149 lines
3.6 KiB
Markdown
149 lines
3.6 KiB
Markdown
# TRUEREF-0012 — MCP Server (HTTP Transport)
|
|
|
|
**Priority:** P1
|
|
**Status:** Pending
|
|
**Depends On:** TRUEREF-0011
|
|
**Blocks:** —
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Extend the MCP server to support an HTTP/SSE transport in addition to the stdio transport from TRUEREF-0011. This allows TrueRef to be used as a remote MCP server (similar to `mcp.context7.com`) without requiring local installation of the MCP binary on the client machine.
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] HTTP transport alongside existing stdio transport (flag-based selection)
|
|
- [ ] `--transport http` and `--port <n>` CLI flags
|
|
- [ ] Streamable HTTP transport via `@modelcontextprotocol/sdk` `StreamableHTTPServerTransport`
|
|
- [ ] `/mcp` endpoint handles MCP protocol over HTTP
|
|
- [ ] `/ping` health check endpoint returns `{ "ok": true }`
|
|
- [ ] Default port 3001 (to avoid conflict with SvelteKit dev server on 5173)
|
|
- [ ] CORS headers on `/mcp` for browser-based clients
|
|
- [ ] `npm run mcp:http` script for convenience
|
|
- [ ] Docker-friendly: reads `PORT` env var
|
|
|
|
---
|
|
|
|
## CLI Interface
|
|
|
|
```
|
|
node dist/mcp/index.js [--transport stdio|http] [--port 3001]
|
|
|
|
Options:
|
|
--transport Transport mode: 'stdio' (default) or 'http'
|
|
--port Port for HTTP transport (default: 3001, env: PORT)
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation
|
|
|
|
```typescript
|
|
// src/mcp/index.ts (extended)
|
|
|
|
import { parseArgs } from 'node:util';
|
|
import { createServer } from 'node:http';
|
|
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
|
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
|
|
const { values: args } = parseArgs({
|
|
options: {
|
|
transport: { type: 'string', default: 'stdio' },
|
|
port: { type: 'string', default: process.env.PORT ?? '3001' }
|
|
}
|
|
});
|
|
|
|
async function startHttp(server: Server, port: number): Promise<void> {
|
|
const httpServer = createServer(async (req, res) => {
|
|
const url = new URL(req.url!, `http://localhost:${port}`);
|
|
|
|
// Health check
|
|
if (url.pathname === '/ping') {
|
|
res.writeHead(200, { 'Content-Type': 'application/json' });
|
|
res.end(JSON.stringify({ ok: true }));
|
|
return;
|
|
}
|
|
|
|
// MCP endpoint
|
|
if (url.pathname === '/mcp') {
|
|
// CORS preflight
|
|
res.setHeader('Access-Control-Allow-Origin', '*');
|
|
res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
|
|
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept');
|
|
|
|
if (req.method === 'OPTIONS') {
|
|
res.writeHead(204);
|
|
res.end();
|
|
return;
|
|
}
|
|
|
|
const transport = new StreamableHTTPServerTransport({
|
|
sessionIdGenerator: () => crypto.randomUUID()
|
|
});
|
|
|
|
await server.connect(transport);
|
|
await transport.handleRequest(req, res);
|
|
return;
|
|
}
|
|
|
|
res.writeHead(404);
|
|
res.end('Not Found');
|
|
});
|
|
|
|
httpServer.listen(port, () => {
|
|
process.stderr.write(`TrueRef MCP server listening on http://localhost:${port}/mcp\n`);
|
|
});
|
|
}
|
|
|
|
async function main() {
|
|
const mcpServer = createMcpServer(); // shared server creation
|
|
|
|
if (args.transport === 'http') {
|
|
const port = parseInt(args.port!, 10);
|
|
await startHttp(mcpServer, port);
|
|
} else {
|
|
const transport = new StdioServerTransport();
|
|
await mcpServer.connect(transport);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Package.json Scripts
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"mcp:start": "tsx src/mcp/index.ts",
|
|
"mcp:http": "tsx src/mcp/index.ts --transport http --port 3001"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Remote Integration (Claude Code)
|
|
|
|
For HTTP transport, users configure Claude Code with the remote URL:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"trueref": {
|
|
"type": "http",
|
|
"url": "http://localhost:3001/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Files to Modify
|
|
|
|
- `src/mcp/index.ts` — add HTTP transport branch and CLI arg parsing
|