Architecture

2026-03-31

workspace-mcp uses a federated model.

Layers

1. Repo-local docs and manifests
2. Workspace registry and routing
3. Shared framework guidance from dirac-framework

Authority

• repo owners remain authoritative for repo-scoped implementation truth
• the workspace layer routes agents to the right repo and entrypoints
• doc-hub is the shared SPOT for curated design intent and developer instruction
• MCP exposes that knowledge to agents in structured form

Key Files

• Repo manifest: docs/agent/manifest.yaml
• Repo start-here: docs/agent/start-here.md
• Workspace registry: workspace-repo-registry.generated.json
• Workspace server: server/src/server.js

Current Resources

• workspace://authority-model
• workspace://repos
• repo://{repo}/manifest
• repo://{repo}/start-here
• repo://{repo}/capabilities
• repo://{repo}/workflows
• repo://{repo}/contracts

Resolution Rule

• resolve repo metadata through the workspace registry first
• only load docs/agent/manifest.yaml when the registry declares a real manifest
• use registry-declared entrypoints for fallback repos
• use heuristic probing only when a repo is missing from the registry

The detailed design note remains in the repo root at WORKSPACE_MCP_ARCHITECTURE.md.