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

// 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

{
	"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:

{
	"mcpServers": {
		"trueref": {
			"type": "http",
			"url": "http://localhost:3001/mcp"
		}
	}
}

Files to Modify

src/mcp/index.ts — add HTTP transport branch and CLI arg parsing

3.6 KiB Raw Blame History