# 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](/Users/sagar/Documents/Learning/MCP-Server/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](/Users/sagar/Documents/Learning/MCP-Server/index.js:41)).

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

  Uncomment the call to `runServeronSTDIOTransport()` in [index.js](/Users/sagar/Documents/Learning/MCP-Server/index.js:53-54) 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](/Users/sagar/Documents/Learning/MCP-Server/index.js:45-50)). 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](/Users/sagar/Documents/Learning/MCP-Server/index.js:11-32) 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](/Users/sagar/Documents/Learning/MCP-Server/index.js:11-31)):

```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.