MCP server for codebase analysis and code search
npm install @goodfoot/codebase-mcp-serverModel Context Protocol (MCP) server providing intelligent codebase analysis and code search capabilities using Claude Code SDK. This package enables natural language queries to understand, navigate, and analyse codebases effectively.
The codebase MCP server delivers sophisticated code analysis through an intelligent agent that selects and orchestrates the appropriate tools for each query. It provides comprehensive codebase understanding through symbol analysis, dependency mapping, error investigation, and flow tracing.
- Natural Language Queries: Ask questions about your codebase in plain English
- Intelligent Tool Selection: Automatic selection of optimal tools (VSCode LSP, Grep, ast-grep, etc.)
- Symbol Analysis: Understand functions, classes, types, and their relationships
- Dependency Mapping: Trace imports, exports, and module dependencies
- Error Investigation: Analyse TypeScript errors and runtime issues with full context
- Flow Analysis: Understand data flow and execution paths through code
- Configurable Logging: Optional diagnostic logging for troubleshooting
- Query Logs: Complete transcripts of analysis for review and debugging
``bash`
yarn add @goodfoot/codebase-mcp-server
`bash`
npx -y @goodfoot/codebase-mcp-server
The server automatically uses the current working directory as the workspace path.
Configure in your MCP client settings:
`json`
{
"mcpServers": {
"codebase": {
"command": "npx",
"args": ["-y", "@goodfoot/codebase-mcp-server"],
"env": {
"CODEBASE_MCP_SERVER_LOGGING": "false"
}
}
}
}
Searches and analyses codebases to answer technical questions. Optimised for focused questions about specific files, symbols, errors, or code flow.
Parameters:
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------------------------- |
| question | string | Yes | Technical question about the codebase with full file paths in monorepos |
Example Usage:
`typescript
// Investigate TypeScript error
await client.callTool({
name: 'ask',
arguments: {
question: 'TypeScript error TS2322 at packages/api/src/user.ts:45: Why is email required?'
}
});
// Trace dependencies
await client.callTool({
name: 'ask',
arguments: {
question: 'What files import from packages/shared/src/types/user.ts?'
}
});
// Analyse code flow
await client.callTool({
name: 'ask',
arguments: {
question: 'How does the authentication system process login requests?'
}
});
// Find symbol definition and usage
await client.callTool({
name: 'ask',
arguments: {
question: 'Find the definition and all usages of UserService class'
}
});
`
#### CODEBASE_MCP_SERVER_LOGGING
Enables diagnostic logging to stderr.
- Default: false (logging disabled)"true"
- Values: or "false"
- Output: All logs written to stderr with level prefixes
`bash`
CODEBASE_MCP_SERVER_LOGGING=true npx -y @goodfoot/codebase-mcp-server
Log Levels:
- [DEBUG] - Detailed debugging information[INFO]
- - General informational messages[WARN]
- - Warning conditions[ERROR]
- - Error conditions
The server includes comprehensive system instructions that guide the analysis agent to select optimal tools:
Primary Approach: VSCode LSP
1. Use Grep to find where symbol is defined
2. Use get_symbol_lsp_info with definition file pathget_references
3. Use for all usage locations
Example Flow:
``
Question: "Find all references to updateGitAvailability"
→ Grep for "updateGitAvailability" to find definition
→ get_symbol_lsp_info at definition file
→ get_references to find all usages
Use ast-grep for code structure patterns:
- Class inheritance (class X extends Y)class X implements Y
- Interface implementation ()
- Type constraints
- Decorator patterns
Use Grep for:
- console.log statements
- TODO comments
- String literals
- Regular expression patterns
1. Use get_diagnostics to see all errorsget_symbol_lsp_info
2. Use to investigate specific types
3. Analyse type definitions and relationships
- print-dependencies: Show what a file importsprint-inverse-dependencies
- : Show what imports a file (impact analysis)print-typescript-types
- : Analyse exported typesprint-type-analysis
- : Get complexity metrics
Good:
- "TypeScript error TS2322 at packages/api/src/user.ts:45: Why is email required?"
- "What files import from packages/shared/src/types/user.ts?"
- "How does packages/api/src/services/user.ts depend on database types?"
- "Find all implementations of the UserRepository interface"
Less Effective:
- "How does useTranscriptSync work?" (missing full path)
- "Find all bugs" (too vague)
- "Analyse the codebase" (too broad)
Always provide full paths in monorepos:
``
✓ packages/api/src/user.ts
✓ apps/web/src/components/UserProfile.tsx
✗ user.ts
✗ src/user.ts
All questions and analysis transcripts are logged to:
``
/workspace/reports/.codebase-questions/{timestamp}.md
Log Contents:
- Original question (quoted)
- Complete tool execution trace
- Tool call parameters
- Tool responses
- Final analysis answer
Log Format:
``markdown
> What files import from packages/shared/src/types/user.ts?
---
`tool-call`
Grep(
pattern="...",
glob="*/.ts"
)``
`tool-response`
[Tool output]
[Final analysis answer]
``
Enable with CODEBASE_MCP_SERVER_LOGGING=true:
- Server startup and shutdown
- Tool execution details
- Error conditions
- Request cancellations
- Query Logs: /workspace/reports/.codebase-questions/
- Diagnostic Logs: stderr (when enabled)
The server handles request cancellation gracefully:
- Propagates abort signals to Claude Code SDK
- Cleans up resources on cancellation
- Returns proper error messages to clients
- Logs cancellation events (when diagnostic logging enabled)
`typescript
// Client can cancel requests
const controller = new AbortController();
const promise = client.callTool({
name: 'ask',
arguments: {
question: 'Analyse entire codebase'
}
});
// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);
``
The server includes comprehensive system instructions covering:
- When to use VSCode LSP vs Grep vs ast-grep
- Proper workflow for symbol lookups
- Fallback strategies when primary tools fail
- Parallel vs sequential tool execution
- Direct answers with no preamble
- Structured sections with headers
- Code snippets with file:line references
- Evidence-based conclusions
- Zero results documentation
- Tool failure recovery
- Alternative search strategies
| Result Count | Action |
| ------------- | -------------------------------------------- |
| 0 results | State "No results found" with search details |
| 1-5 results | Show all with full context |
| 6-20 results | Show all with brief context |
| 21-50 results | Show first 10 with summary |
| 50+ results | Show first 5 with count and pattern analysis |
Cause: Complex queries requiring many tool invocations
Solution: Be more specific in questions
`bashLess specific (slower)
"How does authentication work?"
$3
Common Causes:
1. Incorrect file paths: Use full paths in monorepos
2. Symbol not in indexed files: Check file extensions and patterns
3. Private/internal symbols: May not be exported or referenced
Verification:
`bash
Check file exists
ls packages/api/src/user.tsCheck symbol exists in file
grep -r "UserService" packages/
`$3
Normal when client cancels long-running requests. Check diagnostic logs for details:
`bash
CODEBASE_MCP_SERVER_LOGGING=true npx -y @goodfoot/codebase-mcp-server
`$3
If analysis seems incomplete:
1. Check query logs for tool execution traces
2. Verify all required files are accessible
3. Ensure VSCode language server is running (for LSP features)
4. Try more specific questions
Development
$3
`bash
yarn build
`$3
`bash
yarn test
`$3
`bash
yarn lint
`Technical Architecture
$3
1. Codebase Server: Main MCP server exposing the
ask tool
2. Query Handler: Processes questions and invokes Claude Code SDK
3. System Instructions: Comprehensive tool selection guide
4. Logger: Optional diagnostic logging system
5. Transcript Writer: Logs all queries and responses$3
1. Client sends question via
ask tool
2. Server constructs system instructions with tool guide
3. Claude Code SDK processes query with available tools
4. Tools execute (Grep, VSCode LSP, ast-grep, etc.)
5. Agent synthesises findings into structured answer
6. Response returned to client
7. Full transcript logged to disk$3
The analysis agent has access to:
- Grep: Text and regex search
- Glob: File pattern matching
- Read: File reading
- Bash: Command execution (git, print-dependencies, etc.)
- VSCode LSP Tools:
-
get_symbol_lsp_info: Symbol definitions and types
- get_references: Find all symbol usages
- get_diagnostics: TypeScript/ESLint errors
- rename_symbol: Rename with reference updates$3
For security and focus:
-
ExitPlanMode: Not applicable for analysis
- KillBash/BashOutput: Background process management
- mcp__codebase__ask: Prevents recursive calls$3
-
@anthropic-ai/claude-agent-sdk: Claude Code SDK for intelligent analysis
- @modelcontextprotocol/sdk: MCP protocol implementation
- zod: Runtime type validation$3
Comprehensive TypeScript types with runtime validation for all parameters.
Performance Characteristics
$3
- Simple symbol lookups: 2-5 seconds
- Dependency analysis: 5-10 seconds
- Flow tracing: 10-30 seconds
- Comprehensive analysis: 30-60 seconds
$3
- Memory: Scales with codebase size and query complexity
- CPU: Bursts during tool execution, idle between queries
- Disk: Query logs accumulate over time
$3
1. Use specific file paths to reduce search scope
2. Ask focused questions rather than broad analysis requests
3. Use monorepo paths (packages/api/src/file.ts) not relative paths
4. Clean up old query logs periodically
Limitations
$3
1. Language Support: Optimised for TypeScript/JavaScript (other languages supported but less optimised)
2. VSCode Dependency: LSP features require VSCode language server
3. Monorepo Paths: Best results with full paths in monorepos
4. Query Complexity: Very broad questions may time out or produce incomplete results
$3
- Multi-language support optimisation
- Caching for frequently accessed symbols
- Incremental analysis for large codebases
- Query result pagination
Use Cases
$3
`typescript
await client.callTool({
name: 'ask',
arguments: {
question: 'What would break if I change the User interface in packages/types/user.ts?'
}
});
`$3
`typescript
await client.callTool({
name: 'ask',
arguments: {
question: 'How does the authentication flow work from login to session creation?'
}
});
`$3
`typescript
await client.callTool({
name: 'ask',
arguments: {
question: 'Why does packages/api/tests/user.test.ts fail with TypeError: Cannot read property "id"?'
}
});
`$3
`typescript
await client.callTool({
name: 'ask',
arguments: {
question: 'Find all usages of the deprecated getUserById function'
}
});
``- Read-only filesystem access
- No file modifications
- No external network requests (except for SDK)
- Process execution limited to analysis tools
- Server operates only within workspace directory
- No access to parent directories
- Log files contained in workspace
MIT
For issues, feature requests, and questions, please refer to the main repository documentation.