03-mcp-server

MCP Server Rules (src/mcp-server.ts)

Last reviewed: 2025-08-11 Timestamp: 2025-08-11T08:21:00-04:00

These rules align src/mcp-server.ts with @modelcontextprotocol/sdk best practices and your project’s research pipeline.

Scope & Goals

• Ensure the server exposes a clean, testable tool interface for deep research.
• Favor stdio transport for local/CLI and consider Streamable HTTP for deployment.
• Keep outputs deterministic, cache-aware, and friendly for agent clients.

Project Flow Overview (Current Code)

• src/mcp-server.ts registers a single tool deep-research using server.tool(...).
• Tool handler calls research() and writeFinalReport() from src/deep-research.ts.
• Caching via LRUCache in mcp-server.ts with key JSON.stringify({ query, depth, breadth, existingLearnings }).
• Transport: StdioServerTransport(process.stdin, process.stdout) with server.connect(transport). This matches current code. Using new StdioServerTransport() without args is also valid per SDK docs.
• Logging: helper log() writes to stderr; progress notifications are logged only (no custom notifications emitted).
• Current search provider in orchestrator: Firecrawl (migration to Exa planned; see Notes).

Agents & Tools Summary

• Tools exposed: one MCP tool deep-research.
• Orchestrator: research(options) in src/deep-research.ts (batches Gemini via generateBatch(); uses text splitters; composes final via writeFinalReport()).
• Feedback helper: generateFeedback() in src/feedback.ts (not exposed as MCP tool by default).

Server & Transport

• Instantiate server with name/version and optional debounced notifications:

  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
  
  const server = new McpServer(
    { name: 'deep-research', version: '1.0.0' },
    {
      // Reduce message spam during rapid list changes
      debouncedNotificationMethods: [
        'notifications/tools/list_changed',
        'notifications/resources/list_changed',
        'notifications/prompts/list_changed'
      ]
    }
  );
  
  // Current code passes streams explicitly; either form is acceptable
  const transport = new StdioServerTransport(process.stdin, process.stdout);
  await server.connect(transport);
  

  • SDK also supports new StdioServerTransport() without args. Current code uses explicit streams; both are valid.
  • Prefer await server.connect(transport) (async) vs promise chaining for clarity.