{ "schemaVersion": "0.2.0", "project": { "name": "contextforge-cli", "root": "." }, "generatedAt": "2026-05-08T...Z", "scanRef": { "path": ".contextforge/scan.json", "scanHash": "..." }, "parser": { "engine": "heuristic" }, "stats": { "nodesByType": { "file": 287, "folder": 117, "symbol": 3104 }, "edgesByType": { "imports": 71, "defines": 2256, "contains": 376 } }, "nodes": [ /* ordenados por id, JSON byte-estable */ ], "edges": [ /* ordenadas por (from,to,type) */ ] } ``` ### Tipos de nodo y arista que produce | Nodo | Cuándo aparece | | --------- | -------------------------------------------------------------------------------- | | `file` | Uno por cada archivo del scan (`code`/`test`/`doc`/`config`/`asset`) | | `symbol` | Por cada función/clase/interface/type/var/enum exportada o interna | | `folder` | Sintético, derivado de los paths (anidación completa) | | `package` | Por cada **import externo único** (`react`, `node:path`, `@anthropic-ai/sdk`, …) | | Arista | De qué | Cuándo se emite | | ------------ | ----------------------------------- | ---------------------------------------------------------------------- | | `defines` | `file → symbol` | Siempre que el archivo contiene un símbolo | | `imports` | `file → file` o `file → package` | Relativos · alias workspace (pnpm) · alias `tsconfig.paths` · externos | | `tests` | `file:test → file:impl` | Convención `*.test.ts` ↔ `*.ts` | | `extends` | `symbol → symbol` | Clase/interface extiende un símbolo del mismo file o de un import | | `implements` | `symbol → symbol` | `class A implements B` resuelto | | `contains` | `folder → folder` y `folder → file` | Estructura de carpetas | | `calls` | `file → symbol` | **Solo con `--with-calls`** (heurística regex, ruido aceptado) | | `references` | `file → symbol` | **Solo con `--with-refs`** (PascalCase, fuera de imports/defines) | **Lenguajes parseables** hoy (heurística regex, no tree-sitter WASM): TypeScript, TSX, JavaScript, JSX, Python, Go, Rust, Java. El resto se incluye como `file` pero sin símbolos. ### Incrementalidad y reproducibilidad ```bash pnpm forge graph # 1ª vez en este repo: 112 archivos parseados # editas un archivo pnpm forge scan # actualiza hashes pnpm forge graph # → "cache: 111 reutilizados, 1 reparseados" pnpm forge graph --force # ignora ambos caches; reconstruye todo pnpm forge graph --with-calls # añade aristas calls (heurística, opt-in) pnpm forge graph --with-refs # añade aristas references PascalCase (opt-in) # resolución de imports # 1. workspace pnpm (packages/) # 2. tsconfig.paths (compilerOptions.paths con baseUrl) # 3. relativos (./foo, ../bar) # 4. externos → nodo type=package (react, node:fs, @scope/lib) # export a otros formatos pnpm forge graph --export=dot > graph.dot pnpm forge graph --export=graphml > graph.graphml # Render con Graphviz: dot -Tsvg graph.dot -o graph.svg # O abrir graph.graphml directamente en Gephi. # enriquecimiento opcional con LLM (Anthropic) ANTHROPIC_API_KEY=sk-... pnpm forge graph --enrich # Agrega summary / tags / complexity a los símbolos exportados. # El default sigue siendo determinista; --enrich es la única excepción opt-in. ``` - **Cache global por hash del scan**: si `scan.json` no cambió, `forge graph` no arranca. - **Cache por archivo** (`.contextforge/graph.cache.json`): solo se reparsean los archivos cuyo hash BLAKE3 cambió. - **Output byte-idéntico** entre dos corridas (excluyendo `generatedAt`): los nodos y aristas se ordenan al final por `id` / `(from,to,type)`, así que `git diff` del JSON es revisable y el prompt cache de Claude no se invalida innecesariamente. ### Visualización: `forge viz` ```bash pnpm forge graph pnpm forge viz # genera .contextforge/graph.html # abre el archivo en cualquier navegador, no necesita servidor ni Node ``` El HTML viewer es **standalone** (un solo archivo, Cytoscape vía CDN) y trae: ``` ┌──────────────────────────────────────────────────────────────────────┐ │ ContextForge [Grafo] [Dominios] 287 nodos · 2703 edges · 50 pack│ ├──────────────┬───────────────────────────────────────────────────────┤ │ Estadísticas │ │ │ 287 archivos │ ●─────● │ │ 3104 símbolos│ ╱ ╲ ● ← archivo en pack │ │ 2703 edges │ ●─────●───● ◇ ← símbolo exportado │ │ 50 en pack │ ╲ ╱ ◇ ← dashed = interno │ │ │ ●─● ▢ ← carpeta │ │ Tour ◀ ▶ ✕ │ │ │ 3 / 50 │ │ │ │ │ │ Leyenda nodos │ ┌──────────────┐ │ │ ● Código 128 │ │ src/ │ ← agrupación por dominio │ │ ● Test 24 │ │ ┌────┐ ┌──┐ │ (toggle "Agrupar") │ │ ● Doc 17 │ │ │a.ts│ │b │ │ │ │ ▢ Carpeta 117│ │ └────┘ └──┘ │ │ │ ◇ Interno 218│ └──────────────┘ │ │ ● En pack 50 │ │ │ │ │ │ Leyenda edges │ │ │ ─ imports │ │ │ ─ defines │ │ │ ─ tests │ │ │ ─ extends │ │ │ ─ contains │ │ │ │ │ │ Filtros │ │ │ [Solo pack] [+Sím] [+Carpetas] [Agrupar] │ │ [⊕ Centrar] [⟳ Layout] │ │ │ │ │ 🔍 Buscar... │ │ │ │ │ │ Nodo selec. │ │ │ src/main.ts │ │ │ [code][ts] │ │ │ Define 4 sím │ │ │ → importa: 3 │ │ │ ← usado por:5│ │ └───────────────┴────────────────────────────────────────────────────────┘ ``` **Capacidades del viewer:** - **Dos vistas**: grafo file/symbol/folder + vista de **dominios** (agregación por carpeta top-level, edges = imports cruzados entre dominios). - **Tour por context-pack**: `▶` recorre uno por uno los archivos seleccionados por PageRank para tu tarea, centrándose y mostrando vecinos. - **Filtros incrementales**: solo pack (default), añadir símbolos, añadir carpetas, agrupar por dominio. - **Estilos diferenciados** para `exported:false` (símbolos internos en dashed) y nodos `folder`. - **Búsqueda** por nombre o ruta con resaltado. - **Panel de nodo**: kind, lang, contadores de edges entrantes/salientes, lista navegable de vecinos. ### Cómo lo usa el agente El agente **nunca** lee el repo a ciegas. Lee artefactos derivados, en este orden: ``` 1. .contextforge/agent-context.md ← qué hay disponible y en qué orden leerlo 2. .contextforge/context-pack.json ← solo los archivos relevantes a la tarea 3. .contextforge/agent-manifest.json ← qué skills/rules aplican (con razón) 4. .contextforge/graph.json ← solo si necesita ver vecinos / cross-deps ``` **El grafo no se inyecta entero al prompt**. El agente lo consulta puntualmente: | Pregunta del agente | Cómo responde el grafo | | ------------------------------------ | ---------------------------------------------------------------- | | "¿Qué archivos tocan a `Foo`?" | Edges `defines`/`imports` entrantes del símbolo | | "¿Quién testea esto?" | Edges `tests` entrantes del file | | "¿De qué hereda `Bar`?" | Edge `extends` saliente del símbolo | | "¿En qué carpeta vive este archivo?" | Edge `contains` entrante del file | | "Dame el subgrafo de mi tarea" | Lo entrega `forge context` ya filtrado (PageRank + BFS + budget) | | "Que nada se salga del scope" | `implement-plan.json::allowedFiles[]` derivado del pack | **Vía MCP** — los agentes que hablen MCP pueden llamar tools sin tocar disco: ```jsonc { "tool": "forge_neighbors", "arguments": { "path": "src/foo.ts" } } // → { incoming: [...], outgoing: [...], symbols: [...] } { "tool": "forge_context", "arguments": { "task": "fix race in writer" } } // → { files: [...], packTokens: 11988, tokenLedger: {...} } ``` ### Vs. Understand-Anything (qué tomamos, qué no) | Aspecto | Understand-Anything | ContextForge | | ------------------------- | ---------------------------------- | ------------------------------------------------ | | Pipeline | Tree-sitter + LLM agents (híbrido) | Regex/tree-sitter, **0 LLM** en el pipeline | | Lenguajes soportados | 10+ con WASM | 8 con heurística (TS/JS/Py/Go/Rust/Java/TSX/JSX) | | Schema de nodo | 21 tipos (con dominio + knowledge) | 4 tipos canónicos (file/symbol/folder/package) | | Schema de arista | 35 tipos | 8 tipos (los que un agente usa de verdad) | | Enriquecimiento (summary) | LLM agents enriquecen cada nodo | Determinista: contadores derivados del grafo | | Coste de regenerar | API key + tiempo + ruido | CPU-only · cache por archivo · idempotente | | Visualización | Dashboard rico, tours guiados | HTML standalone con tour + dominios + filtros | | Persistencia | knowledge-graph.json + embeddings | graph.json + graph.cache.json (BLAKE3) | | Roadmap LLM enrich | Es la base | Opt-in futuro (`--enrich`), nunca el default | **La filosofía**: el grafo de ContextForge **no intenta entender el código**, intenta darte un índice rápido y barato. La inteligencia semántica vive en el agente, no en el pipeline. Por eso es reproducible y por eso el output sirve de input al prompt cache de Claude (descuento del 90 % en iteraciones 2+ del SDD). --- ## Cómo el grafo le da superpoderes a OpenSpec > El bloque clave de v0.3.0+. Sin grafo, OpenSpec hace su trabajo bien pero el agente trabaja a ciegas. Con grafo, el spec se vuelve trazable, validable y barato. **1. El `spec-input.json` deriva del grafo, no del repo.** | Campo | Lo aporta el grafo | | ----------------- | ---------------------------------------------------------------------- | | `affectedFiles` | El context-pack ya filtró por PageRank → spec apunta a archivos reales | | `crossDomainDeps` | El grafo de imports → design.md menciona dependencias correctas | | `domain` | Inferencia por mayoría de paths del pack | | `evidence` | Referencias trazables a los artefactos JSON validados | | `purpose` | Inferencia determinista del nombre del archivo | **2. El agente recibe el spec-prompt, NO el repo.** `forge spec` genera `.contextforge/spec-prompt.md` con 4 secciones: ``` 1. Contexto del repo (de ContextForge) - Tarea, dominio inferido, archivos afectados, cross-domain deps, evidencia 2. Instrucciones canónicas de OpenSpec - Lo que devuelve `openspec instructions proposal --change --json` 3. Restricciones para tu salida - Token budget, allowed files, formato moderno 4. Output esperado - Editar openspec/changes//{proposal,design,tasks,specs}.md ``` El agente no abre el repo. Solo lee este prompt + el context-pack si necesita más detalle. **3. El multiplicador escondido — prompt caching.** Claude descuenta **90 % del precio** de tokens cacheados. ContextForge mete un boost porque su output **es determinista**: - Mismo `forge context` → mismo `context-pack.json` byte-a-byte. - Mismo `forge spec` → mismo `spec-prompt.md` byte-a-byte. Entre las **iteraciones 2, 3, N** del SDD, el agente cachea todo el prompt. Solo paga full por el delta. **4. Ahorro doble medido.** ``` Por iteración SDD: Sin ContextForge 217 600 tokens $0.65 Con ContextForge 18 988 tokens $0.057 (-91%) 3 iteraciones de un feature normal: Sin caching 3 × $0.65 = $1.96 Con caching activo $0.07 (÷28×) ``` **5. Trazabilidad auditable.** Cada path en `design.md` apunta a un archivo del `context-pack.json`. Cada commit puede verificarse con `forge implement --check` contra `allowedFiles[]` derivado del pack. **6. Subgrafo congelado dentro del change (v0.3.7+).** `forge spec ` ahora también escribe `openspec/changes//graph.subset.json` — un subgrafo limitado al context-pack del change + 1 hop por aristas. Eso significa: - Las skills/prompts del agente que leen `openspec/changes//` tienen el grafo del momento exacto en que se autorizó el spec, sin necesidad de reabrir `.contextforge/graph.json` (que pudo haber mutado). - `design.md` incluye una sección "Context graph (subset)" con stats y la referencia al adjunto. - Vía MCP: `forge_change_subgraph({ change_id: "mi-feature" })` lo devuelve directo, ideal para que un agente lo cargue al inicio de una sesión de implementación. ``` openspec/changes/mi-feature/ ├── proposal.md ├── design.md ← incluye tabla con stats del subset ├── tasks.md ├── specs//spec.md ├── graph.subset.json ← subgrafo self-contained · validado por JSON Schema └── graph.subset.html ← viewer interactivo standalone (Cytoscape, sin servidor) ``` Trazabilidad real: el subgrafo es `byte-stable` (orden determinista), validado por JSON Schema (`docs/schemas/graph-subset.schema.json`), y queda commiteado con el resto del change. Si seis meses después el grafo global cambió, puedes comparar este subset con el subgrafo equivalente de hoy y ver el drift. **Tabla — qué aporta cada herramienta:** | Aporte | ContextForge | OpenSpec | Agente IA | | --------------------------------------------------------- | :----------: | :------: | :-------: | | Ranking de archivos por relevancia | ✓ | | | | Grafo de dependencias | ✓ | | | | Token budget + selección por presupuesto | ✓ | | | | Trazabilidad (cada archivo viene del pack) | ✓ | | | | Schemas estables (Requirement+Scenario) | | ✓ | | | Validación estructural (`openspec validate`) | | ✓ | | | Templates canónicos por artefacto | | ✓ | | | Instalación de instrucciones por agente (`openspec init`) | | ✓ | | | Redacción de prosa | | | ✓ | | Decisiones de diseño contextual | | | ✓ | | Determinismo + cacheabilidad | ✓ | ✓ | | --- ## Documentación generada para agentes (`forge init`) `forge init` genera `.contextforge/agent-context.md` — un archivo derivado que cualquier agente puede leer al iniciar sesión y entender: - Qué artefactos hay disponibles y en qué orden leerlos. - Cómo consumirlos (no leer el repo a ciegas). - La receta SDD completa (ContextForge ⊕ OpenSpec). - Política para agentes (no specs a mano, no bullets, gate pre-commit). - Tabla de comandos clave por intención. Adicionalmente, `forge init` detecta si `openspec` CLI está en PATH y, si el directorio `openspec/` no existe, ejecuta: ```bash openspec init . --tools=claude,cursor,opencode --force ``` Eso instala las **instrucciones canónicas de OpenSpec** para los 3 agentes (las que aparecen en `.claude/`, `.cursor/rules/`, `opencode.json`). Idempotente: si el directorio `openspec/` ya existe, salta. --- ## Comandos completos | Comando | Qué hace | LLM | | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | :----: | | `forge init` | `.contextforge/` + `agent-context.md` + `openspec init` (si está) | No | | `forge scan` | Indexa con BLAKE3 (incremental) | No | | `forge graph [--force] [--with-calls] [--with-refs] [--enrich] [--export=]` | Grafo file/symbol/folder/package con cache por archivo (BLAKE3) | No (¹) | | `forge context "" [--no-manifest] [--force]` | PageRank + BFS + budget · auto-emite manifest | No | | `forge spec [--no-openspec]` | spec-input.json + handoff/fallback OpenSpec | No | | `forge implement ` | Plan con guardrails derivados del pack | No | | `forge implement --check` | Valida diff vs guardrails | No | | `forge skills [--force]` | Auto-genera skills por dominio (`contextforge-domain-.md`) | No | | `forge manifest [--agents=...] [--force]` | Re-genera manifest sin re-rankear | No | | `forge sync [--since X] [--rebuild]` | Reporta delta desde un ref de git | No | | `forge impact` | Health check de artefactos + cobertura | No | | `forge viz` | Visualización HTML interactiva del grafo | No | | `forge docs [--force]` | Scaffold Diátaxis (tutorials/how-to/reference/explanation/adr/architecture) | No | **Política**: ningún comando llama a un LLM por defecto. Todo es derivable, reproducible, auditable. (¹) `forge graph --enrich` es la **única excepción opt-in** — agrega `summary`/`tags`/`complexity` a símbolos exportados vía Anthropic API. Requiere `ANTHROPIC_API_KEY`. Sin la flag, el pipeline sigue 100 % determinista. --- ## Servidor MCP `packages/mcp` expone **10 tools** consumibles por cualquier cliente MCP (Claude Code, OpenCode, etc.). | Tool | Propósito | | ----------------------- | ------------------------------------------------------------------------------------ | | `forge_status` | Estado de los artefactos (frescura, conteos, savings) | | `forge_domain_map` | Mapa de dominios + dependencias cruzadas | | `forge_neighbors` | Vecinos directos de un archivo en el grafo | | `forge_context` | Selección PageRank para una tarea (con o sin contenido) | | `forge_check` | Valida git diff contra guardrails del implement-plan | | `forge_change_subgraph` | Subgrafo congelado de un OpenSpec change (`openspec/changes//graph.subset.json`) | | `forge_change_context` | Mapa de lectura del change (`openspec/changes//context.md`) | | `forge_archive_change` | **Cierra un change**: `openspec archive` + rebuild graph padre + refresh subgrafos | | `select_agent_context` | **Runtime**: computa agent-manifest en memoria para una tarea (cache mtime) | | `get_agent_manifest` | **Offline**: lee `.contextforge/agent-manifest.json` precomputado | **Wiring (Docker, recomendado):** ```jsonc { "mcpServers": { "contextforge": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "${PWD}:/project", "-e", "PROJECT_ROOT=/project", "ghcr.io/alejandro-cedeno-10/contextforge-mcp:latest" ] } } }

ContextForge MCP Server

Installation