spec-mcp-setup

name	spec-mcp-setup
description	Install, configure, verify, and refresh required harness runtime readiness facts for spec-first workflows on Claude Code, Codex, Kiro, Qoder, or Cursor.
argument-hint	[bare auto setup] [--check|--verify-only|--plan] [--only codegraph,graphify] [--refresh] [--repo <path>] [--requirement-workspace <repo-relative-path>]

Runtime Setup

spec-mcp-setup is the current runnable entrypoint for the Runtime Setup workflow across supported hosts. The target user-facing alias remains spec-runtime-setup once the host alias contract is implemented; legacy host-specific setup spellings normalize to spec-mcp-setup and are not separate product surfaces. Runtime Setup prepares deterministic host/runtime facts for spec-first workflows. It installs or verifies required MCP servers and helper tooling, writes setup-owned project facts, and reports concrete next actions. It does not provide code-understanding authority; downstream workflows use bounded direct source reads, rg, ast-grep, git diff, tests/logs, and user-provided evidence.

Contract Summary

Field	Contract
When to use	Host runtime setup, MCP setup, helper-tool readiness, missing runtime assets, or project-local setup fact refresh.
When not to use	Ordinary planning, implementation, review, debugging, or code impact questions that can proceed from direct source evidence.
Inputs	Current host, repo target, skills/spec-mcp-setup/mcp-tools.json, helper installer facts, host config state, git/workspace target facts, and project instructions.
Outputs	Readiness ledger v2, provider readiness v2 facts, generated runtime manifest freshness, setup scenario fingerprint, optional project setup facts under .spec-first/config/, and a grouped status block.
Artifacts	.spec-first/config/tool-facts.json, .spec-first/config/runtime-capabilities.json, and .spec-first/workspace/scenario-fingerprint-setup.json when applicable.
Failure modes	Missing dependencies, host config write failure, ambiguous parent workspace target, symlink escape, invalid registry schema, helper install failure, or unsupported host.
Downstream consumers	using-spec-first, plan/work/review/debug workflows, doctor/update guidance, and humans repairing setup.

Core boundary: scripts prepare deterministic readiness facts; LLM workflows decide how to use those facts. Setup must not make semantic code-understanding judgments or require any external analysis service before ordinary work can continue. After CodeGraph/Graphify readiness is prepared, setup may recommend spec-rule-miner as a next step for evidence-backed project AI coding rules; it must not invoke rule mining, synthesize rules, or write docs/ai/project-rules.md.

Scenario Capability

Follows docs/contracts/workflows/scenario-capability-matrix.md (default). Overrides: none

Examples As Context

When editing or reviewing this workflow prompt, or when running fresh-source eval for setup posture drift, read skills/spec-mcp-setup/evals/examples.json as examples-as-context. These examples are not a deterministic router, runtime-readiness gate, or substitute for LLM judgment during ordinary setup runs.

Source Of Truth

skills/spec-mcp-setup/mcp-tools.json is the current source directory for the machine registry of baseline MCP servers plus explicit opt-in MCP capability entries and centralized external dependency pins. Schema version is 7. Current required baseline tools include sequential-thinking and context7; optional MCP entries must carry opt_in.explicit_consent_required=true and are admitted only through the bare Runtime Setup default provider pack or explicit --only selection. The directory name remains spec-mcp-setup during the entrypoint rename to avoid a broad source/runtime path migration in the same slice.

Generated runtime mirrors under .claude/, .codex/, .cursor/skills/, .cursor/spec-first/, .kiro/, .qoder/, and .agents/skills/ are not source. .cursor/mcp.json is host-local config output, not source truth. If setup prose or scripts change, update source first and use spec-first init only for runtime regeneration.

Required Harness Runtime

mcp-tools.json owns required baseline MCP server definitions, explicit opt-in MCP capability entries, and external dependency package/version pins under external_dependencies. helper-tools.json is the single source for helper tooling readiness, baseline blocking, install safety metadata, and shell/PowerShell runner requirements. provider-tools.json is the source for non-MCP provider helpers installed through install-helpers.*; provider entries reference centralized dependency pins instead of duplicating package versions. Required helper tooling outside mcp-tools.json is installed and verified by install-helpers.* and check-health, then recorded under helper_tools and items[] in setup facts.

Required helper tooling must not be added to mcp-tools.json. Current helper checks include agent-browser and ast-grep capability detection. Use install-helpers.* --verify-only for read-only verification, and use the install path only when setup explicitly needs repair. The agent-browser repair path may run npx -y skills@latest add https://github.com/vercel-labs/agent-browser --skill agent-browser -g -y, should respect NPM_CONFIG_REGISTRY, and may run agent-browser install --with-deps when browser automation support is required.

Optional provider readiness is reported through provider_readiness[] (provider-readiness.v2). Setup may populate lifecycle display bits such as installed, configured, indexed, server_reachable, and query_verified, plus setup-owned runtime metadata such as native_interfaces, first_generation, steady_state, and usage_note. steady_state may include hook readiness facts for provider-native refresh setup, such as Graphify hook_installed, hook_verified, and hook_status. Downstream decision health is still driven by readiness_status; lifecycle, first-generation, and hook fields explain boundaries and next actions, not semantic truth. The human status table may derive readiness_scope and probe_status from existing lifecycle bits to separate install/index readiness from real server/query probes; these display columns are not new machine schema fields. Provider self-reported fresh maps to unknown; provider self-reported stale may map to stale because it is conservative. query_verified=true is reserved for a real probe or explicit real-environment signal, not for package installation alone. A false or missing server_reachable / query_verified display value means the probe is not verified in this setup run unless a failure reason says otherwise; it must not be summarized as confirmed provider query availability.

Project Preflight / Local Setup

Project-local setup writes .spec-first/config/tool-facts.json, .spec-first/config/runtime-capabilities.json, and when applicable .spec-first/workspace/scenario-fingerprint-setup.json. The readiness ledger and runtime capabilities include generated_runtime_manifest.status (current, stale, missing, or unknown) based only on state.manifestVersion versus the bundled manifest version; this is a deterministic freshness fact, not proof that generated prose is semantically correct. Scenario fingerprint wrapper failures are warn-and-continue: report scenario_fingerprint_setup status and keep the rest of setup actionable instead of blocking ordinary direct-evidence workflows.

Setup Posture And Project Conventions

Runtime Setup follows an Explore -> Present -> Decide -> Write posture:

1. Explore host, target repo, generated runtime manifest, existing setup facts, .spec-first/config.local.yaml, verification profile visibility, provider artifacts, and project instructions.
2. Present discovered facts, missing dependencies, local-only overrides, provider first-generation/refresh actions, generated runtime freshness, and explicit non-actions before applying setup changes.
3. Decide only where the runtime setup workflow has authority: install/verify helper tools, configure host MCP/runtime wiring, refresh setup-owned facts, or choose a documented degraded path. Team workflow conventions and semantic project decisions remain LLM/owner judgment in downstream workflows.
4. Write only setup-owned facts, supported local config examples, host runtime config through documented targets, and generated runtime refreshes through spec-first init. Do not write team-shared tracker policy, label vocabulary, external PR request-surface policy, issue acceptance decisions, or durable rejected-scope decisions from setup.

.spec-first/config.local.yaml is a local-only override file, not team-shared source of truth. The current supported consumer key is verification_profile_path, read by the verification profile loader as a local execution preference. Document output/provider keys in the template are reserved future hints unless an implemented consumer and focused tests exist. Missing local config is not a blocker; defaults remain advisory and must not be reported as repo truth.

If setup later reports project convention facts, they must be deterministic existence facts only, such as whether CONTEXT.md, CONTEXT-MAP.md, docs/adr/, or a team standards index exists. Setup must not judge whether terminology is correct, an ADR applies, a proposed issue/PR should be accepted or rejected, an out-of-scope concept matches, or implementation satisfies a request.

Host Authority And Write Safety

The current public entrypoint is spec-mcp-setup; the host runtime surface that invoked it is authoritative host evidence. Generated host-specific runtime surfaces must pin MCP_SETUP_HOST=<host> before invoking setup mutation scripts. install-mcp.*, configure-host.*, and uninstall-mcp.* fail closed without an explicit canonical MCP_SETUP_HOST=claude|codex|kiro|qoder|cursor; they must not infer mutation targets from PATH, generated runtime directories, old .spec-first/config/* facts, or host config files from another platform. Read-only detection/report paths may surface advisory host candidates, but those candidates are not write authority.

Before any host config write or setup-owned facts refresh, the workflow must anchor the write target to a fresh detect-host.* JSON result driven by an explicit entrypoint host pin. Previous setup facts are drift comparison evidence only: if they disagree with the current entrypoint host, report a host-marker drift and refresh setup-owned facts for the current host instead of treating the previous host as current. Never manually choose .kiro/settings/mcp.json, .qoder/settings.local.json, .cursor/mcp.json, Codex TOML, or Claude managed/user config from prose alone.

Do not use host file-edit tools such as Write, Update, or Edit to modify .spec-first/config/tool-facts.json, .spec-first/config/runtime-capabilities.json, or host MCP config files. Setup-owned facts must be written only by verify-tools.* / write-setup-facts.*; host MCP config must be written only by configure-host.* / install-mcp.* after host detection.

Workflow Modes

• --check: inspect current dependency/runtime status only; do not write setup facts, host config, or install tools.
• --verify-only / --refresh-facts: verify readiness and refresh setup-owned facts; do not install tools or edit host config.
• --plan: render install/config operations and safety results; do not write setup facts, host config, or install tools.
• Bare invocation (spec-mcp-setup in the current host): primary automatic setup path. Show the current CodeGraph/Graphify provider pack, project/provider runtime writes, host config writes, first-generation commands, refresh hooks, and explicit non-actions, then run install-init and verification to completion without an extra confirmation prompt. Treat the bare workflow invocation as explicit opt-in for the default provider pack. Do not ask the user to run internal scripts directly.
• --only <ids>: headless/subset apply path. --only codegraph, --only graphify, or --only codegraph,graphify narrows provider selection and also does not require a confirmation prompt.
• --refresh: Graphify explicit incremental refresh path. Use with --only graphify when .graphify/ already exists, or when a legacy graphify-out/ artifact should be regenerated into provider-native .graphify/, and the user wants setup to run provider-native graphify update . (code-only, no LLM) instead of only verifying/installing provider readiness. This is not full semantic extraction; missing artifacts still use first-generation graphify extract . with graphify update . fallback.
• --requirement-workspace <repo-relative-path>: optional Graphify input-scope override. Omit it for normal project-workspace setup; default input scope is the resolved project workspace.
• --user-scope: Kiro/Qoder/Cursor opt-in for writing user-level MCP config. Without this flag, KIRO_USER_SCOPE=1, QODER_USER_SCOPE=1, or CURSOR_USER_SCOPE=1, script-level setup writes only workspace .kiro/settings/mcp.json for Kiro, local .qoder/settings.local.json for Qoder, or project .cursor/mcp.json for Cursor, including when invoked indirectly from a generated host skill/command.

Graphify setup uses the controlled helper/provider route. Public setup does not ask users to set provider consent environment variables; bare setup or --only graphify is the public opt-in, and the orchestration internally applies helper consent. Direct env consent remains only an advanced/CI escape hatch for invoking install-helpers.* directly. Missing --requirement-workspace defaults to the resolved project workspace and writes provider artifacts under provider-native project-root .graphify/; absolute, escaping, symlink-escaping, or nonexistent explicit overrides skip first generation with a structured next action. When selected, setup installs the pinned Graphify dependency declared in mcp-tools.json, resolves the graphify CLI from the user's original PATH or the provider-standard $HOME/.local/bin/graphify path, and uses that resolved command for current-host project skill install such as graphify install --project --platform codex, scriptable first-generation graphify extract ., code-only/incremental fallback graphify update ., a single bounded graphify update . --force repair only after Graphify emits Refusing to overwrite plus a force hint, query probe, and hook install/status. After npm install or upgrade, if graphify on the original PATH is a stale symlink and setup can resolve a pinned executable from the provider-standard/npm global bin candidates, setup backs up the stale symlink and repoints it to the pinned executable; ordinary files, non-writable paths, and ambiguous cases stay report-only. If project-root .graphify/graph.json or GRAPH_REPORT.md already exists and --refresh was not supplied, setup treats that as a steady-state install check: verify or install the current-host Graphify project skill/instruction section, probe query usability, verify or install hook refresh, report graphify-refresh-recommended, and skip graph regeneration. Legacy graphify-out/graph.json or graphify-out/GRAPH_REPORT.md is compatibility-only refresh-needed evidence; it must not be treated as the current .graphify/ artifact contract. --refresh is the explicit incremental graph refresh path; for the default project-root scope it runs provider-native graphify update . (re-extracts code files without LLM semantic extraction), with the same bounded --force repair only after provider overwrite refusal. After provider project install writes AGENTS.md or CLAUDE.md, setup normalizes only the provider-owned ## graphify instruction section to the resolved CLI/manual-visibility/direct-source-fallback wording; it does not vendor or rewrite the Graphify skill itself. If .graphify/graph.json or .graphify/GRAPH_REPORT.md exists after either path, setup targets project-level graphify hook install so provider-native refresh keeps the code graph usable after setup; when the provider-owned hook would otherwise fail because git hook environments cannot see the resolved Graphify CLI directory, setup may add a marked project-local PATH repair block to Graphify-installed hook files before verifying hook status. It does not edit shell profiles, overwrite non-symlink command files, start graphify watch, run full semantic extraction for ordinary repeat setup, or install the optional Graphify MCP server. $graphify . / /graphify . is the provider assistant UX after setup; setup-internal first generation uses CLI extraction/update because the current session may not dynamically load the newly installed skill.

CodeGraph setup uses the controlled MCP/provider route. When selected, setup installs the pinned CodeGraph dependency declared in mcp-tools.json, configures host MCP with codegraph serve --mcp, runs codegraph init, and probes codegraph status. If status reports Pending Changes or asks for codegraph index -f, setup runs one bounded codegraph sync and re-runs codegraph status; any remaining pending changes or sync failure is action-required with diagnostics. If the post-sync status still asks for codegraph index -f, setup runs one bounded full reindex and rechecks status. Full reindex failure preserves the existing .codegraph/ artifact and reports degraded/actionable readiness instead of erasing the index. These one-time sync/reindex branches are install-init repair, not spec-first steady-state ownership.

Bare Setup Flow

For bare spec-mcp-setup, do this inside the skill:

1. Resolve the project target and render the provider plan with setup-plan-renderer.cjs --mode guided-apply --repo-root <resolved-project-root>.
2. Present a compact install-init preview block naming:
   • selected optional providers: codegraph, graphify;
   • CodeGraph install/init: pinned dependency install from mcp-tools.json, codegraph init, codegraph status, one bounded codegraph sync if status reports Pending Changes or codegraph index -f, one bounded codegraph index -f only if the full-rebuild advisory remains after sync, .codegraph/codegraph.db, and host MCP command codegraph serve --mcp;
   • Graphify install/init: pinned dependency install from mcp-tools.json or supported fallback, resolved Graphify CLI command visibility (PATH or provider-standard $HOME/.local/bin/graphify), graphify install --project --platform <current-host> when the current-host project skill is missing, existing .graphify/ steady-state install checks, legacy graphify-out/ compatibility detection, graphify extract . for first generation, explicit --refresh using incremental/code-only graphify update . for existing project-root graphs, one bounded graphify update . --force only after provider overwrite refusal, project-root .graphify/, and graphify hook install/status;
   • provider/project writes: .codegraph/, .graphify/, legacy graphify-out/, .git/hooks/, .codex/skills/graphify/, .kiro/skills/graphify/, .qoder/skills/graphify/, .codex/hooks.json, AGENTS.md, .claude/skills/graphify/, CLAUDE.md, and .graphify_version when the selected host/provider writes them;

• host-owned writes: Claude/Codex/Kiro/Qoder/Cursor MCP config for CodeGraph when selected; Kiro user-level config requires explicit --user-scope/KIRO_USER_SCOPE=1, otherwise workspace .kiro/settings/mcp.json is the only Kiro write target; Qoder user-level config requires explicit --user-scope/QODER_USER_SCOPE=1, otherwise .qoder/settings.local.json is the only Qoder write target; Cursor user-level config requires explicit --user-scope/CURSOR_USER_SCOPE=1, otherwise .cursor/mcp.json is the only Cursor write target;
• .gitignore policy: spec-first init's managed block ignores .codegraph/, the provider-native .graphify/ artifact directory, and legacy graphify-out/ artifacts; setup does not auto-add, auto-commit, or promote Graphify output to source truth;
• non-actions: no graphify watch/long-running daemon, no optional Graphify MCP server install, no generated artifact promotion to docs/ or source truth, no automatic spec-rule-miner invocation, and no project-rule file writes.

3. If the plan reports an unknown provider selection or unresolved target, stop with the blocked reason and next action instead of installing.
4. Otherwise, run the internal apply path with --only codegraph,graphify plus any --repo/--folder/--requirement-workspace args already supplied, then run verification/fact refresh and render the final grouped status block. If CodeGraph/Graphify readiness is ready or degraded-but-usable and no setup blocker remains, the final next step should suggest running spec-rule-miner separately to mine project rules from source evidence.

Workflow

1. Identify the current host from the generated host-specific runtime surface invoking the unified spec-mcp-setup entrypoint. The target renamed entrypoint is spec-runtime-setup once the alias contract lands.
2. If invoked from a parent workspace, select an explicit child repo or intentionally run setup for all supported child repos. Writes must stay within the selected target.
3. Read mcp-tools.json, validate schema version, and verify every required baseline tool plus explicit opt-in MCP entry has deterministic install, host-config, detection, and summary metadata.
4. Run detect-tools.* or install-mcp.* as appropriate. Warm required package-backed MCP tools, admit optional MCP entries only through the documented default provider pack or explicit --only selection, write host config only through documented host targets, and record structured status.
5. Run install-helpers.* for required helper tooling and explicitly approved non-MCP provider helpers. Bare setup or --only graphify is enough public consent for Graphify; the script layer may translate that to helper env consent internally. Approved provider first generation and project-local auto-refresh setup may run only through controlled script cases or provider-native bounded CLI commands invoked through the resolved CLI path, then helper/provider readiness facts are collected. If graphify extract . fails in the default project-root scope, the script should try code-only graphify update . before returning failed readiness. If Graphify is installed but not visible on the user's original PATH, report the manual visibility action instead of editing shell profiles; for provider-owned git hooks, setup may repair only the project-local Graphify hook PATH block so hook verification can succeed without global profile edits. If Graphify hook install still fails after bounded repair, report readiness_status=degraded with next_actions instead of marking hook refresh verified.
6. Run verify-tools.* to write the readiness ledger, reconcile host pointer facts, write project setup facts, and render the grouped status block. Read generated_runtime_manifest.status separately from baseline_ready; baseline_ready=true must not hide stale generated runtime. If the status is stale or missing, refresh runtime with the topology-appropriate command (spec-first init -y for the current repo or parent workspace runtime, spec-first init --repo <child> -y for one child repo, or explicit spec-first init --all-repos -y only for intentional batch child-root refresh), then rerun verification. If spec-first update just ran and the status is still stale, treat that as degraded refresh evidence and surface the same fallback command instead of reporting runtime freshness as ready.
7. Report the status exactly enough for the user to act: ready rows need no action; action-required rows name the missing dependency/config/target step; generated runtime manifest rows name the init refresh command when stale or missing.

Output Shape

The final setup output should contain:

• Execution result: separate Required MCP/helper dependencies and Generated runtime manifest rows; report baseline_ready as dependency readiness and generated_runtime_manifest.status as generated runtime freshness.
• MCP servers: required baseline MCP tool dependency/host/project readiness, explicit opt-in MCP entries when selected or detected, and next action.
• Helper tools: helper install and readiness status.
• Provider tools: provider readiness status, derived readiness_scope / probe_status, and lifecycle display bits when present. Summaries must distinguish install/index readiness from server/query verification.
• Host configured dependencies: configured MCP/hooks/allowlist/setup/verification command facts.
• Install safety: helper install source, risk, review, and mirror provenance.
• Project setup facts: status for tool-facts.json and runtime-capabilities.json.
• Verification profile: current verification profile visibility placeholder; full profile execution is v1.13 scope.
• Next steps: either fix action-required rows, choose an explicit child repo, continue to the user-intent workflow, or suggest spec-rule-miner as a separate follow-up after CodeGraph/Graphify readiness is prepared. This suggestion is advisory; setup must not treat rule-miner output as setup readiness and must not call spec-rule-miner automatically.

tool-facts.json records setup-owned tool and helper readiness:

{
  "schema_version": "tool-facts.v2",
  "tools": {},
  "helper_tools": {},
  "items": [],
  "configured_dependencies": [],
  "schema_capabilities": [
    "items",
    "configured_dependencies",
    "tool-existence",
    "provider-readiness-generic"
  ],
  "source": {
    "repo_status": "git-repo"
  }
}

runtime-capabilities.json should record direct evidence posture instead of provider capabilities:

{
  "schema_version": "runtime-capabilities.v1",
  "direct_evidence": {
    "bounded_source_reads": true,
    "ripgrep": true,
    "ast_grep": true,
    "git_diff": true,
    "tests_and_logs": true
  }
}

Boundaries

Setup does:

• verify Node/npm/npx and required helper dependencies;
• warm package-backed MCP servers when configured by mcp-tools.json;
• write host MCP config through managed/user host targets;
• write Kiro MCP config to workspace .kiro/settings/mcp.json by default, and to ~/.kiro/settings/mcp.json only after explicit user-scope opt-in;
• write Qoder MCP config to local .qoder/settings.local.json by default, and to ~/.qoder/settings.json only after explicit user-scope opt-in;
• write Cursor MCP config to project .cursor/mcp.json by default, and to ~/.cursor/mcp.json only after explicit user-scope opt-in;
• write project-local setup facts;
• perform explicit provider-native first generation for approved providers when the target workspace is resolved, or verify Graphify install readiness without regenerating the graph when a project-root Graphify artifact already exists and no explicit --refresh was requested;
• perform bounded provider-native setup repair where deterministic and documented, such as incremental/code-only graphify update . after default project-root graphify extract . failure or explicit --refresh, one graphify update . --force after Graphify overwrite refusal plus force hint, one codegraph sync after pending/full-rebuild status, or one codegraph index -f after sync cannot clear the full-rebuild advisory;
• perform provider-native project-local auto-refresh setup for approved providers when available, such as Graphify graphify hook install, including bounded project-local PATH repair for Graphify-installed hook files when the resolved CLI is off the user's original PATH;
• classify parent workspace target ambiguity and foreign residual indicators as advisory facts.

Setup does not:

• start watchers or long-running daemons;
• install the optional Graphify MCP server;
• run provider first generation from --check, --plan, --verify-only, or invalid explicit workspace override paths;
• treat provider indexes or query probes as semantic code evidence;
• treat setup facts as semantic code evidence;
• invoke spec-rule-miner, synthesize project rules, or write docs/ai/project-rules.md;
• treat .spec-first/config.local.yaml as team-shared workflow policy;
• decide issue/PR category, state, scope, accept/reject status, or implementation truth;
• hand-edit generated runtime mirrors as source;
• block ordinary plan/work/review/debug when direct source evidence is sufficient.

Verification

Focused setup changes should run the narrowest relevant checks:

bash skills/spec-mcp-setup/scripts/check-health
bash -n skills/spec-mcp-setup/scripts/*.sh
npm run test:mcp-setup
node --check src/cli/commands/internal.js src/cli/helpers/scenario-fingerprint.js

For cross-host changes, also run npm run typecheck, npm run test:unit, npm run test:smoke, and spec-first init after source validation.