Intelligent Context MCP

A comprehensive Model Context Protocol (MCP) server by Wildcard Corporation that provides advanced codebase indexing and semantic search with slash commands and natural language interface for Claude Code.


🎯 Features

$3

- Slash Commands: /index, /search, /status, /clear, /context, /deps, /help
- Natural Language: "Find authentication functions", "Index my codebase"
- Traditional MCP Tools: Direct tool calls for programmatic access

$3

- Tree-sitter semantic chunking - AST-based code chunking creating meaningful units (complete functions, classes, interfaces)
- Smart token limit handling - Automatic content truncation with intelligent boundary detection for API limits
- Content quality filtering - Excludes test files, generated code, and low-quality content
- Dependency graph analysis - Cross-file relationship mapping and context expansion
- Incremental indexing - Only re-indexes changed files and dependencies
- Multi-strategy search - Semantic, hybrid, BM25, and structural search options

$3

- Result Reranking - Jina reranker-v2 optimizes relevance scoring
- Local BM25 Search - SQLite full-text search for exact keyword matching
- Hybrid Fusion - Combines vector similarity with BM25 for best results

$3

- Real API integration - Jina AI embeddings + Turbopuffer vector storage
- Multi-language support - 30+ programming languages with Tree-sitter parsing
- Error handling - Graceful degradation and comprehensive error reporting
- Performance optimized - Batch processing and intelligent caching

🚀 Installation & Setup

$3

``bash
npm install
npm run build
`

$3

#### Required APIs:
- Jina AI: Get your API key from Jina AI - For embeddings and reranking
- Turbopuffer: Get your API key from Turbopuffer - For vector storage

$3

`bash

Install via npm

npm install -g @wildcard-corp/intelligent-context-mcp

Add to Claude Code

claude mcp add intelligent-context \\
-e JINA_API_KEY=your-jina-key \\
-e TURBOPUFFER_API_KEY=your-turbopuffer-key \\
-- npx @wildcard-corp/intelligent-context-mcp
`

🎮 Usage

$3

Execute commands using slash syntax:

`bash


Index your codebase with intelligent chunking

/index /path/to/your/project

Search with semantic understanding

/search authentication implementation
/search user registration flow
/search database connection setup

Check indexing status

/status
/status /specific/project/path

Get focused context for specific files or symbols

/context src/auth.js --with-deps
/context UserService --window=10

Analyze dependencies

/deps src/user.js --reverse
/deps AuthController --graph

Clear index data

/clear --confirm
/clear /path/to/project --confirm

Get help

/help
/help search
`

$3

Use conversational queries:

`bash
"Find all authentication functions"
"Show me the user registration flow"
"Index my codebase at /path/to/project"
"What's the status of my index?"
"Get context for the login function"
`

$3

Direct tool calls for programmatic access:

- execute_slash_command - Execute any slash command
- natural_language_query - Process natural language queries
- index_codebase_intelligent - Direct indexing (legacy)
- search_with_intelligence - Direct search (legacy)

⚙️ Configuration

$3

| Variable | Required | Description |
|----------|----------|-------------|
| JINA_API_KEY | ✅ | Your Jina AI API key for embeddings |
| TURBOPUFFER_API_KEY | ✅ | Your Turbopuffer API key for vector storage |
| LOG_LEVEL | ❌ | Logging level: debug, info, warn, error (default: info) |
| CODEX_CONTEXT_DATA_DIR | ❌ | Data storage directory (default: ~/.codex-context) |

$3

- Jina AI Embeddings: Uses jina-embeddings-v3 model with 1024 dimensions
- Turbopuffer Storage: Vector storage with cosine distance similarity
- Tree-sitter Parsing: AST parsing for accurate symbol extraction

🏗️ Architecture

$3

`mermaid
graph TD
A[Claude Code CLI] --> B[Enhanced MCP Interface]
B --> C{Interface Type}
C -->|Slash Commands| D[Command Parser]
C -->|Natural Language| E[NL Interpreter]
C -->|Direct Tools| F[Tool Handler]
D --> G[Integration Bridge]
E --> G
F --> G
G --> H[Core Components]
H --> I[IndexingOrchestrator]
H --> J[SemanticSearchEngine]
H --> K[TreeSitterSymbolExtractor]
I --> L[Real APIs]
J --> L
K --> L
`

$3

1. Enhanced MCP Interface (src/enhanced-mcp.ts)
- Primary interface with slash commands and natural language
- MCP protocol handling and state management
- Command registry with extensible architecture

2. Integration Bridge (src/standalone-mcp-integration.ts)
- Connects interface layer with core components
- Real API integration (Jina AI + Turbopuffer)
- Data format conversion and error handling

3. Core Intelligence Components (src/core/)
- IndexingOrchestrator: Advanced codebase indexing
- SemanticSearchEngine: Multi-strategy intelligent search
- TreeSitterSymbolExtractor: AST-based symbol extraction
- ContentFilterProvider: Quality filtering and noise reduction
- IncrementalIndexer: Efficient change detection and updates

📊 Performance & Quality

$3

- Symbol-boundary chunking: No arbitrary line splits
- Content filtering: Excludes ~40% of noise (tests, configs, generated code)
- Incremental updates: Only processes changed files
- Batch processing: Optimized API calls and vector uploads

$3

- Multi-stage ranking: Vector similarity + optional reranking
- Dependency expansion: Finds related code across file boundaries
- Context windows: Configurable context around matches
- Symbol awareness: Understands code structure and relationships

🔍 Examples

$3

`bash
/index /path/to/react-app --force

✅ Successfully indexed 1,247 files into 3,821 intelligent chunks

🔍 Ready for intelligent search with /search


`

$3

`bash
/search user authentication login

🔍 Found 15 results (234ms):

#

src/auth/AuthService.ts:45-67 (0.923)

`typescript

async authenticateUser(credentials: LoginCredentials): Promise {

const user = await this.userRepository.findByEmail(credentials.email);

if (!user || !await this.verifyPassword(credentials.password, user.hashedPassword)) {

throw new UnauthorizedError('Invalid credentials');

}

return this.generateAuthTokens(user);

}

`


`

$3

`bash
/context src/auth/AuthService.ts --with-deps

📋 Context for AuthService with dependencies:

- Depends on: UserRepository, TokenService, PasswordHasher

- Used by: LoginController, SignupController, AuthMiddleware

- Related symbols: authenticateUser, verifyPassword, generateTokens

`

🎉 Benefits

$3

- Intuitive interface with familiar slash commands
- Natural language queries for non-technical stakeholders
- Comprehensive context with dependency awareness
- Fast search with semantic understanding

$3

- Consistent indexing with quality filtering
- Cross-file understanding via dependency analysis
- Incremental updates for active development
- Production ready with robust error handling

🚀 Advanced Usage

$3

`bash

Semantic search for concepts

/search "how does authentication work" --type=semantic

Structural search for patterns

/search "function.login.password" --type=structural

Hybrid search combining both

/search authentication --type=hybrid
`

$3

`bash

Find all files that depend on AuthService

/deps AuthService --reverse

Show dependency graph for authentication module

/deps src/auth/ --graph --depth=3
`

$3

`bash

Get 20 lines of context around matches

/search database connection --window=20

Focus on specific symbol types

/context UserService --focus=functions --with-deps
`

🛠️ Development

$3

`
├── src/ # Source code
│ ├── core/ # Core indexing and search logic
│ ├── services/ # Search and utility services
│ ├── utils/ # Utilities (Logger, FileUtils, etc.)
│ └── types/ # TypeScript type definitions
├── tests/ # Essential test files
├── scripts/ # Utility scripts
└── dist/ # Compiled JavaScript output
`

$3

`bash

Set environment variables

export JINA_API_KEY="your_jina_api_key"
export TURBOPUFFER_API_KEY="your_turbopuffer_key"

Test semantic chunking quality

node tests/final-chunking-validation.mjs

Test search integration end-to-end

node tests/test-improved-search-quality.mjs

Test search result quality directly

node tests/test-search-results-direct.mjs

Test MCP server functionality

node tests/test-mcp-tools-directly.mjs
``

$3

- TreeSitterChunkExtractor - AST-based semantic code chunking
- HybridSearchService - Vector + BM25 search fusion
- StandaloneCodexMcp - Main MCP server integration
- IndexingOrchestrator - Coordinates the indexing pipeline

🎯 What Makes This Special

Unlike simple text search tools, this MCP provides:

1. True code understanding via AST parsing and symbol extraction
2. Quality-focused indexing that filters out noise automatically
3. Dependency-aware search that finds related code across files
4. Multiple interfaces to suit different user preferences
5. Production deployment with real API integrations
6. Incremental efficiency for large, active codebases

Perfect for teams using Claude Code who need intelligent codebase exploration and context-aware development assistance.

---

Ready to enhance your codebase exploration with Claude Code! 🚀