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**:
```json
{
  "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**:
```typescript
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**:
```json
{
  "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**:
```typescript
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**:
```json
{
  "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**:
```typescript
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**:
```json
{
  "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**:
```typescript
{
  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`:

```javascript
{
  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