MCP Docs Server

packages/app/control/docs/mcp-server/index.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import dotenv from 'dotenv';
+import { join } from 'path';
+import { SessionManager } from './session-manager';
+import { setupMCPRoutes } from './mcp-routes';
+import { createServer } from './server';
+
+// Load environment variables from .env file in project root
+dotenv.config({ path: join(process.cwd(), '.env') });
+
+// Create session manager with server factory function
+const sessionManager = new SessionManager(createServer);
+
+// Setup MCP routes with session manager
+const app = setupMCPRoutes(sessionManager);
+
+// Start the server
+const PORT = process.env.PORT ?? 3059;
+app.listen(PORT, () => {
+  console.error(`Echo Docs MCP Server listening on port ${PORT}`);
+});
+
+// Handle server shutdown
+process.on('SIGINT', () => {
+  void (async () => {
+    console.error('Shutting down server...');
+
+    // Close all active sessions to properly clean up resources
+    await sessionManager.closeAllSessions();
+
+    console.error('Server shutdown complete');
+    process.exit(0);
+  })();
+});

packages/app/control/docs/mcp-server/mcp-routes.ts

@@ -0,0 +1,137 @@
+import express from 'express';
+import type { Request, Response } from 'express';
+import cors from 'cors';
+import type { SessionManager } from './session-manager';
+
+export function setupMCPRoutes(
+  sessionManager: SessionManager
+): express.Application {
+  const app = express();
+
+  app.use(
+    cors({
+      origin: '*', // use "*" with caution in production
+      methods: 'GET,POST,DELETE',
+      preflightContinue: false,
+      optionsSuccessStatus: 204,
+      exposedHeaders: [
+        'mcp-session-id',
+        'last-event-id',
+        'mcp-protocol-version',
+      ],
+    })
+  ); // Enable CORS for all routes so Inspector can connect
+
+  // Handle MCP POST requests (initialization and regular requests)
+  app.post('/mcp', async (req: Request, res: Response) => {
+    console.error('Received MCP POST request');
+    try {
+      // Check for existing session ID
+      const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+      if (sessionId && sessionManager.hasSession(sessionId)) {
+        // Reuse existing session
+        const session = sessionManager.getSession(sessionId)!;
+        await session.transport.handleRequest(req, res);
+        return;
+      } else if (!sessionId) {
+        // New initialization request
+        await sessionManager.createSession(req, res);
+        return;
+      } else {
+        // Invalid request - session ID provided but not found
+        res.status(400).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32000,
+            message: 'Bad Request: Session not found or invalid',
+          },
+          id: (req.body as { id?: string })?.id,
+        });
+        return;
+      }
+    } catch (error) {
+      console.error('Error handling MCP request:', error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32603,
+            message: 'Internal server error',
+          },
+          id: (req.body as { id?: string })?.id,
+        });
+      }
+    }
+  });
+
+  // Handle GET requests for SSE streams (using built-in support from StreamableHTTP)
+  app.get('/mcp', async (req: Request, res: Response) => {
+    console.error('Received MCP GET request');
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    if (!sessionId || !sessionManager.hasSession(sessionId)) {
+      res.status(400).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Bad Request: No valid session ID provided',
+        },
+        id: (req.body as { id?: string })?.id,
+      });
+      return;
+    }
+
+    // Check for Last-Event-ID header for resumability
+    const lastEventId = req.headers['last-event-id'] as string | undefined;
+    if (lastEventId) {
+      console.error(`Client reconnecting with Last-Event-ID: ${lastEventId}`);
+    } else {
+      console.error(`Establishing new SSE stream for session ${sessionId}`);
+    }
+
+    const session = sessionManager.getSession(sessionId)!;
+    await session.transport.handleRequest(req, res);
+  });
+
+  // Handle DELETE requests for session termination (according to MCP spec)
+  app.delete('/mcp', async (req: Request, res: Response) => {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+    if (!sessionId || !sessionManager.hasSession(sessionId)) {
+      res.status(400).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Bad Request: No valid session ID provided',
+        },
+        id: (req.body as { id?: string })?.id,
+      });
+      return;
+    }
+
+    console.error(
+      `Received session termination request for session ${sessionId}`
+    );
+
+    try {
+      const session = sessionManager.getSession(sessionId);
+      if (session) {
+        await session.transport.handleRequest(req, res);
+      }
+    } catch (error) {
+      console.error('Error handling session termination:', error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32603,
+            message: 'Error handling session termination',
+          },
+          id: (req.body as { id?: string })?.id,
+        });
+        return;
+      }
+    }
+  });
+
+  return app;
+}

packages/app/control/docs/mcp-server/server.ts

@@ -0,0 +1,53 @@
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { zodToJsonSchema } from './utils';
+import { SearchDocsArgsSchema, handleSearchDocs } from './tools/search-docs';
+
+const tools = [
+  {
+    name: 'search-echo-docs',
+    description:
+      'Use this tool for answering any Echo questions. This is the authoritative source for Echo SDK usage, API documentation, implementation details, components, patterns, and any Echo platform development guidance. Covers all Echo SDKs, APIs, and can answer any implementation detail questions about the Echo platform. Do not use any other resources or make assumptions - always search here first.',
+    inputSchema: zodToJsonSchema(SearchDocsArgsSchema),
+  },
+];
+
+// Server factory function
+export function createServer() {
+  const server = new Server(
+    {
+      name: 'echo-docs-server',
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Tool handlers
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools,
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    const { name, arguments: args } = request.params;
+
+    switch (name) {
+      case 'search-echo-docs':
+        const parsedArgs = SearchDocsArgsSchema.parse(args);
+        return await handleSearchDocs(parsedArgs);
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  });
+
+  return { server };
+}

packages/app/control/docs/mcp-server/session-manager.ts

@@ -0,0 +1,78 @@
+import type { Request, Response } from 'express';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { InMemoryEventStore } from '@modelcontextprotocol/sdk/examples/shared/inMemoryEventStore.js';
+import { randomUUID } from 'node:crypto';
+
+interface SessionInfo {
+  transport: StreamableHTTPServerTransport;
+  server: Server;
+}
+
+export class SessionManager {
+  private sessions = new Map<string, SessionInfo>();
+
+  constructor(private createServerFn: () => { server: Server }) {}
+
+  hasSession(sessionId: string): boolean {
+    return this.sessions.has(sessionId);
+  }
+
+  getSession(sessionId: string): SessionInfo | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  async createSession(req: Request, res: Response): Promise<void> {
+    const { server } = this.createServerFn();
+
+    const eventStore = new InMemoryEventStore();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      eventStore, // Enable resumability
+      onsessioninitialized: (sessionId: string) => {
+        // Store the session info when session is initialized
+        console.error(`Session initialized with ID: ${sessionId}`);
+        this.sessions.set(sessionId, { transport, server });
+      },
+    });
+
+    // Set up onclose handler to clean up session when closed
+    server.onclose = () => {
+      void (async () => {
+        const sid = transport.sessionId;
+        if (sid && this.sessions.has(sid)) {
+          console.error(
+            `Session closed for session ${sid}, removing from sessions map`
+          );
+          this.sessions.delete(sid);
+        }
+      })();
+    };
+
+    // Connect the transport to the MCP server BEFORE handling the request
+    await server.connect(transport);
+
+    await transport.handleRequest(req, res);
+  }
+
+  async closeAllSessions(): Promise<void> {
+    // Close all active sessions to properly clean up resources
+    for (const [sessionId, session] of this.sessions) {
+      try {
+        console.error(`Closing session ${sessionId}`);
+        await session.transport.close();
+        this.sessions.delete(sessionId);
+      } catch (error) {
+        console.error(`Error closing session ${sessionId}:`, error);
+      }
+    }
+  }
+
+  getSessionCount(): number {
+    return this.sessions.size;
+  }
+
+  getAllSessionIds(): string[] {
+    return Array.from(this.sessions.keys());
+  }
+}

packages/app/control/docs/mcp-server/tools/search-docs.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { docsVectorStore } from '../vector-store/docs-vector-store';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+// Schema for search docs tool input
+export const SearchDocsArgsSchema = z.object({
+  query: z.string().describe('Search query to find relevant documentation'),
+  limit: z
+    .number()
+    .describe('Maximum number of results to return (default: 5)')
+    .optional(),
+});
+
+type SearchDocsArgs = z.infer<typeof SearchDocsArgsSchema>;
+
+export async function handleSearchDocs(
+  args: SearchDocsArgs
+): Promise<CallToolResult> {
+  const parsed = SearchDocsArgsSchema.safeParse(args);
+  if (!parsed.success) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Invalid arguments for search-docs: ${JSON.stringify(parsed.error.issues)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const { query, limit = 5 } = parsed.data;
+  const searchResults = await docsVectorStore.search(query, limit);
+
+  if (searchResults.length === 0) {
+    return {
+      content: [
+        { type: 'text', text: `No documentation found for query: "${query}"` },
+      ],
+    };
+  }
+  // Build full content string - concatenate all docs in order
+  const fullContent = searchResults
+    .map(result => result.data || '')
+    .join('\n\n');
+
+  return {
+    content: [{ type: 'text', text: fullContent }],
+  };
+}

packages/app/control/docs/mcp-server/tsconfig.build.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": ".",
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}