Code Intelligence MCP Server v1.1

An MCP server that provides Cursor IDE-like code intelligence capabilities using open source tools.

Overview

Even with the same Opus 4.5 model, behavior differs depending on the caller:

This MCP server provides mechanisms to make Claude Code "understand the codebase".

Design Philosophy

Don't let the LLM decide. Design so it can't proceed without compliance.
And have a mechanism to learn from failures.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MCP Clients (Claude Code)                 │
└─────────────────────────────────────────────────────────────┘
                               │
                               ▼
                    ┌─────────────────┐
                    │   code-intel    │  ← Unified MCP Server
                    │  (orchestrator) │
                    └─────────────────┘
                               │
               ┌───────────────┼───────────────┐
               ▼               ▼               ▼
        ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
        │ ChromaDB    │ │ ripgrep     │ │ ctags       │
        │ (map/forest)│ │ (search)    │ │ (symbols)   │
        └─────────────┘ └─────────────┘ └─────────────┘
               │
               ▼
    ┌───────────────────┐
    │ Project/.code-intel│  ← Project-specific
    │ ├─ config.json     │
    │ ├─ chroma/         │  ← ChromaDB data
    │ ├─ agreements/     │
    │ ├─ logs/           │  ← DecisionLog, OutcomeLog
    │ └─ sync_state.json │
    └───────────────────┘

Forest and Map

Short-circuit Logic: Map score ≥ 0.7 → Skip Forest exploration

Phase Gates

EXPLORATION → SEMANTIC → VERIFICATION → IMPACT ANALYSIS → READY
     ↓           ↓           ↓               ↓               ↓
  code-intel  semantic    verify         analyze_impact   implementation
   tools      search    (confirm)        (v1.1)           allowed
             (hypothesis)

Tool List

Code Intelligence

Session Management

Improvement Cycle

Setup

Step 1: MCP Server Setup (once only)

# Clone repository
git clone https://github.com/tech-spoke/llm-helper.git
cd llm-helper

# Setup server (venv, dependencies)
./setup.sh

Step 2: Project Initialization (per project)

# Initialize target project (index entire project)
./init-project.sh /path/to/your-project

# Option: Index only specific directories
./init-project.sh /path/to/your-project --include=src,packages

# Option: Specify additional exclude patterns
./init-project.sh /path/to/your-project --exclude=tests,docs,*.log

This creates:

your-project/
└── .code-intel/
    ├── config.json       ← Configuration
    ├── chroma/           ← ChromaDB data (auto-generated)
    ├── agreements/       ← Agreements directory
    └── logs/             ← DecisionLog, OutcomeLog

Step 3: Configure .mcp.json

Add the configuration output by init-project.sh to .mcp.json:

{
  "mcpServers": {
    "code-intel": {
      "type": "stdio",
      "command": "/path/to/llm-helper/venv/bin/python",
      "args": ["/path/to/llm-helper/code_intel_server.py"],
      "env": {"PYTHONPATH": "/path/to/llm-helper"}
    }
  }
}

Step 4: Setup Skills (optional)

mkdir -p /path/to/your-project/.claude/commands
cp /path/to/llm-helper/.claude/commands/*.md /path/to/your-project/.claude/commands/

Step 5: Restart Claude Code

Restart to load the MCP server. Index is automatically built on first session start.

Step 6: Essential Context (v1.1, automatic)

Design docs and project rules are automatically detected and summarized.

How it works:

1. On first sync_index, server auto-detects design docs and project rules
2. Creates .code-intel/context.yml with detected sources
3. Returns document content + prompt for LLM to generate summaries
4. LLM generates summaries and saves via update_context tool
5. On subsequent syncs, detects changes and regenerates summaries as needed

Auto-detected locations:

• Design docs: docs/architecture/, docs/design/, docs/
• Project rules: CLAUDE.md, .claude/CLAUDE.md, CONTRIBUTING.md

Manual customization (optional):

You can edit .code-intel/context.yml to add extra_notes (implicit knowledge not in source docs):

essential_docs:
  source: "docs/architecture"
  summaries:
    - file: "overview.md"
      path: "docs/architecture/overview.md"
      summary: "..."                     # ← Auto-generated by LLM
      extra_notes: |                     # ← Optional: add your implicit knowledge
        - Exception: Simple CRUD can bypass Service layer

project_rules:
  source: "CLAUDE.md"
  summary: "..."                         # ← Auto-generated by LLM
  extra_notes: |                         # ← Optional: add your implicit knowledge
    - Legacy code in /old can ignore these rules

Upgrade (v1.0 → v1.1)

If you have existing projects initialized with v1.0, follow these steps to upgrade:

Step 1: Update llm-helper Server

cd /path/to/llm-helper
git pull
./setup.sh  # Update dependencies

Step 2: Update Skills (if copied to project)

cp /path/to/llm-helper/.claude/commands/*.md /path/to/your-project/.claude/commands/

Step 3: Restart Claude Code

Restart to reload the MCP server.

What Changes

No Changes Required

• .code-intel/config.json - Compatible, no changes needed
• .code-intel/chroma/ - Existing index continues to work
• .mcp.json - No changes needed

The context.yml file will be automatically created on next session start.

Usage

Using /code skill (recommended)

/code Fix the bug in AuthService's login function where no error is shown when password is empty

The skill automatically:

1. Failure check (auto-detect and record previous failures)
2. Intent determination
3. Session start (auto-sync, essential context)
4. QueryFrame extraction and verification
5. EXPLORATION (find_definitions, find_references, etc.)
6. Symbol verification (Embedding)
7. SEMANTIC if needed
8. VERIFICATION (hypothesis verification)
9. IMPACT ANALYSIS (v1.1 - analyze affected files)
10. READY (implementation)

Direct tool invocation

# Text search
Search for pattern "Router" with mcp__code-intel__search_text

# Definition search
Find definition of "SessionState" with mcp__code-intel__find_definitions

# Semantic search
Search for query "login functionality" with mcp__code-intel__semantic_search

Improvement Cycle

Two Logs

Automatic Failure Detection

At /code start, automatically determines if current request indicates "previous failure":

• Detects patterns like "redo", "doesn't work", "wrong", etc.
• Automatically records failure to OutcomeLog
• No need to manually call /outcome

Dependencies

System Tools

Python Packages

mcp>=1.0.0
chromadb>=1.0.0
tree-sitter>=0.21.0
tree-sitter-languages>=1.10.0
sentence-transformers>=2.2.0
scikit-learn>=1.0.0
PyYAML>=6.0.0
pytest>=7.0.0

Project Structure

MCP Server (llm-helper/)

llm-helper/
├── code_intel_server.py    ← MCP server main
├── tools/                  ← Tool implementations
│   ├── session.py          ← Session management
│   ├── query_frame.py      ← QueryFrame
│   ├── router.py           ← Query routing
│   ├── chromadb_manager.py ← ChromaDB management
│   ├── ast_chunker.py      ← AST chunking
│   ├── sync_state.py       ← Sync state management
│   ├── outcome_log.py      ← Improvement cycle log
│   ├── context_provider.py ← Essential context (v1.1)
│   ├── impact_analyzer.py  ← Impact analysis (v1.1)
│   └── ...
├── setup.sh                ← Server setup
├── init-project.sh         ← Project initialization
└── .claude/commands/       ← Skill definitions
    └── code.md

Target Project

your-project/
├── .mcp.json               ← MCP config (manual setup)
├── .code-intel/            ← Code Intel data (auto-generated)
│   ├── config.json
│   ├── context.yml         ← Essential context config (v1.1)
│   ├── chroma/             ← ChromaDB data
│   ├── agreements/         ← Success pairs
│   ├── logs/               ← DecisionLog, OutcomeLog
│   └── sync_state.json
├── .claude/commands/       ← Skills (optional copy)
└── src/                    ← Your source code

Documentation

License

MIT