blindspot-mcp 0.2.0

The External Brain for AI Coding Agents — see what your LLM can't see. Provides instant, structured intelligence about your entire codebase without reading files into the AI's context window.

Blindspot MCP

Blindspot is a local, general-purpose context engine for AI coding agents.

It exists for one job:

• help the agent understand a project
• help the agent understand symbols and relationships
• help the agent estimate change impact before editing
• do this across different languages and project layouts

Blindspot is intentionally small. It is not trying to be a deployment system, policy engine, rollout manager, or autonomous edit platform.

Why

Most agents can edit files, search text, and run commands. What they usually lack is a compact, reusable understanding layer for:

• project structure
• symbol ownership
• callers and references
• inheritance and composition
• likely blast radius of a change

That is the gap Blindspot fills.

Paid context engines already proved this model is useful. Blindspot is the local and reusable alternative.

Design Goals

• Small MCP surface
• Works across languages and frameworks
• Gives structured context instead of file dumps
• Helps any agent write better code with fewer blind edits
• Stays useful even when framework-specific intelligence is missing

Language Coverage

Blindspot keeps one public API and improves the engine underneath it.

• Strong support: Python, PHP, JavaScript, TypeScript, Go
• Solid project-structure and syntax-aware support: Dart / Flutter, React Native, Node.js
• Additional generic support: Java, Kotlin, C#, Ruby, Rust, mixed repos

The contract does not change per language. get_context(...) stays the same; only the quality of the internal enrichment improves.

Core Tools

Blindspot now exposes only the core context-engine surface:

• set_project_path: call once to bind Blindspot to the repo
• get_project_snapshot: one-shot repo overview at session start
• get_context: main entrypoint for file, symbol, relationship, and impact context
• get_symbol_body: exact symbol metadata or bounded source excerpt
• get_edit_region: small numbered excerpt around a symbol or line range
• search_code: fallback text search when structured context is not enough
• find_files: locate candidate files before drilling into one with get_context
• refresh_index: rebuild the shallow file index if discovery gets stale
• build_deep_index: rebuild the deep symbol index for richer relationship analysis

Main Workflow

1. Call set_project_path(...)
2. Call get_project_snapshot() once at the start of a session
3. Before any important edit, call get_context(target=..., intent="before_edit", symbol=...)
4. If exact source is needed, call get_symbol_body(...) or get_edit_region(...)
5. If the returned context is still insufficient, use search_code(...)

Tool Selection Rule

Agents should default to get_context.

• Use get_project_snapshot for orientation
• use get_context for understanding and edit planning
• use get_symbol_body for one symbol
• use get_edit_region for a tight excerpt
• use find_files to locate candidates
• use search_code only as fallback
• use index rebuild tools only when index data is missing or stale

The Main Idea

The agent should not decide between 40 different analysis tools.

Instead, it should call one entrypoint and receive a normalized context envelope:

• project
• target
• overview
• file_context
• symbol_context
• relationship_context
• impact_context
• direct_callers
• indirect_dependents
• blast_radius
• risk_reasons
• safe_edit_hints
• related_files
• related_file_reasons
• missing_context
• confidence
• confidence_details
• edit_plan
• suggested_next_steps

That is what get_context(...) returns.

Supported Intents

get_context(...) supports these intents:

• project
• file
• symbol
• before_edit
• impact

This keeps the public API small while still covering the main agent workflows.

get_context(...) also accepts change_type:

• modify
• rename
• delete
• signature_change
• contract_change

Use a stronger change_type when you want Blindspot to plan a coordinated refactor instead of a local edit.

Install

pip install blindspot-mcp

Claude Code

Add this to ~/.claude/settings.json:

{
  "mcpServers": {
    "blindspot": {
      "command": "blindspot-mcp",
      "args": ["--project-path", "/path/to/your/project"]
    }
  }
}

Cursor / VS Code

Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "blindspot": {
      "command": "blindspot-mcp",
      "args": ["--project-path", "."]
    }
  }
}

Example

Developer: Change the User status behavior

Agent:
1. get_project_snapshot()
2. get_context(target="app/models/user.py", intent="before_edit", symbol="is_active")
3. get_symbol_body("app/models/user.py", "is_active")
4. edit with full awareness of related files and likely impact

What Blindspot Does Not Try To Be

• a code editor
• a release gate system
• a deployment orchestrator
• a policy approval workflow
• a giant framework tool catalog

Those concerns make the product noisier and make agents choose tools instead of understanding code.

Local-First

Blindspot runs locally and analyzes the codebase on your machine.

Current Product Direction

Blindspot should become:

• a stable context layer any AI agent can use
• easy to plug into different editors and agent runtimes
• reliable across Python, PHP, TypeScript, JavaScript, Go, Java, Ruby, Rust, C#, and mixed repos
• reliable across Dart / Flutter, React Native, Node.js, and mixed monorepos
• useful even in plain projects with no heavy framework detection

The standard for success is simple:

• fewer blind edits
• better relationship awareness
• better change impact awareness
• better code written by the agent

Development

Run the core test suite:

python3 -m unittest tests.test_context_engine_service -v

Run the lightweight context evaluation harness:

.venv/bin/python evals/run_context_eval.py