chore: initial project scaffold

docs/features/TRUEREF-0012.md

@@ -0,0 +1,148 @@
+# 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