Codestrate (coding-intelligence-mcp-server)

An "external fine-tuning" layer for cloud coding models (Claude Code, Codex, Gemini, OpenCode). Provides structural code retrieval via tree-sitter AST parsing, graph-based symbol navigation, project memory, and allowlisted validation via the Model Context Protocol.

Architecture

Model (Claude Code / Codex / OpenCode)
        │
        │ MCP (stdio)
        ▼
┌──────────────────────────────────────────────────────┐
│              Codestrate MCP Server                   │
├──────────────────────────────────────────────────────┤
│  Profile: core (default, ≤7 tools)                   │
│  ├─ ci_status           — Index readiness + counts   │
│  ├─ ci_repo_overview    — Project structure          │
│  ├─ ci_explore          — FTS5 + camelCase search    │
│  ├─ ci_inspect_symbol   — Definition + callers       │
│  ├─ ci_get_context      — Task context bundle        │
│  ├─ ci_analyze_impact   — Change impact              │
│  └─ ci_trace_flow       — Call/import BFS            │
│                                                      │
│  Profile: full (opt-in)                              │
│  ├─ validation, reindex, memory, session, graph ops  │
│  └─ set CI_MCP_PROFILE=full or "profile":"full"      │
│                                                      │
│  Store: SQLite only (single source of truth)         │
│  Transport: stdio                                    │
└──────────────────────────────────────────────────────┘

Quick Start

# From package
npx codestrate
# or
npx ci-mcp

# From source
git clone <repo> && cd coding-intelligence-mcp-server
npm install
npm run build
node dist/index.js

Default profile is core (read-only, ≤7 tools). Mutations and extra diagnostics require full:

CI_MCP_PROFILE=full node dist/index.js

Or in .ci-mcp.json:

{
  "profile": "full",
  "commands": {
    "build": "npm run build",
    "test": "npm test",
    "lint": "npm run lint"
  },
  "validation": { "trusted": true },
  "timeout": 300,
  "storePath": "~/.ci-mcp/store"
}

Semantic search (automatic by default)

On first start, codestrate auto-downloads LFM2.5-Embedding GGUF + llama-server, spawns a local embeddings process, indexes vectors, and uses hybrid search when ready.

Artifacts live under ~/.ci-mcp/ (models/, bin/, store/). Disable with CI_MCP_EMBEDDING_MODE=none.

Full guide: docs/semantic-search.md.

Tools

Core (default)

| Tool | Purpose | |------|---------| | ci_status | Index lifecycle, readiness, symbol counts, staleness | | ci_repo_overview | Structure, build system, frameworks, entry points | | ci_explore | FTS5 + camelCase + graph search | | ci_inspect_symbol | Definition, callers, callees, tests | | ci_get_context | Token-budgeted context bundle for a task | | ci_analyze_impact | Dependents / symbols affected by file changes | | ci_trace_flow | BFS call/import flow |

Full profile only

• ci_search_code, ci_search_history, ci_deep_explore
• Graph: ci_graph_stats, ci_graph_explain, ci_query_graph, ci_detect_cycles, ci_trace_bfs, ci_detect_dead_code
• Memory: ci_recall_experience, ci_record_experience (evidence-gated)
• Validation: ci_run_validation (requires validation.trusted: true)
• Index: ci_reindex
• Session: ci_session_heartbeat, ci_session_status, ci_reflect, ci_reflect_history
• Meta: ci_profile, ci_ping

Features

Tree-sitter AST + graph

Bundled WASM grammars (TypeScript, TSX, JavaScript, Python, Go, Rust, Java, C, C++). Symbols and relations land in SQLite with FTS5 and camelCase matching. Graph BFS powers ci_trace_flow / impact tools.

Index readiness

Auto-index runs on startup when repoPath is known. Lifecycle states: not_started | indexing | ready | failed | empty. Failed indexes do not report ready; tools that need the graph return typed INDEX_FAILED / INDEX_NOT_READY errors instead of empty success.

Evidence-gated memory

ci_record_experience (full profile) requires commit SHA, changed files, and validation evidence before storing.

Validation trust

ci_run_validation is default-off. Enable only after reviewing allowlisted commands and setting "validation": { "trusted": true }.

Configuration

Config files (first found wins): .ci-mcp.json, ci-mcp.config.json, .coding-intelligence.json.

| Key | Default | Notes | |-----|---------|-------| | profile | core | or env CI_MCP_PROFILE=full | | storePath | ~/.ci-mcp/store | SQLite DB location | | commands.* | — | build/test/lint allowlist | | validation.trusted | false | must be true to run validation | | timeout | 300 | seconds |

Transport

stdio only. Streamable HTTP is not shipped in this version.

Prompts

• ci://prompts/debug-runtime-error
• ci://prompts/implement-feature
• ci://prompts/review-code

Limitations

• Relation resolution is still partly name-based (heuristic edges may be wrong for overloads)
• Incremental reindex improves over full rebuild but cascading dependents are best-effort
• Regex fallback languages are best-effort vs tree-sitter grammars

License

MIT