feature - RFC 106 MCP tools and task context packing

[dannymeijer]

Area

• Tooling (CLI/formatter/test runner)
• Documentation

Problem statement

incan inspect codegraph gives agents raw graph facts, but RFC 106’s main agent-facing product is task-ranked context packing: one high-level call should return a compact, deterministic, budgeted context pack for a concrete task.

Without this layer, agents still need to perform several low-level graph/search/read calls and decide relevance themselves.

Related: #573, #766, RFC 106.

Proposed solution

Add an agent-facing context service and MCP surface on top of the compiler-backed codegraph export.

The first implementation should support task-level retrieval before exposing many raw graph tools. It should produce compact, deterministic context packs with source anchors, graph reasons, provenance, diagnostics, and relevant neighboring facts.

Candidate tools/resources:

• context_for_task(task, budget, project_id)
• context_for_files(files, budget, project_id)
• explain_context(task, node_id, project_id)
• graph_neighbors(node_id, project_id)
• graph_summary(project_id)
• read-only resources for schema, stale status, indexed packages, and snapshot metadata

Alternatives considered

• Expose only raw JSONL and expect agents to rank it: too low-level for agent ergonomics.
• Pack the entire repository: portable but token-heavy and structurally blunt.
• Make embeddings mandatory: rejected because graph/name/provenance ranking should work locally and deterministically first.

Scope / acceptance criteria

• In scope:

  • Define compact task-context output for agent consumption.
  • Implement deterministic ranking using exact names, docs/metadata, graph proximity, diagnostics, and provenance.
  • Add an MCP surface or prototype for read-only task context and graph summary tools.
  • Include stale/snapshot metadata in responses.

• Out of scope:

  • Mandatory embeddings or hosted inference.
  • Remote graph storage.
  • Writing or mutating source files through MCP.

• Done when:

  • A task prompt can produce a bounded context pack from an Incan project without manual grep/read loops.
  • Output is deterministic for the same graph snapshot, task, budget, and ranking config.
  • Tests cover budget behavior, stable ordering, and provenance preservation.