# Node.js MCP Server

A small, stateless Model Context Protocol server built with Node.js, Express and the official MCP SDK. It is intended as a practical starting point: every tool has validated parameters, and the integration suite talks to a real local server through the MCP client transport.

## Requirements

- Node.js 18 or newer
- npm

## Run locally

```bash
npm install
npm start
```

The server listens on port `3000` by default. Override it with `PORT=8080 npm start`.

Endpoints:

- `GET /health` - HTTP health check
- `POST /mcp` - stateless Streamable HTTP MCP endpoint

## Example tools

| Tool | What it demonstrates |
| --- | --- |
| `getCurrentTime` | Defaults, locale and IANA timezone parameters, structured output |
| `formatText` | Enum operations, optional decoration, bounded repeat count |
| `calculate` | Numeric parameters, rounding and an MCP tool error |

Every successful call returns text containing JSON, `structuredContent`, and `isError: false`. Expected tool failures still use HTTP 200 and return JSON such as `{"error":"Division by zero is not allowed."}` in the text content with `isError: true`.

Example arguments:

```json
{
  "operation": "divide",
  "a": 10,
  "b": 3,
  "precision": 3
}
```

## Integration tests

```bash
npm test
```

The Mocha suite starts `index.mjs` as a child process on an available local port, waits until it is ready, connects with the official MCP client, exercises the health endpoint and tools, then shuts the process down in teardown. Chai is used for assertions.

## MCP client URL

```text
http://localhost:3000/mcp
```

The example is stateless: every MCP request gets a fresh server and transport.

## License

MIT