Claude-Code-Workflow/codex-lens/docs/MCP_ENDPOINT_DESIGN.md

CodexLens MCP Endpoint Design

Generated by Gemini Analysis | 2026-01-19 Document Version: 1.0

Overview

This document provides the complete MCP endpoint design for exposing codex-lens LSP capabilities through the Model Context Protocol.

Related Files

• src/codexlens/lsp/server.py - Main LSP server initialization, component management, and capability declaration.
• src/codexlens/lsp/handlers.py - Implementation of handlers for core LSP requests (definition, references, completion, hover, workspace symbols).
• src/codexlens/lsp/providers.py - Helper classes, specifically HoverProvider for generating rich hover information.
• src/codexlens/storage/global_index.py - The backing data store (GlobalSymbolIndex) that powers most of the symbol lookups.
• src/codexlens/search/__init__.py - Exposes the ChainSearchEngine, used for advanced reference searching.

Summary

The codex-lens LSP implementation exposes five core code navigation and search features: go to definition, find references, code completion, hover information, and workspace symbol search. These features are primarily powered by two components: GlobalSymbolIndex for fast, project-wide symbol lookups (used by definition, completion, hover, and workspace symbols) and ChainSearchEngine for advanced, relationship-aware reference finding.

The following MCP tool design externalizes these backend capabilities, allowing a client to leverage the same code intelligence features outside of an LSP context.

MCP Tool Group: code.symbol

This group provides tools for searching and retrieving information about code symbols (functions, classes, etc.) within an indexed project.

---

1. code.symbol.search

Description: Searches for symbols across the entire indexed project, supporting prefix or contains matching. Ideal for implementing workspace symbol searches or providing code completion suggestions.

Mapped LSP Features: workspace/symbol, textDocument/completion

Backend Implementation: This tool directly maps to the GlobalSymbolIndex.search method.

• Reference: src/codexlens/lsp/handlers.py:302 (in lsp_workspace_symbol)
• Reference: src/codexlens/lsp/handlers.py:256 (in lsp_completion)

Schema:

{
  "name": "code.symbol.search",
  "description": "Searches for symbols across the entire indexed project, supporting prefix or contains matching. Ideal for implementing workspace symbol searches or providing code completion suggestions.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The symbol name or prefix to search for."
      },
      "kind": {
        "type": "string",
        "description": "Optional: Filter results to only include symbols of a specific kind (e.g., 'function', 'class', 'method').",
        "nullable": true
      },
      "prefix_mode": {
        "type": "boolean",
        "description": "If true, treats the query as a prefix (name LIKE 'query%'). If false, performs a contains search (name LIKE '%query%'). Defaults to true.",
        "default": true
      },
      "limit": {
        "type": "integer",
        "description": "The maximum number of symbols to return.",
        "default": 50
      }
    },
    "required": ["query"]
  }
}

Returns:

Array<{
  name: string;          // The name of the symbol
  kind: string;          // The kind of the symbol (e.g., 'function', 'class')
  file_path: string;     // The absolute path to the file containing the symbol
  range: {
    start_line: number;  // The 1-based starting line number
    end_line: number;    // The 1-based ending line number
  }
}>

---

2. code.symbol.findDefinition

Description: Finds the definition location(s) for a symbol with an exact name match. This corresponds to a 'Go to Definition' feature.

Mapped LSP Feature: textDocument/definition

Backend Implementation: This tool uses GlobalSymbolIndex.search with prefix_mode=False and then filters for an exact name match.

• Reference: src/codexlens/lsp/handlers.py:180 (in lsp_definition)

Schema:

{
  "name": "code.symbol.findDefinition",
  "description": "Finds the definition location(s) for a symbol with an exact name match. This corresponds to a 'Go to Definition' feature.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol_name": {
        "type": "string",
        "description": "The exact name of the symbol to find."
      },
      "kind": {
        "type": "string",
        "description": "Optional: Disambiguate by providing the symbol kind (e.g., 'function', 'class').",
        "nullable": true
      }
    },
    "required": ["symbol_name"]
  }
}

Returns:

Array<{
  name: string;          // The name of the symbol
  kind: string;          // The kind of the symbol
  file_path: string;     // The absolute path to the file
  range: {
    start_line: number;  // The 1-based starting line number
    end_line: number;    // The 1-based ending line number
  }
}>

---

3. code.symbol.findReferences

Description: Finds all references to a symbol throughout the project. Uses advanced relationship analysis for accuracy where possible, falling back to name-based search.

Mapped LSP Feature: textDocument/references

Backend Implementation: This primarily uses ChainSearchEngine.search_references for accuracy, which is more powerful than a simple name search.

• Reference: src/codexlens/lsp/handlers.py:218 (in lsp_references)

Schema:

{
  "name": "code.symbol.findReferences",
  "description": "Finds all references to a symbol throughout the project. Uses advanced relationship analysis for accuracy where possible.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol_name": {
        "type": "string",
        "description": "The name of the symbol to find references for."
      },
      "context_path": {
        "type": "string",
        "description": "The source path of the current project or workspace root to provide context for the search."
      },
      "limit": {
        "type": "integer",
        "description": "The maximum number of references to return.",
        "default": 200
      }
    },
    "required": ["symbol_name", "context_path"]
  }
}

Returns:

Array<{
  file_path: string;    // The absolute path to the file containing the reference
  line: number;         // The 1-based line number of the reference
  column: number;       // The 0-based starting column of the reference
}>

---

4. code.symbol.getHoverInfo

Description: Retrieves rich information for a symbol, including its signature and location, suitable for displaying in a hover card.

Mapped LSP Feature: textDocument/hover

Backend Implementation: This tool encapsulates the logic from HoverProvider, which finds a symbol in GlobalSymbolIndex and then reads the source file to extract its signature.

• Reference: src/codexlens/lsp/handlers.py:285 (instantiates HoverProvider)
• Reference: src/codexlens/lsp/providers.py:53 (in HoverProvider.get_hover_info)

Schema:

{
  "name": "code.symbol.getHoverInfo",
  "description": "Retrieves rich information for a symbol, including its signature and location, suitable for displaying in a hover card.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol_name": {
        "type": "string",
        "description": "The exact name of the symbol to get hover information for."
      }
    },
    "required": ["symbol_name"]
  }
}

Returns:

{
  name: string;           // The name of the symbol
  kind: string;           // The kind of the symbol
  signature: string;      // The full code signature as extracted from source
  file_path: string;      // The absolute path to the file
  start_line: number;     // The 1-based starting line number
} | null  // null if symbol not found

---

Integration with CCW MCP Manager

The codex-lens-tools MCP server should be added to the recommended MCP servers list in ccw/src/templates/dashboard-js/components/mcp-manager.js:

{
  id: 'codex-lens-tools',
  nameKey: 'mcp.codexLens.name',
  descKey: 'mcp.codexLens.desc',
  icon: 'search-code',
  category: 'code-intelligence',
  fields: [
    {
      key: 'toolSelection',
      labelKey: 'mcp.codexLens.field.tools',
      type: 'multi-select',
      options: [
        { value: 'symbol.search', label: 'Symbol Search' },
        { value: 'symbol.findDefinition', label: 'Find Definition' },
        { value: 'symbol.findReferences', label: 'Find References' },
        { value: 'symbol.getHoverInfo', label: 'Hover Information' }
      ],
      default: ['symbol.search', 'symbol.findDefinition', 'symbol.findReferences'],
      required: true,
      descKey: 'mcp.codexLens.field.tools.desc'
    }
  ],
  buildConfig: (values) => {
    const tools = values.toolSelection || [];
    const env = { CODEXLENS_ENABLED_TOOLS: tools.join(',') };
    return buildCrossPlatformMcpConfig('npx', ['-y', 'codex-lens-mcp'], { env });
  }
}

Tool Naming Convention

• Namespace: code.* for code intelligence tools
• Category: symbol for symbol-related operations
• Operation: Descriptive verb (search, findDefinition, findReferences, getHoverInfo)
• Full Pattern: code.symbol.<operation>

This naming scheme aligns with MCP conventions and is easily extensible for future categories (e.g., code.types.*, code.imports.*).

Future Enhancements

1. Document Symbol Tool (code.symbol.getDocumentSymbols)

   • Maps LSP textDocument/documentSymbol
   • Returns all symbols in a specific file

2. Type Information (code.type.* group)

   • Type definitions and relationships
   • Generic resolution

3. Relationship Analysis (code.relation.* group)

   • Call hierarchy
   • Inheritance chains
   • Import dependencies

---

Generated: 2026-01-19 Status: Ready for Implementation