# 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