mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
Add tests and documentation for CodexLens LSP tool
- Introduced a new test script for the CodexLens LSP tool to validate core functionalities including symbol search, find definition, find references, and get hover. - Created comprehensive documentation for the MCP endpoint design, detailing the architecture, features, and integration with the CCW MCP Manager. - Developed a detailed implementation plan for transitioning to a real LSP server, outlining phases, architecture, and acceptance criteria.
This commit is contained in:
catlog22
284
codex-lens/docs/MCP_ENDPOINT_DESIGN.md
Normal file
284
codex-lens/docs/MCP_ENDPOINT_DESIGN.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user