mcp-from-scratch

This MCP server provides a foundational implementation of the Model Context Protocol (MCP) designed for learning and experimentation. It supports standard MCP tooling concepts such as tool registration, structured input/output according to JSON schemas, and both STDIO and HTTP/S transports for communication between the client (LLM) and the server. You can run the server locally and use its tooling surface to discover registered tools, invoke them through the MCP protocol, and observe how responses are shaped by explicit input/output schemas and error models. The included setup is geared toward exploring safe and scalable tool integrations, permission boundaries, and the flow of structured data between AI models and external utilities.

To interact, start the server with the provided command and connect a client (such as an MCP-aware LLM or a CLI tool) over HTTP or STDIO. Use the discovery mechanism to enumerate available tools, send tool invocation requests with the required input, and receive validated, schema-driven outputs. The server is designed to illustrate common MCP patterns: stateless request handling, clear tool definitions, transport-appropriate message framing, and structured error handling that helps prevent hallucinations during tool calls.

Prerequisites:

• Node.js (14.x or newer) installed on your machine
• Basic familiarity with running Node.js applications

Installation steps:

1. Clone the repository: git clone https://github.com/bhuvan-raj/mcp-from-scratch.git cd mcp-from-scratch

2. Install dependencies: npm install

3. Configure environment (optional):

   • Create a .env file or export variables as needed
   • Example: export MCP_ENV=production export PORT=3000

4. Start the MCP server: npm run start or if a direct node script is provided: node server.js

5. Verify the server is running (default port 3000): curl http://localhost:3000/health

Notes:

• If your setup uses a different entry point or custom scripts, adjust the start command accordingly.
• Ensure any required tool definitions are registered before attempting tool invocations.

Tips and common considerations:

• Transport choices: The server supports STDIO and HTTP transports; choose based on your client integration needs.
• Schema-driven safety: Rely on the defined input/output schemas to prevent invalid data or unsafe tool usage.
• Environment variables: Use MCP_ENV to switch between environments (development, staging, production) and PORT to expose the correct endpoint.
• Troubleshooting: If tool discovery fails, verify the tool registration phase and confirm the server is reachable on the configured port. Check logs for schema validation errors or permission-related messages.
• Extensibility: This setup is intended as a learning scaffold; you can extend it by adding new tools, richer error models, and additional transports to reflect real-world MCP deployments.