@anyforge/mcp-server 2.5.0 → 3.1.0

package/README.md

@@ -9,10 +9,28 @@ The server is a thin client over AnyForge's key-authenticated control
 API (`/api/v1/control/*`). It holds no business logic and never needs a
 Firebase login.
 
-> **User-facing setup guide:** [Drive AnyForge from Claude CLI](https://anyforge.ai/docs/mcp-server)
+> **User-facing setup guide:** [Connect AnyForge to Claude, Cursor and VS Code](https://anyforge.ai/docs?page=mcp-server)
 > (`apps/www/content/docs/mcp-server.md`). This README is the in-repo
 > developer reference; the docs page is the canonical install walkthrough.
 
+## Platform guide for connected agents
+
+The server advertises a static `anyforge-platform` guide without tenant data or
+extra authority. MCP clients can load it on demand with the `platform_guide`
+prompt or the `anyforge://guide/platform` resource. The resource also exposes
+the guide's three reference files.
+
+For an Agent Skills-compatible local host, install the same guide with:
+
+```bash
+npx @anyforge/control skill install anyforge-platform
+```
+
+The default is the project-local `.agents/skills/anyforge-platform/` directory.
+Use `--scope user --client claude` or `--scope user --client codex` for the
+corresponding user-level directory. Existing files are preserved unless
+`--force` is explicit.
+
 ## 1. Authorise this machine (once)
 
 ```bash
@@ -61,28 +79,146 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_submit_approval` | approve | Approve or reject a HIL (resumes the crew) |
 | `anyforge_list_programs` | read | List programs |
 | `anyforge_get_program` | read | Get a program |
-| `anyforge_list_initiatives` | read | List initiatives with progress + spend |
-| `anyforge_get_initiative` | read | Initiative + crews + burn-down |
+| `anyforge_get_program_brief_context` | read | Read a program's structured Brief, version history, legacy mirror, and ICE readiness |
+| `anyforge_save_program_brief_version` | write | Save a complete structured Brief version; archives the prior active version and replaces the retired free-form writer |
+| `anyforge_update_program` | write | Update a program's name / status / owner / target date / coverage goal / tags |
+| `anyforge_delete_program` | write | Delete a program; `deleteChildren: true` also deletes child initiatives + work items (else they're detached) |
+| `anyforge_update_program_initiative` | write | Enrich one existing program initiative and return changed fields or a structured no-op |
+| `anyforge_close_program_initiative` | write | Preview then close one program initiative with a supported close reason |
+| `anyforge_close_program_work_items_as_fixed` | write | Preview then batch-close non-terminal program work items fixed outside AnyForge |
+| `anyforge_list_initiatives` | read | List initiatives with progress + budget. Returns ONE PAGE (50 default, 100 max) — continue with `meta.nextCursor`, or narrow with `programId`, `status`, `priority`, `owner`, `tag`, `search`. Unknown arguments are rejected; the page echoes `appliedFilters` |
+| `anyforge_get_initiative` | read | Initiative + crew and work-item rows + burn-down; long text is excerpted unless `shape: "full"` |
+| `anyforge_get_initiative_spec` | read | Read the active ICE spec, its readiness, what backlog approval will decide (`approvalGate`), and any submission awaiting human review |
+| `anyforge_propose_initiative_spec` | write | Submit an ICE spec for human review; it becomes active only when a person reviews and publishes it in the Console |
+| `anyforge_update_initiative` | write | Update a (non-system) initiative — only the fields you pass change |
+| `anyforge_delete_initiative` | write | Delete a DRAFT initiative (archive via update once it's past DRAFT) |
+| `anyforge_list_opportunities` | read | List opportunities in the Discovery (product-planning) layer |
+| `anyforge_create_opportunity` | write | Create an opportunity (bridges raw signals to themed roadmap work) |
+| `anyforge_update_opportunity` | write | Edit an opportunity's RICE inputs, stage, theme assignment, or program link (`programId`; `null` unlinks) |
+| `anyforge_delete_opportunity` | write | Hard-delete an opportunity (prefer archiving via `anyforge_update_opportunity`) |
+| `anyforge_promote_opportunity` | write | Promote a prioritized opportunity into a Program + Initiative |
+| `anyforge_list_signals` | read | List signals in the Discovery (product-planning) layer |
+| `anyforge_create_signal` | write | Capture a signal — a raw data point that may inform product direction |
+| `anyforge_update_signal` | write | Edit a signal's status, linked opportunity, or other fields |
+| `anyforge_delete_signal` | write | Hard-delete a signal (prefer archiving via `anyforge_update_signal`) |
+| `anyforge_list_themes` | read | List themes in the Discovery (product-planning) layer |
+| `anyforge_create_theme` | write | Create a theme — a strategic grouping above individual initiatives |
+| `anyforge_update_theme` | write | Edit a theme's name, status, objective, or other fields |
+| `anyforge_delete_theme` | write | Hard-delete a theme (prefer archiving via `anyforge_update_theme`) |
+| `anyforge_get_strategy` | read | Read the complete strategy tree, attainment, delivery rollups, horizons, orphan work, and delivery conditions |
+| `anyforge_list_pillars` | read | List strategy pillars |
+| `anyforge_create_pillar` | write | Create a strategy pillar |
+| `anyforge_update_pillar` | write | Update a pillar's name, description, lead, or order |
+| `anyforge_delete_pillar` | write | Delete a pillar when it has no objectives |
+| `anyforge_list_objectives` | read | List strategy objectives |
+| `anyforge_create_objective` | write | Create an objective under a pillar |
+| `anyforge_update_objective` | write | Update or move an objective |
+| `anyforge_delete_objective` | write | Delete an objective when it has no key results |
+| `anyforge_list_key_results` | read | List strategy key results |
+| `anyforge_create_key_result` | write | Create a measurable key result |
+| `anyforge_update_key_result` | write | Update a key result or record a reading |
+| `anyforge_delete_key_result` | write | Delete a key result |
+| `anyforge_get_horizons` | read | Read NOW / NEXT / LATER narratives and completion criteria |
+| `anyforge_set_horizon_narrative` | write | Update a horizon narrative |
+| `anyforge_get_cluster_charter` | read | Read one theme's charter and outstanding lines |
 | `anyforge_approve_backlog` | approve | Approve a proposed backlog (HIL #1) |
 | `anyforge_approve_task_proposal` | approve | Approve a mid-flight task proposal |
-| `anyforge_list_work_items` | read | List backlog items + crew state |
+| `anyforge_list_work_items` | read | List backlog items + crew state with status, owner, assignee, program, initiative, priority, type, and search filters. Returns ONE PAGE (50 default, 200 max) — continue with `nextCursor`. Unknown arguments are rejected; the page echoes `appliedFilters` |
 | `anyforge_get_work_item` | read | Get one work item |
-| `anyforge_create_work_item` | write | Create a work item |
-| `anyforge_update_work_item` | write | Edit / advance / dispatch / archive / close |
+| `anyforge_create_work_item` | write | Create a work item with routing, migration, incident, intake, estimate, and evidence fields |
+| `anyforge_update_work_item` | write | Edit, assign, begin, expedite, dispatch, confirm, drop (with optional `droppedReason`), archive, close, or reopen a work item |
+| `anyforge_retry_work_item` | write | Terminate a work item's crew and dispatch a fresh one on the same branch; recovers missing/phantom crew records from work-item + initiative defaults |
+| `anyforge_list_work_item_comments` | read | List the work item's discussion thread, separate from crew transcripts |
+| `anyforge_post_work_item_comment` | write | Add a discussion comment to a work item |
+| `anyforge_split_work_item` | write | Replace one unstarted work item with multiple children |
+| `anyforge_merge_work_items` | write | Replace multiple unstarted work items with one merged item |
+| `anyforge_list_crews` | read | Discover crews by status, active state, and limit |
 | `anyforge_get_crew` | read | Crew state + recent outputs + comments |
-| `anyforge_post_crew_comment` | write | Comment on / @-mention in a crew |
+| `anyforge_post_crew_comment` | write | Comment on / @-mention people on a crew (the crew does not read comments; use `anyforge_amend_crew` to redirect it) |
 | `anyforge_resume_crew` | approve | Resume a PAUSED/HALTED crew |
 | `anyforge_halt_crew` | approve | Halt a crew |
 | `anyforge_amend_crew` | approve | Continue & finish — send a crew at its HIL gate back to the engineer with guidance |
 | `anyforge_create_program` | write | Create a program (cross-initiative grouping) |
-| `anyforge_write_program_brief` | write | Write/update a program's brief (charter) — seeds each initiative's architect context |
 | `anyforge_create_initiative` | write | Create a (DRAFT) initiative, optionally under a program |
 | `anyforge_dispatch_architect` | write | Decompose an initiative into a backlog (→ HIL #1) |
 | `anyforge_list_repo_index` | read | List the org repo index (activity, coverage, analyzed) — discover codebases to scope |
 | `anyforge_get_repo_analysis` | read | One repo's coverage / architecture / gap summary |
-| `anyforge_analyze_repos` | write | Start Phase-1 analysis for one or more repos |
+| `anyforge_check_dispatch_readiness` | read | Check the repository's Phase 1 + Phase 2 analysis gate before dispatch; does not launch a crew |
+| `anyforge_analyze_repos` | write | Start Phase-1 analysis for one or more repos; Phase 2 follows automatically when Phase 1 completes |
 | `anyforge_start_coverage_sweep` | write | Paced Phase 1→2 analysis sweep over a program/repo set |
 | `anyforge_refresh_repo_index` | write | Refresh the repo index + committed-coverage detection now |
+| `anyforge_upload_coverage` | write | Upload test-coverage measurements for one or many repos (e.g. synced from SonarQube) |
+| `anyforge_list_escrow_deposits` | read | List a codebase's (or the company's) escrow deposit ledger |
+| `anyforge_generate_escrow_deposit` | write | Generate a source-escrow deposit bundle for one codebase |
+| `anyforge_list_escrow_scope` | read | List the codebases currently in escrow scope (escrow.enabled) |
+| `anyforge_set_escrow_scope` | write | Bulk-set the "In escrow scope" checkbox across many codebases (repos and/or codebaseIds, up to 1000 per call) |
+| `anyforge_start_escrow_sweep` | write | Seed/inspect a paced fleet-wide escrow deposit sweep |
+| `anyforge_escrow_scoping_report` | read (write if store=true) | Generate the Escode scoping-answers report (markdown); `store=true` persists it to Storage |
+| `anyforge_deliver_escrow_deposit` | write | SFTP a stored deposit bundle to the escrow agent; stamps the ledger with a delivery receipt |
+| `anyforge_ask_oracle` | read | Ask the AnyForge Oracle a workspace question (codebases, releases, decisions, live data from connected integrations); runs the full research loop server-side and returns one cited answer — can take minutes |
+| `anyforge_investigate_repository` | read | Delegate a bounded repository investigation across one to five selected repos; returns an evidence-backed report from indexed code intelligence and analysis docs without exposing raw graph records or live source |
+| `anyforge_list_workflows` | read | List the company's Operator Workflows — reusable multi-step orchestrations (agent / tool / parallel / map / gate steps) with each one's inputs and enabled flag |
+| `anyforge_get_workflow` | read | Get one workflow including its full current spec (steps, inputs, budget) — inspect required inputs before a run |
+| `anyforge_run_workflow` | write | Dispatch a run of a workflow (returns the QUEUED run); runs pause at gate steps for an operator decision |
+| `anyforge_get_workflow_run` | read | Get a workflow run's status and per-step progress; gate decisions are made on the Console run page |
+| `anyforge_resolve_workflow_gate` | approve | Resolve a run paused at a gate (`approve` / `amend` / `reject`; `amend` carries guidance in `comment`) |
+| `anyforge_list_observability_signals` | read | List production-error triage signals (filter by `status`) |
+| `anyforge_accept_observability_signal` | write | Accept a signal into a governed incident under the KTLO program |
+| `anyforge_dismiss_observability_signal` | write | Dismiss a production-error signal as noise |
+| `anyforge_triage_ticket` | read | Run or continue a Support Triage interview — classification, readiness scoring, owning-team routing — and get a paste-ready rendering plus the structured draft; pass the same `sessionId` to continue an interview. Never files anything itself |
+| `anyforge_list_triage_eval_cases` | read | List the company's triage eval cases |
+| `anyforge_upsert_triage_eval_cases` | write | Create or update triage eval cases in bulk; pass an existing case's `id` to update it in place |
+| `anyforge_delete_triage_eval_case` | write | Delete one triage eval case by id |
+| `anyforge_update_triage_eval_case` | write | Edit one triage eval case in place (bulk-edit via `anyforge_upsert_triage_eval_cases`) |
+| `anyforge_run_triage_eval` | write | Run the eval corpus through the real Support Triage Agent; 10 cases or fewer run synchronously, a larger corpus returns a QUEUED run |
+| `anyforge_get_triage_eval_run` | read | Poll a queued triage eval run by id and read its completed result |
+
+`anyforge_update_work_item` advertises the complete action enum: `advance`,
+`approve_refinement`, `dispatch`, `complete`, `update`, `reorder`, `archive`,
+`unarchive`, `close-as-fixed`, `reopen`, `mark-incident`, `drop`,
+`confirm-repo`, `assign`, `begin`, `dismiss-automation-suggestion`,
+`expedite`, `link-external`, and `verification`. Use `drop` for an obsolete
+unfinished item and pass `droppedReason` when the reconciliation needs an audit
+explanation. `archive` requires `DONE` or `DROPPED`; if it returns
+`archive_requires_terminal`, drop the item first. `close-as-fixed` instead
+records an external fix and requires `closedReason`; `closedEvidenceUrls`
+optionally adds up to 10 http(s) evidence links. `link-external` records the
+item's key in another tracker (`externalKey`, optional `externalUrl`; `null`
+unlinks). `verification` with `verificationState: "verified"` records the
+client's acceptance of a `DONE` item and needs a key bound to a user; a key
+with no user gets `user_bound_credential_required`.
+
+The structured Program Genesis writes are program-scoped. Brief saves are full
+versioned replacements through `anyforge_save_program_brief_version`. Initiative
+closures and batch close-as-fixed operations use `preview` followed by
+`execute` with the short-lived `proposalToken` returned by the preview. A
+successful initiative enrichment returns `changedFields`; a valid request that
+does not change stored data returns `changed: false` and
+`reason: "no_changes_requested"`.
+
+With the default analysis gate enabled, Crew dispatches require a connected
+Codebase with both Phase 1 and Phase 2 analysis complete. Use
+`anyforge_analyze_repos` to start Phase 1, then wait for the automatically
+chained Phase 2 before dispatching a work item. The dispatch response identifies
+the missing stage when a repository is not ready.
+
+### Tool metadata: annotations + structured output
+
+Every tool advertises 2025-06-18 MCP metadata so clients can present it well:
+
+- **Title + behaviour annotations** — a human-readable `title` plus hints
+  (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) derived
+  from the tool's verb, matching the read/write/approve column above. Clients use
+  these to, e.g., auto-run read-only tools and confirm before a `delete_*`. They
+  are advisory only: the control API still re-checks the key's scopes on every
+  call, so annotations never widen access.
+- **Structured output** — every tool declares an `outputSchema` (a JSON object)
+  and returns the result as `structuredContent` alongside the human-readable
+  text block, so structured-output-aware clients get machine-parseable data.
+  Arrays come back as `{ items: [...] }` and prose as `{ text: "…" }`.
+
+Both are filled in centrally (`lib/toolMeta`, `lib/toolResult`) so the stdio and
+hosted-HTTP transports advertise and return exactly the same thing.
 
 ## Prompts (guided flows)
 
@@ -92,17 +228,33 @@ MCP clients that support server prompts (e.g. Claude Code surfaces them as
 | Prompt | Args | What it does |
 |--------|------|--------------|
 | `genesis` | `programId?`, `goal?` | Turns the client into the **Program Genesis agent**: it interviews you to scope a program across your codebases (using `anyforge_list_repo_index` / `anyforge_get_repo_analysis`), writes the program brief, then creates one initiative per in-scope codebase and offers to dispatch the architect on each. |
+| `platform_guide` | `topic?` | Loads the static AnyForge platform model, surface map, tool-selection rules, and safety boundaries. Use live tools for current tenant state. |
 
 The Genesis flow runs entirely in *your* agent — there's no server-side
 chat-in-a-tool. The prompt gives your client the persona + interview script;
 it drives the conversation and calls the tools above as it goes.
 
+## Resources
+
+Clients that support MCP resources can list and read:
+
+| URI | Content |
+|-----|---------|
+| `anyforge://guide/platform` | The portable `anyforge-platform` Agent Skill |
+| `anyforge://guide/platform/references/entity-model.md` | Entity relationships and delivery lifecycle |
+| `anyforge://guide/platform/references/tool-map.md` | Representative tool categories and selection rules |
+| `anyforge://guide/platform/references/operating-boundaries.md` | Identity, evidence, trust, and secret-handling boundaries |
+
+The server's bootstrap instructions point clients at the prompt and resource
+when platform context is needed. They are orientation only; permissions and
+current state still come from the authenticated server and live tool results.
+
 ## Example prompts
 
 - "What's waiting for my approval in AnyForge?" → `anyforge_list_pending_approvals`
 - "Show me the plan for approval `abc123` then approve it." → `anyforge_get_approval_detail` → `anyforge_submit_approval`
 - "Add a P1 bug: rate-limit the export endpoint." → `anyforge_create_work_item`
-- "What did crew `xyz` produce? Post a comment asking it to add tests." → `anyforge_get_crew` → `anyforge_post_crew_comment`
+- "What did crew `xyz` produce? Tag Sam on it to review the tests." → `anyforge_get_crew` → `anyforge_post_crew_comment`
 - "Scope a coverage program across our Go services." → run the `genesis` prompt → it lists repos, scopes, and creates an initiative per service.
 
 ## How it works
@@ -114,16 +266,37 @@ Claude CLI ──stdio──▶ MCP server ──HTTPS (Bearer sk_anyforge_…)
 The `/api/v1/control/*` routes share the exact same service layer as the
 AnyForge web app, so the CLI and the dashboard behave identically.
 
+### Console links in findings
+
+The server advertises MCP `instructions` (see `lib/consoleLinks.ts`, mirrored by
+the hosted `/api/mcp` transport) telling every client to present entity ids as
+clickable links to their Console views by default — crew → `/studio?crew={crewId}`,
+work item → `/work?item={workItemId}`, initiative → `/initiatives/{initiativeId}`,
+and so on — never as bare ids. Crew payloads additionally carry an absolute `url`
+field built server-side from the deployment's public origin. The path table is a
+hand copy of the app's single source of truth
+(`app/lib/navigation/entityRoutes.ts`), kept in lock-step by a drift test
+(`__tests__/lib/navigation/entityRoutes.test.ts`) — change them together. The
+Console enforces the viewer's permissions when a link is opened, so linking never
+widens access.
+
 ## Build & publish (maintainers)
 
-The package ships **compiled JS** (`dist/`), so end users can run
-`npx -y @anyforge/mcp-server` without a TypeScript toolchain. Source lives
-in `index.ts` / `lib/` / `tools/`; `tsc` emits `dist/` (shebang preserved,
-`.js` import specifiers already in source for NodeNext).
+The package ships a single **bundled, minified JS** file (`dist/index.js`),
+so end users can run `npx -y @anyforge/mcp-server` without a TypeScript
+toolchain. Source lives in `index.ts` / `lib/` / `tools/`; **esbuild**
+bundles it into one ESM file with the shebang preserved and `node_modules`
+deps left external (`--packages=external`). The bundle is minified — not as
+a security control (a downloaded npm package is always readable), but to keep
+the tarball small; the real trust boundary is the key-authenticated control
+API, and this process holds no secrets. Type-checking is a separate `tsc
+--noEmit` step. `dist/` is git-ignored and rebuilt at publish by
+`prepublishOnly`.
 
 ```bash
-npm install          # includes the typescript devDependency
-npm run build        # tsc → dist/
+npm install          # esbuild + typescript devDependencies
+npm run type-check   # tsc --noEmit (types only, no output)
+npm run build        # esbuild → dist/index.js (bundled + minified)
 npm pack --dry-run   # verify the tarball: dist/ + README + package.json only
 ```