# http-mcp-server

A minimal [Model Context Protocol](https://modelcontextprotocol.io) (MCP) HTTP server implementing the [2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) protocol, including the [Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview). Zero runtime dependencies.

## Usage

Run directly with npx (requires Node.js 24+):

```sh
npx http-mcp-server
```

Or install and run:

```sh
npm install -g http-mcp-server
http-mcp-server
```

The server listens on `http://127.0.0.1:8456/mcp`.

## Configuration

| Variable | Default     | Description         |
| -------- | ----------- | ------------------- |
| `PORT`   | `8456`      | Listening port      |
| `HOST`   | `127.0.0.1` | Listening interface |

## Endpoints

- `POST /mcp` — MCP JSON-RPC over HTTP (2026-07-28)
- `POST /mcp-no-tools` — same, but `tools/list` returns no tools (for testing empty-server behavior)
- `GET /mcp` — SSE stream

## Protocol

- **Discovery**: `server/discover` advertises supported protocol versions and the `io.modelcontextprotocol/tasks` extension capability. Legacy `initialize` is also supported.
- **Headers**: requests carrying `MCP-Protocol-Version`, `Mcp-Method`, and `Mcp-Name` headers are validated against the body (`-32020` on mismatch, `-32022` for unsupported versions). Requests without the new-style headers are accepted for backward compatibility.
- **Tasks**: clients that declare `io.modelcontextprotocol/tasks` in their per-request `_meta.io.modelcontextprotocol/clientCapabilities.extensions` receive a task handle (`resultType: "task"`) from `thx_slow_echo` and poll `tasks/get` until a terminal state, answering elicitations via `tasks/update` and cancelling via `tasks/cancel`.

## Tools

| Tool            | Description                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `thx_echo`      | Echoes the given text back as `echo:<text>`                                                                |
| `thx_add`       | Sums `numbers` as `sum:<n>`                                                                                |
| `thx_upper`     | Uppercases `text` as `upper:<TEXT>`                                                                        |
| `thx_time`      | Returns the current UTC time as `time:<ISO 8601>`                                                          |
| `thx_slow_echo` | Async task tool: echoes after `delayMs`; optionally pauses for an approval elicitation (`requireApproval`) |

### `thx_slow_echo` example

```json
{
  "name": "thx_slow_echo",
  "arguments": { "text": "hello", "delayMs": 1000, "requireApproval": false }
}
```

The call returns a task handle:

```json
{
  "result": {
    "resultType": "task",
    "taskId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "working",
    "statusMessage": "echoing 'hello' in 1000ms",
    "createdAt": "2026-08-29T10:30:00Z",
    "lastUpdatedAt": "2026-08-29T10:30:00Z",
    "ttlMs": 3600000,
    "pollIntervalMs": 100
  }
}
```

Poll `tasks/get` until the task reaches `completed`, `failed`, or `cancelled`. With `requireApproval: true` the task enters `input_required` and surfaces an `elicitation/create` request under `inputRequests`; answer it with `tasks/update` and `inputResponses`.

## Development

```sh
npm install
npm test        # run tests
npm run lint    # run eslint
npm run format  # format with prettier
```

## License

MIT