# Code Intelligence MCP Server

> **Current Version: v1.16**

An MCP server that enforces LLMs like Claude and Codex to implement code exactly as specified.

## Overview

### Problems Solved

LLM-driven code implementation has three key problems:

| Problem | Symptom |
|---------|---------|
| **Insufficient Exploration** | Only looks at the modification target, ignores related code |
| **Rule Ignorance** | Doesn't read design documents or coding standards |
| **Incomplete Implementation** | Skips tasks, uses mocks, returns empty implementations |

### Our Solution

```
Don't let LLMs make decisions. Design gates they cannot bypass.
```

| Problem | Solution | Implementation |
|---------|----------|----------------|
| Insufficient Exploration | **Forced Exploration** | code-intel tool usage required in EXPLORATION phase |
| Rule Ignorance | **Forced Documentation** | Design document reading required in DOCUMENT_RESEARCH phase |
| Incomplete Implementation | **Forced Verification** | checklist + evidence required, empty implementation detection (pass/TODO/NotImplementedError) |

### Positioning

```
┌─────────────────────────────────────────────────────────────┐
│  Upper Layer: Spec-Driven Development Workflow               │
│  Define "what to build" (spec creation, task decomposition)  │
└─────────────────────────────────────────────────────────────┘
                         ↓ Pass specs/tasks
┌─────────────────────────────────────────────────────────────┐
│  This Tool: Code Intelligence MCP Server                     │
│  Enforce "build exactly as specified"                        │
│  - Force 19-step execution: explore → verify rules → impl    │
│  - Server controls phase transitions (LLM cannot skip)       │
└─────────────────────────────────────────────────────────────┘
```

This tool functions as a **lower layer** of the spec-driven development workflow, solving the problem of "specs are correct but LLM doesn't implement correctly."

---

## Design Philosophy

| Principle | Description |
|-----------|-------------|
| **Phase Enforcement** | Cannot proceed to implementation without exploration. Server controls transitions |
| **Server Evaluation** | Confidence scores calculated by server. LLM self-reporting eliminated |
| **Write Restriction** | Only explored files can be modified. Writes to unexplored files are blocked |
| **Safety Valve** | Server-side counter prevents infinite loops. Intervention triggers after 3 verification failures |
| **Improvement Cycle** | DecisionLog + OutcomeLog for learning from failure patterns |

See [DESIGN.md](docs/DESIGN.md) for details.

---

## 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 │
    └───────────────────┘
```

### Semantic Search (Forest/Map)

**Purpose**: Find code from natural language queries (e.g., "authentication logic" → `AuthService.login()`)

| Layer | Search Target | Effect |
|-------|--------------|--------|
| **Map** | Term→Symbol mappings | Instantly identify symbols for learned terms |
| **Forest** | Entire source code | Find relevant code even for new terms |

**Behavior**: High Map score (≥0.7) → Skip Forest for faster results

---

## Processing Flow (19 Steps)

Each phase is gate-managed, with the orchestrator controlling transitions so LLMs cannot skip phases.

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  Session Start                                                              │
│  Step 1: start_session (Intent detection → Initialization)                  │
│  Step 2: BRANCH_INTERVENTION (only when stale detected)                     │
│  Step 3: DOCUMENT_RESEARCH ← Skip with --no-doc                            │
│  Step 4: QUERY_FRAME                                                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  Exploration Phase ← Skip with --fast/--quick                               │
│  Step 5:  EXPLORATION                                                       │
│  Step 6:  Q1 (SEMANTIC necessity check)                                     │
│  Step 7:  SEMANTIC (only when Q1=true)                                      │
│  Step 8:  Q2 (VERIFICATION necessity check)                                 │
│  Step 9:  VERIFICATION (only when Q2=true)                                  │
│  Step 10: Q3 (IMPACT_ANALYSIS necessity check)                              │
│  Step 11: IMPACT_ANALYSIS (only when Q3=true / research: SESSION_COMPLETE)  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  Implementation Phase                                                        │
│  Step 12: READY (task planning + branch creation)                           │
│  Step 13: READY (implementation ×N)                                         │
│  Step 14: READY (all tasks completion check)                                │
│  Step 15: POST_IMPL_VERIFY ← Skip with --no-verify / fail→Step 12          │
│  Step 16: VERIFY_INTERVENTION (only when failure_count ≥ 3)                 │
│  Step 17: PRE_COMMIT                                                        │
│  Step 18: QUALITY_REVIEW ← Skip with --no-quality                          │
│  Step 19: MERGE → SESSION_COMPLETE                                          │
└─────────────────────────────────────────────────────────────────────────────┘
```

See [DESIGN.md](docs/DESIGN.md) for details.

---

## Requirements

- Python 3.10+
- Supported OS: Linux (Ubuntu/Debian, Fedora/RHEL, Arch), macOS, Windows (WSL)

### Tools Installed by setup.sh

**Environment Setup:**
- venv — Creates Python virtual environment
- pip — Upgraded to latest version

**System Tools:**
- ripgrep (rg) — Text search
- universal-ctags — Symbol definition search

**Python Packages:**
| Package | Version | Purpose |
|---------|---------|---------|
| mcp | ≥1.0.0 | MCP server framework |
| chromadb | ≥1.0.0 | Vector search (Forest/Map) |
| tree-sitter | ≥0.21.0, <0.22.0 | AST parsing |
| tree-sitter-languages | ≥1.10.0 | Language parsers |
| sentence-transformers | ≥2.2.0 | Embedding model |
| scikit-learn | ≥1.0.0 | Similarity calculation |
| PyYAML | ≥6.0.0 | context.yml parsing |
| asyncio | — | Async processing |
| pytest | ≥7.0.0 | Testing |
| pytest-asyncio | ≥0.21.0 | Async testing |

---

## Setup

### Step 1: MCP Server Setup (One-time)

```bash
# Clone the 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)

```bash
# Initialize target project (indexes entire project)
./init-project.sh /path/to/your-project

# Option: Index specific directories only
./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 the following (◎ = must modify, ★ = can add/modify, 〇 = can modify):

```
your-project/
├── .claude/
│   ├── CLAUDE.md          〇 Project rules for LLM (can add rules)
│   └── commands/          ← Skill files (auto-generated)
└── .code-intel/
    ├── config.json           ← Configuration (auto-generated)
    ├── context.yml           ◎ Project settings (see Step 6)
    ├── phase_contract.yml    ← Phase contract definitions (v1.13)
    ├── task_planning.md      〇 Task decomposition guide (v1.11)
    ├── user_escalation.md    〇 User escalation procedures
    ├── chroma/               ← ChromaDB data (auto-managed)
    ├── sessions/             ← Checkpoints (auto-managed)
    ├── agreements/           ← Success patterns (auto-managed)
    ├── logs/                 ← DecisionLog, OutcomeLog (auto-managed)
    ├── verifiers/            ★ Verification prompts (can add/modify)
    ├── doc_research/         ★ Document research prompts (can add/modify)
    ├── interventions/        ★ Intervention prompts (can add/modify)
    └── review_prompts/       ★ Quality review prompts (can add/modify)
```

### Step 3: Configure .mcp.json

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

```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: Restart Claude Code

Restart to load the MCP server.

### Step 5: Verify Skills

Check that skills are available:
```bash
# In Claude Code
/code --help
```

### Codex Users (Install Skills)

Codex loads skills from `$CODEX_HOME/skills`. Copy the templates:
```bash
cp -r /path/to/llm-helper/templates/skills/codex/* "$CODEX_HOME/skills/"
```

### Step 6: Customize context.yml

The `.code-intel/context.yml` file controls various behaviors. Customize as needed:

```yaml
# Project rules (auto-detected: CLAUDE.md, .claude/CLAUDE.md, CONTRIBUTING.md)
project_rules:
  source: "CLAUDE.md"

# Document search settings for analyze_impact
document_search:
  include_patterns:
    - "**/*.md"
    - "**/README*"
    - "**/docs/**/*"
  exclude_patterns:
    - "node_modules/**"
    - "vendor/**"
    - ".git/**"

# v1.3: Document research settings
doc_research:
  enabled: true
  docs_path:
    - "docs/"
  default_prompts:
    - "default.md"

# v1.4: Intervention system settings
interventions:
  enabled: true
  prompts_dir: "interventions/"
  threshold: 3  # Failure count before intervention triggers

# Verifier settings
verifiers:
  suggest_improvements: true
```

| Section | Description |
|---------|-------------|
| `project_rules` | Project rules source file (auto-detected) |
| `document_search` | Document search patterns for impact analysis |
| `doc_research` | Document research settings (v1.3) |
| `interventions` | Intervention system settings (v1.4) |
| `verifiers` | Verifier behavior settings |

---

## Usage

### Using /code Skill

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

**Default Behavior:** Full mode (exploration + implementation + verification + cleanup + quality)

### Command Options

| Long | Short | Description |
|------|-------|-------------|
| `--gate=LEVEL` | `-g=LEVEL` | Gate level: f(ull), a(uto) [default: auto] (v1.10) |
| `--no-verify` | - | Skip verification (also skips intervention) |
| `--no-quality` | - | Skip quality review (v1.5) |
| `--only-verify` | `-v` | Run verification only (skip implementation) |
| `--only-explore` | `-e` | Run exploration only (skip implementation) |
| `--fast` | `-f` | Fast mode: skip exploration, with branch |
| `--quick` | `-q` | Minimal mode: skip exploration, no branch |
| `--no-doc-research` | - | Skip document research (v1.3) |
| `--no-intervention` | `-ni` | Skip intervention system (v1.4) |
| `--resume` | `-r` | Resume session from checkpoint |
| `--clean` | `-c` | Delete stale branches + all checkpoints |
| `--rebuild` | - | Force rebuild all indexes |

**gate_level Options (v1.10):**
- `--gate=full` or `-g=f`: Execute all phases ignoring Q1/Q2/Q3 checks
- `--gate=auto` or `-g=a`: LLM judges necessity before each phase (default)

#### Phase Matrix

| Option | Doc Research | Explore | Impl | Verify | Intervene | Cleanup | Quality | Branch |
|--------|:----:|:----:|:----:|:----:|:------:|:----:|:-------:|:-------:|
| (default) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `--only-explore` / `-e` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `--only-verify` / `-v` | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `--no-verify` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ |
| `--no-quality` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| `--no-intervention` / `-ni` | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
| `--no-doc` | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `--fast` / `-f` | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| `--quick` / `-q` | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |

#### Examples

```bash
# Full mode (default): exploration + implementation + verification + cleanup + quality
/code add login feature

# Skip verification (also skips intervention)
/code --no-verify fix this bug

# Skip quality review only
/code --no-quality fix simple typo

# Verification only (check existing implementation)
/code -v sample/hello.html

# Exploration only (no implementation, for investigation)
/code -e investigate issues in the codebase

# Fast mode (skip exploration, with branch, for known fixes)
/code -f fix known issue in login validation

# Quick mode (minimal, no branch)
/code -q change the button color to blue

# Skip document research (v1.3)
/code --no-doc-research fix typo

# Resume from checkpoint
/code -r

# Clean up stale sessions
/code -c

# Force rebuild all indexes
/code --rebuild
```

## 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 logging
│   ├── context_provider.py ← Required context (v1.1)
│   ├── impact_analyzer.py  ← Impact analysis (v1.1)
│   ├── branch_manager.py   ← Git branch isolation (v1.2)
│   └── ...
├── setup.sh                ← Server setup
├── init-project.sh         ← Project initialization
└── templates/
    ├── code-intel/         ← .code-intel templates
    └── skills/
        ├── claude/         ← Claude skill templates
        └── codex/          ← Codex skill templates
```

> For target project structure, see "[Setup > Step 2](#step-2-project-initialization-per-project)"

---

## Tool List

| Category | Tools |
|----------|-------|
| Session | `start_session`, `submit_phase`, `get_session_status` |
| Exploration | `search_text`, `find_definitions`, `find_references`, `analyze_structure`, `get_symbols`, `search_files`, `semantic_search`, `query` |
| Implementation Control | `check_write_target`, `add_explored_files`, `review_changes` |
| Branch | `cleanup_stale_branches` |
| Index | `sync_index`, `update_context`, `record_outcome`, `get_outcome_stats` |

See [DESIGN.md](docs/DESIGN.md) for details.

---

## Documentation

| Document | Content |
|----------|---------|
| [DESIGN.md](docs/DESIGN.md) | Overall design (English) |
| [DESIGN_ja.md](docs/DESIGN_ja.md) | Overall design (Japanese) |
| [DOCUMENTATION_RULES.md](docs/DOCUMENTATION_RULES.md) | Documentation management rules |

---

## CHANGELOG

Version history and detailed changes:

| Version | Description | Link |
|---------|-------------|------|
| v1.11 | submit_phase unification & task orchestration (17 tools→1, compaction resilience, server-enforced task management) | [v1.11](docs/updates/v1.11_ja.md) |
| v1.10 | Individual Phase Checks (per-phase checks, VERIFICATION/IMPACT separation, gate_level reorganization - 20-60s reduction) | [v1.10](docs/updates/v1.10_ja.md) |
| v1.9 | sync_index batch processing, VERIFICATION+IMPACT_ANALYSIS integration (15-20s reduction) | [v1.9](docs/updates/v1.9_ja.md) |
| v1.8 | Exploration-Only Mode (Intent auto-detection + --only-explore, no branch creation) | [v1.8](docs/updates/v1.8_ja.md) |
| v1.7 | Parallel Execution (27-35s reduction) | [v1.7](docs/updates/v1.7_ja.md) |
| v1.6 | Branch Lifecycle (stale warning, begin_phase_gate) | [v1.6](docs/updates/v1.6_ja.md) |
| v1.5 | Quality Review | [v1.5](docs/updates/v1.5_ja.md) |
| v1.4 | Intervention System | [v1.4](docs/updates/v1.4_ja.md) |
| v1.3 | Document Research, Markup Cross-Reference | [v1.3](docs/updates/v1.3_ja.md) |
| v1.2 | Git Branch Isolation | [v1.2](docs/updates/v1.2_ja.md) |
| v1.1 | Impact Analysis, Context Provider | [v1.1](docs/updates/v1.1_ja.md) |

---

## License

MIT