Ctxo

# Ctxo MCP Server

> AI agents don't fail because they can't code. They fail because they code blind. Ctxo gives them the full picture before they write a single line.

Ctxo is a Model Context Protocol (MCP) server that gives AI agents structured context about codebases: symbol graphs, blast radius, architectural overlays, change intelligence, dead code detection, and PR impact analysis.

## Quick Start

```
npm install -g @ctxo/cli   # One-time global install (gives you the `ctxo` command)
ctxo init                  # Detect languages, install plugins, wire MCP
ctxo index                 # Build codebase index
ctxo                       # Start MCP server (stdio)
```

## Package Layout (v0.7.0-alpha.0, pnpm monorepo)

- `@ctxo/cli` — CLI + MCP server (formerly `ctxo-mcp`)
- `@ctxo/plugin-api` — `CtxoLanguagePlugin` v1 interface (apiVersion, id, extensions, tier, createAdapter)
- `@ctxo/lang-typescript` — ts-morph full-tier plugin
- `@ctxo/lang-go` — tree-sitter / gopls plugin
- `@ctxo/lang-csharp` — Roslyn plugin
- `@ctxo/lang-java` - tree-sitter Java plugin (syntax tier built-in; full tier via `@ctxo/lang-java-analyzer` companion, requires JRE 11+)

Language adapters ship as separate npm packages and are discovered by scanning the project `package.json` for `@ctxo/lang-*` or `ctxo-lang-*` dependencies.

## 14 Tools

- get_logic_slice: Symbol + transitive dependencies (L1-L4 detail levels)
- get_blast_radius: What breaks if a symbol changes (3-tier: confirmed/likely/potential)
- get_architectural_overlay: Project layer map (Domain/Infrastructure/Adapter)
- get_why_context: Git commit intent + anti-pattern warnings (reverts, rollbacks)
- get_change_intelligence: Complexity x churn composite score
- find_dead_code: Unreachable symbols and files
- get_context_for_task: Task-optimized context (fix/extend/refactor/understand)
- get_ranked_context: BM25 + PageRank search within token budget
- search_symbols: Symbol name/regex search across index
- get_changed_symbols: Symbols in recently changed files (git diff)
- find_importers: Reverse dependency lookup ("who uses this?")
- get_class_hierarchy: Class inheritance tree (ancestors + descendants)
- get_symbol_importance: PageRank centrality ranking
- get_pr_impact: Full PR risk assessment in a single call

## Tool Selection Guide

- Reviewing a PR? -> get_pr_impact
- About to modify code? -> get_blast_radius
- Understanding a symbol? -> get_context_for_task(taskType: "understand")
- Fixing a bug? -> get_context_for_task(taskType: "fix")
- Refactoring? -> get_context_for_task(taskType: "refactor")
- Don't know the symbol name? -> search_symbols or get_ranked_context
- Finding unused code? -> find_dead_code
- Safe to delete? -> find_importers

## New in v0.8

- **Safe-edit guard** - a PreToolUse hook (Claude Code) that blocks edits to high-impact symbols until the agent checks blast radius. Installed by `ctxo init`. Configure via `gate:` in `.ctxo/config.yaml` (sensitivity: strict|balanced|lenient).
- `ctxo blast-radius <symbolId> --json` - compute blast radius for one symbol, JSON to stdout (CI scripts, jq pipelines)
- `ctxo gate --preview [--json]` - preview which symbols the guard would flag at the current sensitivity
- Three model-invoked skills (`ctxo-understand`, `ctxo-safe-edit`, `ctxo-review-pr`) installed to `.claude/skills/` (Claude Code) and `.cursor/rules/` (Cursor)

## New in v0.7

- `ctxo install` — install language plugin packages
- `ctxo update` — check npm for newer @ctxo/cli + plugins; auto-execute or print install command
- `ctxo init` — project-aware language detection + plugin wiring
- `ctxo index --install-missing` — auto-install missing plugins during index
- `ctxo doctor --fix` — repair common issues
- `ctxo version` subcommand; `ctxo --version --verbose|--json` for plugin/runtime details

## Key Concepts

- Symbol ID format: "file::name::kind" (e.g., "src/foo.ts::myFn::function")
- All responses include _meta: { totalItems, returnedItems, truncated, totalBytes }
- 4 tools support intent filtering: get_blast_radius, get_logic_slice, find_importers, find_dead_code
- Large responses auto-truncated at 8KB (configurable via CTXO_RESPONSE_LIMIT)

## Links

- npm: https://www.npmjs.com/package/@ctxo/cli
- GitHub: https://github.com/alperhankendi/Ctxo
- Full reference: llms-full.txt