archgen-mcp 0.0.0-stage → 0.0.6

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# archgen-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP server for [archgen](https://github.com/akashmaurya99/archgen) — it
+owns **every** deterministic capability in the archgen workflow.
+
+The archgen skill is orchestration guidance for an agent; this server is the
+runtime it drives. One implementation, three ways in:
+
+| Consumer | How it reaches the server |
+|---|---|
+| Coding agents | MCP over stdio — 10 domain tools |
+| `archgen-skill init` / `install` | `archgen-mcp bootstrap` |
+| The VS Code extension | `archgen-mcp exec <tool> '<json>'` |
+
+## Install
+
+The archgen installer wires this server into every detected harness for you:
+
+```bash
+npx archgen-skill init
+```
+
+That installs the skill, writes the `archgen` MCP entry into each detected
+harness's own config (with the correct per-platform file and top-level key),
+and ensures CodeGraph.
+
+To run it by hand:
+
+```bash
+npx archgen-mcp            # serve MCP over stdio
+npx archgen-mcp --list     # list the tools
+npx archgen-mcp doctor     # health report
+```
+
+Requires **Node.js >= 20** (the official MCP SDK v2 floor).
+
+## The tools
+
+| Tool | Use it for |
+|---|---|
+| `archgen_plan` | validate · verifier gate · dependency graph · blast radius · coverage · **scaffold** (the artifact set for a scope class) · **brief** (a dispatch brief) |
+| `archgen_tasks` | next wave · set status · list · resume snapshot · **contract** (the assembled worker prompt) |
+| `archgen_docs` | navigate markdown artifacts: section index, one section, token map, reference integrity |
+| `archgen_registry` | refresh / read the AGENTS.md features registry |
+| `archgen_codegraph` | install + wire + index CodeGraph and its MCP |
+| `archgen_setup` | doctor · bootstrap servers · install/remove the MCP · list harnesses · **harness_info** (a platform's capabilities) |
+| `archgen_ui` | drive the VS Code extension in real time |
+| `archgen_skills` | match / install / load external capability skills |
+| `archgen_refs` | load archgen's own protocol documents — section by section |
+| `archgen_help` | the full briefing for one domain |
+
+Every tool returns the same envelope:
+
+```json
+{ "ok": true, "data": { }, "error": null, "meta": { "serverVersion": "…", "skillVersion": "…", "projectRoot": "…" } }
+```
+
+`ok` says whether the **call** succeeded. A failed call carries a typed
+`error.code`:
+
+`INVALID_INPUT` · `NOT_FOUND` · `CYCLE` · `OWNERSHIP_CONFLICT` · `CONFLICT` ·
+`PERMISSION_DENIED` · `UNAVAILABLE` · `TIMEOUT` · `INTERNAL`
+
+Call `archgen_help { topic: "<domain>" }` for the full briefing on any tool —
+including when to call it, every action, and its gotchas.
+
+### The judgment / output split
+
+The archgen **skill** carries the judgment (policy, rules, when-to-use). This
+server carries the **deterministic output** — the artifact sets, the skeletons,
+the dispatch briefs, the assembled worker prompt, the harness capability tables.
+
+The five orchestrator-facing protocol documents also live **here**, in
+`assets/references/`, and are served section-by-section by `archgen_refs`:
+
+```
+archgen_refs { action: 'index', topic: 'orchestration' }
+archgen_refs { action: 'read', topic: 'orchestration', section: 'dispatch--wave-execution' }
+```
+
+They live here so they are always the same version as the tools they describe.
+One exception stays in the skill as a plain file: `code-standards.md`, because
+WORKER sub-agents read it with their native file tools and may have no MCP
+server at all.
+
+### The capability contract
+
+The skill declares the server version it needs:
+
+```yaml
+metadata:
+  requires:
+    archgen_mcp: ">=0.0.6"
+```
+
+`archgen_setup { action: 'doctor' }` reports a mismatch, `bootstrap` warns
+before wiring, and CI refuses to ship a skill whose declared minimum exceeds
+this package's version.
+
+## The CLI facade
+
+```bash
+archgen-mcp exec archgen_plan '{"action":"validate","tasksYaml":"/abs/tasks.yaml"}'
+archgen-mcp exec archgen_tasks '{"action":"next","tasksYaml":"/abs/tasks.yaml"}'
+archgen-mcp bootstrap --project . --location both --yes
+archgen-mcp doctor --project . --json
+archgen-mcp uninstall-mcp --project . --yes
+```
+
+`exec` runs the **same handlers** the MCP tools expose — there is no second
+implementation of any capability, only a second way to reach it.
+
+## Safety
+
+- Every path argument is resolved against the project root and refused if it
+  escapes; symlinked targets are never written through.
+- MCP-config writes are approval-gated (`approve: true` / `--yes`); without
+  approval the tool reports its **plan** and writes nothing.
+- A config file that cannot be parsed is reported, never rewritten.
+- Writes are atomic (temp file + rename): readers see old-or-new, never a
+  partial file.
+- UI commands are allowlisted, workspace-scoped, expiring, and idempotent.
+
+## License
+
+MIT

package/assets/briefs/investigate.md

@@ -0,0 +1,22 @@
+TASK: Investigate a recurring issue in this repository.
+TRIGGER: the user reports repetitive/recurring issues AFTER implementation waves
+completed. This is NOT a patch-fix task.
+
+DELIVERABLE: all four, or the investigation is incomplete:
+1. ROOT CAUSE — one sentence naming the actual defect (not the symptom).
+2. EVIDENCE — files / lines / repro steps that prove it.
+3. BLAST RADIUS — which tasks and artifacts are affected.
+   Use `archgen_plan { action: 'impact', tasksYaml: <tasks.yaml>, target: <id-or-path> }`.
+4. REMEDIATION — routed through the NORMAL gates: new fix tasks get fresh ids
+   inheriting the affected task's ownership globs.
+
+SIZING
+- SMALL scope: the main agent investigates directly.
+- MEDIUM/LARGE: 1–3 investigator sub-agents split by suspected subsystem.
+
+DISCIPLINE
+- Read narrowly around the evidence — no whole-repo sweeps.
+- A patch-fix WITHOUT a root-cause statement is FORBIDDEN under this protocol.
+- Write your notes under .archgen/<slug>/.agent/notes/<topic>.md and your
+  findings under .archgen/<slug>/.agent/reports/investigate-<round>.md.
+  NEVER create ad-hoc folders at the repo root.

package/assets/briefs/review.md

@@ -0,0 +1,35 @@
+TASK: Review the plan in .archgen/<slug>/ READ-ONLY.
+DELIVERABLE: a numbered findings list; each finding = what + where + why.
+You NEVER edit files. You report only.
+
+EXAMINE
+- edge cases per module
+- task ordering / parallelization sanity (waves vs real dependencies)
+- cross-module contract mismatches (interfaces, paths, naming)
+- enhancement recommendations
+- documentation completeness
+
+CONTEXT TO ATTACH
+- `archgen_plan { action: 'graph', tasksYaml: <tasks.yaml>, format: 'mermaid', status: true }`
+  — the wave-progress render; reviewer reads it to sanity-check ordering.
+- `archgen_docs { action: 'validate', slugDir: <slug dir> }` — the reference
+  integrity result; broken references are findings, not noise.
+
+SIZING
+- SMALL: the main agent's self-review is acceptable when the harness has no
+  reviewer mechanism.
+- MEDIUM: 1 reviewer.
+- LARGE: 1 holistic reviewer on the strongest reasoning tier. A 2nd reviewer
+  ONLY if the plan is genuinely too large for one reviewer's context — split by
+  ARTIFACT/VOLUME (e.g. plans vs docs), never by concern.
+
+ONE holistic reviewer analyzes ALL issues together: cross-issue reasoning catches
+contradictions a narrow per-concern slice misses, and one reviewer costs far
+fewer tokens than several. NEVER dispatch one sub-agent per individual issue.
+
+BOUNDS
+- A "more review" approval authorizes EXACTLY ONE additional pass — never a
+  fresh loop, never more reviewers. The stage ends ONLY at zero findings or an
+  explicit user waiver on record.
+- The ORCHESTRATOR fixes the artifacts, re-runs validate + the verifier gate
+  after every change, and re-dispatches. Reviewers never fix.

package/assets/briefs/survey.md

@@ -0,0 +1,22 @@
+TASK: Survey this repository to prepare a feature plan for: <feature request>
+DELIVERABLE: write .archgen/<slug>/codebase-map.md containing EXACTLY these
+sections:
+  ## Structure      — top-2-levels folder tree w/ one-line purpose each
+  ## Modules        — table: module | responsibility | key entry points
+  ## Conventions    — naming, error-handling, test layout actually observed
+  ## Affected       — files/modules the feature will touch, with evidence paths
+SCOPE: read-only.
+NAVIGATE: use the CodeGraph MCP tools when available — the index is built once
+at bootstrap and kept live by the server's watcher, so never re-index.
+Otherwise Glob+Grep systematically.
+VERIFY: every claim cites a real path; no guessed APIs. A claim without an
+evidence path is a defect, not a detail.
+
+ACCEPTANCE
+The map is accepted only if every section is present and NON-EMPTY. Anything the
+survey could not determine is written down as an explicit unknown, not omitted —
+an omitted section is indistinguishable from an un-surveyed one.
+
+THEN: the orchestrator asks ONLY what the survey could not answer. Never
+interrogate the user with what a file already answers — quote the file and ask
+for confirmation instead.

package/assets/briefs/verifier.md

@@ -0,0 +1,44 @@
+TASK: Verify this archgen plan before any execution.
+DELIVERABLE: exactly one line — `APPROVE` or `ISSUES:` followed by a numbered list.
+SCOPE: read-only. You NEVER edit files. You report findings only.
+
+RUN THESE FIRST (the deterministic floor — every one must pass):
+1. `archgen_plan { action: 'verify', tasksYaml: <tasks.yaml>, planDir: <plans dir> }`
+   — must return verdict APPROVE. It checks cycles, dangling refs, same-wave
+   ownership overlap, missing acceptance criteria and plan<->task coverage.
+2. `archgen_docs { action: 'validate', slugDir: <slug dir> }` (when markdown
+   artifacts exist) — must return valid:true. Broken references BLOCK approval.
+
+THEN judge what the tools cannot:
+- Are wave boundaries sensible (no artificial serialization)?
+- Do acceptance criteria objectively verify (a command or an observable)?
+- Is edge-case coverage adequate for the scope class of each task?
+- Is code-standards compliance plausible for the planned structure?
+- CONTRACT-COMPLETENESS sweep — round 1 must confirm OR flag-as-missing every
+  APPLICABLE dimension. Apply a dimension only where the system actually has
+  that concern, but NEVER skip a dimension the system touches:
+  - Functional coverage: every stated requirement has a task + objectively
+    verifiable acceptance.
+  - Security & data protection (if it authenticates, authorizes, encrypts or
+    handles sensitive data): authn/authz flows, session & credential lifecycle,
+    replay/CSRF protection, encryption & privacy boundaries, input validation.
+  - Data integrity: schemas, relationships, validation, migration / back-compat.
+  - State, lifecycle & recovery (if any operation is stateful, long-running or
+    multi-step): checkpointing/resume, idempotency, cleanup, expiry,
+    compensation/rollback semantics.
+  - Resource limits & abuse (if it exposes shared or anonymous resources):
+    quotas, rate limits, retention/deletion, anonymous-abuse controls.
+  - Operational entrypoints: every stack-required build/deploy/test/bootstrap
+    entrypoint is OWNED by some task.
+  - Metric traceability: every PRD success metric maps to a task acceptance
+    criterion with a reproducible command / sample size / data source.
+  - Consistency: cross-contract claims must not contradict each other.
+  These failure classes are the TOP cause of multi-round loops — round 1 MUST
+  sweep the applicable dimensions exhaustively.
+
+RULES
+- Run on the STRONGEST reasoning agent the harness offers. NEVER an explore /
+  research / quick / cheap tier: a weak verifier misses real defects AND raises
+  false positives, costing MORE rounds, not fewer.
+- Every finding names the file and the reason. No vague findings.
+- If everything passes, return exactly `APPROVE` and nothing else.

package/assets/depth-ladder.json

@@ -0,0 +1,90 @@
+{
+  "version": 1,
+  "_readme": [
+    "Canonical depth ladder: scope class -> the artifact set a plan MUST have.",
+    "",
+    "This is the machine-readable twin of references/artifact-templates.md § Plan",
+    "depth by scope class. The reference keeps the AUTHORING RULES; this file",
+    "owns the ARTIFACT SET, so the orchestrator never guesses which files a",
+    "SMALL/MEDIUM/LARGE plan needs. `archgen_plan{action:'scaffold'}` serves it.",
+    "",
+    "A drift test (packages/mcp/test/core/depth-ladder.test.mjs) pins this file",
+    "against the reference's stated minimums."
+  ],
+  "classes": {
+    "SMALL": {
+      "label": "SMALL — add or touch a few things",
+      "intentDefaults": ["BROWNFIELD-CHANGE"],
+      "roundCap": 3,
+      "artifacts": [
+        { "path": ".archgen/<slug>/tasks.yaml", "required": true, "purpose": "the task contract" },
+        { "path": ".archgen/<slug>/plans/<slug>-note.md", "required": true, "purpose": "a lean plan note" }
+      ],
+      "planSections": ["Intent", "Tasks", "Risks"],
+      "minEdgeCasesPerTask": 0,
+      "requires": [],
+      "forbids": ["docs/prd.md", "architecture.yaml", "decisions/"],
+      "notes": [
+        "Every task entry STILL carries repo-root-relative paths verbatim in file_ownership, in each step, and in verification commands.",
+        "No Context section, no diagrams, no PRD."
+      ]
+    },
+    "MEDIUM": {
+      "label": "MEDIUM — a real feature with real risk",
+      "intentDefaults": ["GREENFIELD-MODULE", "BROWNFIELD-FEATURE"],
+      "roundCap": 3,
+      "artifacts": [
+        { "path": ".archgen/<slug>/tasks.yaml", "required": true, "purpose": "the task contract" },
+        { "path": ".archgen/<slug>/plans/<slug>.md", "required": true, "purpose": "the full plan" }
+      ],
+      "planSections": ["Context", "Per-task sections", "Verification steps"],
+      "minEdgeCasesPerTask": 3,
+      "requires": ["plan context of 2-4 paragraphs", "per-task sections with approach + edge cases + out-of-scope", "ordered runnable verification steps"],
+      "forbids": ["docs/prd.md", "architecture.yaml"],
+      "notes": [
+        "One `<id> — <title>` heading per task, in dependency order.",
+        "Verification steps are repo-root-relative (no `../`, no `--plan .`), exact, and runnable."
+      ]
+    },
+    "LARGE": {
+      "label": "LARGE — a full professional stack (greenfield from scratch)",
+      "intentDefaults": ["GREENFIELD-SYSTEM"],
+      "roundCap": 6,
+      "artifacts": [
+        { "path": ".archgen/<slug>/answers.yaml", "required": true, "purpose": "the captured requirements" },
+        { "path": ".archgen/<slug>/docs/prd.md", "required": true, "purpose": "the product requirements — FR ids tasks cite" },
+        { "path": ".archgen/<slug>/architecture.yaml", "required": true, "purpose": "the contract source of truth" },
+        { "path": ".archgen/<slug>/tasks.yaml", "required": true, "purpose": "the task contract" },
+        { "path": ".archgen/<slug>/plans/<slug>.md", "required": true, "purpose": "the full plan" },
+        { "path": ".archgen/<slug>/decisions/NNNN-<title>.md", "required": false, "purpose": "formal ADRs (one per decision)" },
+        { "path": ".archgen/<slug>/docs/<module>.md", "required": false, "purpose": "per-module diagrams (≤15 nodes each)" }
+      ],
+      "planSections": ["Context", "Per-task sections", "Edge-case matrices", "Verification steps"],
+      "minEdgeCasesPerTask": 3,
+      "requires": [
+        "docs/prd.md written BEFORE tasks.yaml (~1 page per major module)",
+        "architecture.yaml with naming_conventions, data_contracts, api_contracts and environment_matrix",
+        "an edge-case matrix per task (every row maps to an acceptance bullet)",
+        "per-module diagrams (≤15 nodes each) plus one integration diagram",
+        "MEDIUM-grade plan sections"
+      ],
+      "forbids": [],
+      "notes": [
+        "Requirement ids (FR-<MODULE>-nn) are defined in docs/prd.md and cited from tasks.yaml acceptance lines.",
+        "architecture.yaml is the anti-hallucination source of truth: tasks cite its keys instead of restating shapes from memory."
+      ]
+    }
+  },
+  "edgeCaseClasses": [
+    "empty/null",
+    "boundary values",
+    "authz denied",
+    "concurrent/conflicting write",
+    "failure/retry path",
+    "i18n/formatting edge"
+  ],
+  "edgeCaseExtras": {
+    "infra": ["partial-failure recovery", "rollback story"],
+    "maxRowsPerMatrix": 10
+  }
+}

package/assets/harness-mcp.json

@@ -0,0 +1,159 @@
+{
+  "version": 1,
+  "_readme": [
+    "Authoritative MCP wiring registry. ONE source of truth: the MCP server,",
+    "the CLI installer and the docs must agree.",
+    "",
+    "TWO SERVERS: 'entries'/'npxEntries' describe the CodeGraph server;",
+    "'archgenEntries'/'archgenNpxEntries' describe archgen's own server. Both",
+    "are written by the SAME writer (core/harness-wiring.mjs), so a platform",
+    "that works for one works for the other.",
+    "",
+    "ENTRY SHAPES: every platform has a DIFFERENT top-level key and a DIFFERENT",
+    "server-object shape. The four known top-level keys are mcpServers (claude,",
+    "cursor, windsurf, gemini, antigravity, kiro, trae), servers (vscode/copilot),",
+    "mcp (opencode), context_servers (zed). Codex CLI uses TOML ([mcp_servers.<id>]).",
+    "",
+    "COMMAND SHAPE: the server entries below are the ones the official installers",
+    "write — keep them byte-compatible, or the MCP server never connects.",
+    "The CodeGraph server also runs a FILE WATCHER, so the index stays live after",
+    "the one-time init; nothing is re-indexed by hand.",
+    "",
+    "The command below is the resolved absolute path to the binary when one is",
+    "found on PATH; the wiring layer substitutes it at write time. When no binary",
+    "is available the npx form is used instead."
+  ],
+  "package": "@colbymchenry/codegraph",
+  "entries": {
+    "stdio": { "type": "stdio", "command": "codegraph", "args": ["serve", "--mcp"] },
+    "stdioNoType": { "command": "codegraph", "args": ["serve", "--mcp"] },
+    "opencodeLocal": { "type": "local", "command": ["codegraph", "serve", "--mcp"], "enabled": true }
+  },
+  "npxEntries": {
+    "stdio": { "type": "stdio", "command": "npx", "args": ["-y", "@colbymchenry/codegraph", "serve", "--mcp"] },
+    "stdioNoType": { "command": "npx", "args": ["-y", "@colbymchenry/codegraph", "serve", "--mcp"] },
+    "opencodeLocal": { "type": "local", "command": ["npx", "-y", "@colbymchenry/codegraph", "serve", "--mcp"], "enabled": true }
+  },
+  "archgenPackage": "archgen-mcp",
+  "archgenEntries": {
+    "stdio": { "type": "stdio", "command": "archgen-mcp", "args": [] },
+    "stdioNoType": { "command": "archgen-mcp", "args": [] },
+    "opencodeLocal": { "type": "local", "command": ["archgen-mcp"], "enabled": true }
+  },
+  "archgenNpxEntries": {
+    "stdio": { "type": "stdio", "command": "npx", "args": ["-y", "archgen-mcp"] },
+    "stdioNoType": { "command": "npx", "args": ["-y", "archgen-mcp"] },
+    "opencodeLocal": { "type": "local", "command": ["npx", "-y", "archgen-mcp"], "enabled": true }
+  },
+  "harnesses": {
+    "claude": {
+      "label": "Claude Code",
+      "codegraphTarget": "claude",
+      "detectHome": [".claude", ".claude.json"],
+      "detectProject": [".claude", ".mcp.json"],
+      "configs": {
+        "global": { "path": "~/.claude.json", "key": "mcpServers", "entry": "stdio" },
+        "project": { "path": ".mcp.json", "key": "mcpServers", "entry": "stdio" }
+      }
+    },
+    "cursor": {
+      "label": "Cursor",
+      "codegraphTarget": "cursor",
+      "detectHome": [".cursor"],
+      "detectProject": [".cursor"],
+      "configs": {
+        "global": { "path": "~/.cursor/mcp.json", "key": "mcpServers", "entry": "stdio" },
+        "project": { "path": ".cursor/mcp.json", "key": "mcpServers", "entry": "stdio" }
+      }
+    },
+    "opencode": {
+      "label": "OpenCode",
+      "codegraphTarget": "opencode",
+      "detectHome": [".config/opencode"],
+      "detectProject": [".opencode", "opencode.json", "opencode.jsonc"],
+      "_note": "OpenCode's global config is JSONC (opencode.jsonc) — codegraph's own installer writes it correctly; our writer refuses non-JSON files on purpose, so this entry is a fallback only.",
+      "configs": {
+        "global": { "path": "~/.config/opencode/opencode.json", "key": "mcp", "entry": "opencodeLocal" },
+        "project": { "path": "opencode.json", "key": "mcp", "entry": "opencodeLocal" }
+      }
+    },
+    "codex": {
+      "label": "Codex CLI",
+      "codegraphTarget": "codex",
+      "detectHome": [".codex"],
+      "detectProject": [".codex"],
+      "configs": {
+        "global": { "path": "~/.codex/config.toml", "format": "toml", "key": "mcp_servers.codegraph", "entry": "toml" },
+        "project": { "path": ".codex/config.toml", "format": "toml", "key": "mcp_servers.codegraph", "entry": "toml" }
+      }
+    },
+    "gemini": {
+      "label": "Gemini CLI",
+      "codegraphTarget": "gemini",
+      "detectHome": [".gemini"],
+      "detectProject": [".gemini"],
+      "configs": {
+        "global": { "path": "~/.gemini/settings.json", "key": "mcpServers", "entry": "stdio" },
+        "project": { "path": ".gemini/settings.json", "key": "mcpServers", "entry": "stdio" }
+      }
+    },
+    "antigravity": {
+      "label": "Antigravity",
+      "codegraphTarget": "antigravity",
+      "detectHome": [".gemini/config"],
+      "detectProject": [".agents/mcp_config.json"],
+      "configs": {
+        "global": { "path": "~/.gemini/config/mcp_config.json", "key": "mcpServers", "entry": "stdio" },
+        "project": { "path": ".agents/mcp_config.json", "key": "mcpServers", "entry": "stdio" }
+      }
+    },
+    "kiro": {
+      "label": "Kiro",
+      "codegraphTarget": "kiro",
+      "detectHome": [".kiro"],
+      "detectProject": [".kiro"],
+      "configs": {
+        "global": { "path": "~/.kiro/settings/mcp.json", "key": "mcpServers", "entry": "stdioNoType" },
+        "project": { "path": ".kiro/settings/mcp.json", "key": "mcpServers", "entry": "stdioNoType" }
+      }
+    },
+    "windsurf": {
+      "label": "Windsurf",
+      "codegraphTarget": null,
+      "detectHome": [".codeium/windsurf"],
+      "detectProject": [".windsurf"],
+      "configs": {
+        "global": { "path": "~/.codeium/windsurf/mcp_config.json", "key": "mcpServers", "entry": "stdioNoType" }
+      }
+    },
+    "vscode": {
+      "label": "VS Code / Copilot",
+      "codegraphTarget": null,
+      "detectHome": [],
+      "detectProject": [".vscode", ".github/copilot-instructions.md"],
+      "configs": {
+        "project": { "path": ".vscode/mcp.json", "key": "servers", "entry": "stdio" }
+      }
+    },
+    "zed": {
+      "label": "Zed",
+      "codegraphTarget": null,
+      "detectHome": [".config/zed"],
+      "detectProject": [".zed"],
+      "configs": {
+        "global": { "path": "~/.config/zed/settings.json", "key": "context_servers", "entry": "stdioNoType" },
+        "project": { "path": ".zed/settings.json", "key": "context_servers", "entry": "stdioNoType" }
+      }
+    },
+    "trae": {
+      "label": "Trae",
+      "codegraphTarget": null,
+      "detectHome": [".trae"],
+      "detectProject": [".trae"],
+      "configs": {
+        "project": { "path": ".trae/mcp.json", "key": "mcpServers", "entry": "stdioNoType" }
+      }
+    }
+  },
+  "codegraphNativeTargets": ["claude", "cursor", "opencode", "codex", "gemini", "antigravity", "kiro"]
+}

package/assets/mcp-template.json

@@ -0,0 +1,45 @@
+{
+  "_readme": [
+    "Generic MCP server declarations. COPY the variant matching your platform",
+    "(references/platforms.md owns file paths + top-level keys).",
+    "Keys DIFFER per platform: mcpServers | servers | mcp | context_servers.",
+    "Remote URL field varies: url | serverUrl | httpUrl.",
+    "",
+    "CodeGraph is wired automatically by the archgen MCP server (the per-platform",
+    "shapes live in packages/mcp/assets/harness-mcp.json) — it needs no entry here.",
+    "This file documents the SHAPE for any other MCP server.",
+    "Prefer the archgen_setup tool to hand-editing harness configs: it detects the",
+    "harness, resolves the absolute binary path, writes the right shape, and is",
+    "idempotent."
+  ],
+  "_claude_code_cursor_windsurf_kiro_gemini": {
+    "mcpServers": {
+      "context7-remote": {
+        "type": "http",
+        "url": "https://mcp.context7.com/mcp",
+        "headers": { "Authorization": "Bearer ${env:CONTEXT7_TOKEN}" }
+      }
+    }
+  },
+  "_vscode_copilot": {
+    "servers": {
+      "context7": { "type": "http", "url": "https://mcp.context7.com/mcp" }
+    },
+    "inputs": []
+  },
+  "_opencode": {
+    "mcp": {
+      "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "enabled": true }
+    }
+  },
+  "_zed": {
+    "context_servers": {
+      "context7": { "url": "https://mcp.context7.com/mcp" }
+    }
+  },
+  "_codex_toml": {
+    "_note": "TOML in ~/.codex/config.toml",
+    "mcp_servers.context7": { "url": "https://mcp.context7.com/mcp" }
+  },
+  "_antigravity_warning": "Remote servers MUST use serverUrl (url/httpUrl are rejected): { mcpServers: { name: { serverUrl: '...' } } }"
+}