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.7 KiB Raw Blame History