Skip to content

Repo MCP Contract Expectation

Contract Expectation

The workspace discovery layer must declare repo capability and authority before any top-layer agent attempts repo-local file loads.

Expected behavior:

  1. Resolve target repo through the workspace registry first.
  2. Registry must explicitly declare whether a repo has a real repo manifest.
  3. Only load docs/agent/manifest.yaml when the registry says it exists.
  4. If no repo manifest exists, use registry-declared fallback entrypoints instead of probing blindly.
  5. Repo-local manifest remains authoritative when present.
  6. Workspace registry is discovery and routing authority, not content override authority.
  7. The registry-first rule must be enforced in workspace-mcp server handlers and MCP tools, not left to caller discipline.

Minimum Registry Contract Per Repo

  • repo_id: stable repo key
  • manifest_source: repo or generated
  • manifest_path: absolute path when present
  • entrypoints: ordered safe-to-read files
  • resource_roots: bounded scan roots by type
  • authority_order: declared precedence
  • repo_class: dirac / oves / legacy
  • lifecycle: active / transitional / archived
  • owner: owning team or authority
  • signals.has_docs
  • signals.has_mkdocs
  • signals.has_adr
  • signals.has_intents

Observed Gap

Current usage pattern is still too optimistic:

  • top layer may try docs/agent/manifest.yaml directly
  • some repos still do not have that file
  • this creates avoidable lookup failures during rollout
  • fallback exists, but only after a failed blind load

Concrete Example

  • workspace-mcp repo is correctly declared in the registry and has a repo manifest
  • mkdocs-template now has a repo manifest and explicit context docs
  • many other active repos are still registry-only
  • current flow can still attempt direct manifest loading on a registry-only repo
  • expected flow should consult registry first, see manifest_source: generated, then route to fallback entrypoints like README.md, docs/index.md, or mkdocs.yml

Required MCP Setup Change

Change resolution flow from:

  1. try nearest repo manifest
  2. then fallback to registry

to:

  1. resolve repo in registry
  2. if registry declares manifest_path, load it
  3. else use registry-declared fallback entrypoints
  4. only if repo is missing from registry, use heuristic probing

Why This Matters

  • avoids fragile top-layer behavior during manifest rollout
  • makes missing manifests an expected declared state, not an error condition
  • reduces blind file probing
  • gives agents a deterministic, bounded discovery contract
  • supports mixed maturity repos cleanly

Next Layer

Once the registry-first contract is in place, repo-specific context services should be exposed in the same pattern:

  • repo://<repo>/manifest
  • repo://<repo>/start-here
  • repo://<repo>/capabilities
  • repo://<repo>/workflows
  • repo://<repo>/contracts

These should be loaded only through declared registry or manifest-backed paths, not through open-ended probing.

Optional Hardening

  • add discovery_mode: manifest-backed / registry-fallback / heuristic
  • add safe_to_probe: true/false
  • add entrypoint_status metadata so missing files can be surfaced by the registry generator rather than by runtime agent failure

Bottom Line

The MCP discovery contract should be registry-first, manifest-when-declared, and heuristic-only-as-last-resort. The data already exists; the calling pattern must now be tightened in the server and exposed resources.