Code Intelligence

This MCP Server provides code intelligence capabilities for Cursor-like editors by orchestrating specialized tools, data stores, and a controlled workflow. It enhances understanding of a codebase, enforces safety gates, and learns from past decisions to deliver reliable suggestions and targeted changes across projects.

How to use

You interact with the Code Intelligence MCP Server through an MCP client that connects to the server orchestration layer. The server guides you through a staged workflow: Exploration, Semantic search, Verification, and Impact Analysis, culminating in a READY state where you can implement changes. You will benefit from automated failure detection, embedded context, and project-specific learning that helps the system understand your codebase and apply changes safely.

Typical usage flow when you start a session with a project is: start a session, set a query frame for quote-verification, perform exploration queries (like finding definitions or references), optionally run semantic searches, verify embeddings, check for impact on related files, and finally implement the changes when READY is reached. The system keeps decision and outcome logs to improve future sessions and detect failures automatically.

How to install

Prerequisites you need installed on your machine or in your environment before setting up the MCP Server:

• Python 3.10 or newer

• ripgrep (rg) for text and reference searches

• universal-ctags for symbol and definition lookups

• A compatible runtime environment for the MCP server (virtual environment recommended)

Step 1: MCP Server Setup (once only)

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

# Setup server (virtual environment, 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

Step 3: Configure .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 the Claude Code client to load the MCP server. The initial code-intel index is built as you start your first session.

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

Design docs and project rules are automatically detected and summarized at session start. The server scans for design documents and project rules, creates a local context file, and prompts you to generate summaries. It then saves your summaries and updates the context for future sessions.

Upgrade (v1.0 → v1.1)

If you have an older project setup, follow these steps to upgrade your MCP server and project context.

1. Update the llm-helper server

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

2. Update skills in your project (if copied)

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

3. Restart Claude Code to reload the MCP server.

Notes and tips

• The system enforces phase gates to prevent unsafe actions. You will move through EXPLORATION, SEMANTIC, VERIFICATION, IMPACT ANALYSIS, and READY with explicit permissions at each stage.

• It uses a decision- and outcome-logging mechanism to learn from outcomes and detect failures automatically.

• Project isolation ensures learning data stays bound to each project.

Security and compliance

The server enforces discipline through phase gates, prevents unauthorized tool usage, and relies on embedded quotes for hallucination prevention. You should only interact with known, explored files when making changes.

Troubleshooting

If you encounter indexing or session-start issues, verify that the Python virtual environment is active and that the paths in .mcp.json point to the correct locations. Check the logs under .code-intel/logs for decisions and outcomes to understand any automatic failure detections.

Available tools

start_session

Start a new MCP session and initialize necessary components for the current project.

set_query_frame

Set the QueryFrame, enabling quote verification during input processing.

get_session_status

Check the current phase and status of the active session.

submit_understanding

Complete the EXPLORATION phase by submitting understanding of the codebase.

validate_symbol_relevance

Perform embedding verification to ensure symbol relevance.

submit_semantic

Complete the SEMANTIC phase with a semantic search and results.

submit_verification

Complete the VERIFICATION phase and confirm hypotheses.

check_write_target

Verify that you have permission to write to the target files.

add_explored_files

Record files that have been explored during the session.

revert_to_exploration

Return the session to the EXPLORATION phase if needed.

record_outcome

Record the outcome of a session step for improvement cycles.

get_outcome_stats

Retrieve statistics about past outcomes to inform future runs.

analyze_impact

Analyze the impact of changes across affected files (v1.1).