first-mcp-server

Project summary

• A minimal MCP (Model Context Protocol) server exposing a single tool named add that adds two numbers and returns the result as text.
• Built with @modelcontextprotocol packages and zod for input validation.

Key files

• index.js — main server file that registers the add tool and starts the server.

Requirements

• Node.js 16+ (recommend LTS)
• npm or yarn

Install

1. Clone the repository and change into the project directory:

   git clone <repo-url> && cd /Users/sagar/Documents/Learning/MCP-Server

2. Install dependencies (example with npm):

   npm install

Dependencies used in this project (examples from code):

• @modelcontextprotocol/server
• @modelcontextprotocol/server/stdio (stdio transport)
• @modelcontextprotocol/express (express helper)
• @modelcontextprotocol/node (Node HTTP transport)
• zod (validation)

Run

• Default HTTP transport (as the project currently starts):

  node index.js

  The server listens on port 3001 and mounts the MCP endpoint at /mcp (see index.js).

• STDIO transport (useful for local CLI-style integrations):

  Uncomment the call to runServeronSTDIOTransport() in index.js and run:

  node index.js

Usage examples

1. HTTP example (curl)

• Request payload (JSON):

  { "tool": "add", "input": { "num1": 10, "num2": 20 } }

• Example curl call (adjust hostname/port if needed):

  curl -X POST http://localhost:3001/mcp
  -H "Content-Type: application/json"
  -d '{"tool":"add","input":{"num1":10,"num2":20}}'

• Expected response (the server's tool returns a content array of text blocks):

  { "content": [ { "type": "text", "text": "30" } ] }

Notes: index.js wires the HTTP transport using NodeStreamableHTTPServerTransport and calls transport.handleRequest(req, res, req.body) (see index.js). The exact envelope the transport expects depends on the @modelcontextprotocol/node transport implementation; the example above follows the simple shape used in this project (tool + input).

2. STDIO example (local CLI integration)

• The project contains a helper to run the server over STDIO using StdioServerTransport. If started in STDIO mode, the server expects JSON requests on stdin and replies on stdout. The tool registered in index.js validates inputs with zod and returns the sum as text.

Tool details (from code)

• Tool name: "add"
• Description: "Add two numbers"
• Input schema (zod):
  • num1: number
  • num2: number

Implementation snippet (from index.js):

server.registerTool(
  "add",
  {
    title: "add",
    description: "Add two numbers",
    inputSchema: z.object({ num1: z.number(), num2: z.number() }),
  },
  async (ctx) => ({
    content: [{ type: "text", text: `${ctx.num1 + ctx.num2}` }],
  }),
);

Notes:

• Validation: zod already validates the inputs. Ensure callers send numeric values and handle validation errors gracefully.
• Error handling: Add try/catch around transport.handleRequest and tool handlers to return consistent error payloads and HTTP status codes (4xx for client errors, 5xx for server errors).
• Logging & monitoring: Add structured logging, request IDs, and basic metrics to monitor usage and errors.
• Security: If exposed publicly, protect the /mcp endpoint (authentication, rate-limiting) and run behind a reverse proxy.
• Tests: Add unit tests for tool handlers and integration tests for transports (HTTP and STDIO).

Contributing

• Open issues or PRs for feature requests or fixes.