Core — Rosetta MCP tool vocabulary¶
Runtime-agnostic catalog of the rosetta_* MCP tools the plugin exposes via the
bundled rosetta-mcp-server binary. As of server v0.8.7
the surface is 43 tools — 5 composites + 38 read/write 1:1 wrappers —
behind a server-side deny-by-default tool-policy (§7). Both adapter runtimes
(Claude Code, Cowork) bind to this vocabulary; the adapter MUST NOT rename tools,
collapse the composite/1:1 distinction, invent parallel names, or call a tool the
server tool-policy denies.
The binary registers the 1:1 wrappers mechanically from the vendored
api/rosetta-v1.yaml (rosetta_<operationId-snake-cased>); the composites come
from config/mcp/composites.yaml. The plugin manifest does not declare the
tools — the binary does, at startup.
This catalog covers READ and WRITE. The cross-cutting write discipline
(confirm-before-destructive, idempotency, enum validation, partition/access) is
core/write-safety.md; per-family detail is in core/engagement-twin.md,
core/governance-lifecycle.md, core/engagement-lifecycle.md,
core/engagement-canvas.md. Reach for those before driving a write.
1. Five composites (task-shaped) — the default reach¶
Composites bundle a common multi-call flow into one MCP tools/call. Source of
truth: config/mcp/composites.yaml.
| Composite | Purpose | Fans out to |
|---|---|---|
rosetta_turn |
One conversation turn end-to-end (project-scoped). | rosetta_create_conversation (idempotent) → rosetta_persist_conversation_turn → rosetta_decide_flow_next_action. Returns the flow decision. |
rosetta_engagement_turn |
One engagement-scoped turn; binds the session to an engagement and writes turn semantics into the twin. | same three, with engagementId (slug) on create + an optional semanticProjection (decisions / gaps / citations) on persist. Returns the flow decision. See core/conversation-lifecycle.md. |
rosetta_record |
Governance batch write. Always a DecisionTrace; conditionally an ADRApplication + a QueryTrace. Partial-success contract. | rosetta_create_decision_trace → (rosetta_record_adr_application if present) → (rosetta_create_query_trace if present). |
rosetta_query |
Context retrieval with expand=full (inlines governingADRs[], semanticEntities[], vocabularyTerms[]; removes N+1 hydration). |
rosetta_create_context_retrieval with expand=full forced. |
rosetta_engagement_canvas_slack |
An engagement's canvas as publish-ready Slack-canvas markdown, one call. | rosetta_get_engagement_canvas with format=slack; returns { status, text }. Hand text to the Slack MCP. See core/engagement-canvas.md. |
Reach for a composite first; fall back to the 1:1 wrappers (§2/§3) for fine-grained control or an endpoint no composite covers.
2. Read wrappers (fine-grained)¶
Grouped by family. All are non-mutating.
Context / patterns / ADRs / spec-manifest
| Tool | REST |
| --- | --- |
| rosetta_create_context_retrieval | POST /api/v1/context (sparse; expand=full opt) |
| rosetta_get_pattern | GET /api/v1/patterns/[id] |
| rosetta_get_a_d_r | GET /api/v1/adrs/[id] |
| rosetta_get_spec_manifest | GET /api/v1/spec-manifests/[id] |
Conversation / identity
| Tool | REST |
| --- | --- |
| rosetta_get_conversation_context | GET /api/v1/conversations/[id] |
| rosetta_get_authenticated_user | GET /api/v1/users/me |
Engagement (twin / memory / lifecycle / canvas)
| Tool | REST | Notes |
| --- | --- | --- |
| rosetta_list_engagements | GET /api/v1/engagements | discover engagementIds (slugs) |
| rosetta_get_engagement | GET /api/v1/engagements/[uid] | |
| rosetta_get_engagement_twin | GET /api/v1/engagements/[uid]/twin | full TwinDocument; since=[int revision] for delta; no include= (filter client-side) |
| rosetta_recall_engagement_memory | GET /api/v1/engagements/[uid]/memory | hybrid graph+vector; q, kinds=decision\|artifact\|gap\|session, limit, cursor |
| rosetta_get_engagement_canvas | GET /api/v1/engagements/[uid]/canvas | format=json (default) or slack; include= section subset |
| rosetta_get_digital_twin_node | GET /api/v1/digital-twins/[uid] | one CA / DecisionTrace / gap node |
Governance
| Tool | REST |
| --- | --- |
| rosetta_get_promotion_candidate | GET /api/v1/promotion-candidates/[id] |
| rosetta_list_promotion_candidates | GET /api/v1/promotion-candidates (filters: status, decisionPoint) |
| rosetta_get_governance_review | GET /api/v1/governance-reviews/[id] |
3. Write wrappers (fine-grained) — see core/write-safety.md first¶
Conversation / governance-batch members
| Tool | REST | Idempotency |
| --- | --- | --- |
| rosetta_create_conversation | POST /api/v1/conversations | 201 create / 200 exists on (sessionId, projectId, userId) |
| rosetta_persist_conversation_turn | POST /api/v1/conversations/[id]/turns | new turn each call; turnNumber skip = race |
| rosetta_decide_flow_next_action | POST /api/v1/flow/decide | read-shaped (no persist) |
| rosetta_create_decision_trace | POST /api/v1/decision-traces | 201/200 on (sessionUid, decisionPoint) |
| rosetta_record_adr_application | POST /api/v1/adr-applications | on (adrUid, engagementUid, surfacedBy) |
| rosetta_create_query_trace | POST /api/v1/query-traces | per RESOLVED_VIA target |
| rosetta_upsert_practitioner | POST /api/v1/practitioners | upsert on email (200 always) |
Engagement twin (core/engagement-twin.md)
| Tool | REST | Notes |
| --- | --- | --- |
| rosetta_apply_engagement_twin | POST /api/v1/engagements/[uid]/twin/apply | forensic lane: atomic edits[] for confirmed graph-canonical state; send Idempotency-Key; 200/409 |
| rosetta_apply_engagement_twin_rehearsal | POST /api/v1/engagements/[uid]/twin:apply-rehearsal | rehearsal lane: the honesty-routing target for [SIMULATED] / status:PROPOSED / simulationRunId content (core/write-safety.md §1.5). Admits traceKind:"runtime" and stamps the revision ProvenanceEvent provenance:"simulated". Available since mcp v0.8.7 (generated from the applyEngagementTwinRehearsal operation, tag engagement-twin). |
| rosetta_create_digital_twin_node | POST /api/v1/digital-twins | exactly one of engagementId/projectId; overrideMode enum |
| rosetta_update_digital_twin_node | PATCH /api/v1/digital-twins/[uid] | properties patch |
Engagement lifecycle (core/engagement-lifecycle.md)
| Tool | REST | Notes |
| --- | --- | --- |
| rosetta_create_engagement | POST /api/v1/engagements | clientUid REQUIRED (api 1.5.0; :Client.uid slug, lazily MERGEd; absent/empty/malformed → 422) + name; optional engagementUid slug ≤64; dual-write; 201/409/422 |
| rosetta_update_engagement | PATCH /api/v1/engagements/[uid] | name / status / clientUid (non-empty = edge move; "" = unlink, confirm-before; omitted = unchanged) |
| rosetta_create_project | POST /api/v1/projects | new project namespace |
| rosetta_compile_spec_manifest | POST /api/v1/spec-manifests/compile | exactly one of projectId / engagementId |
Governance three-gate (core/governance-lifecycle.md)
| Tool | REST | Gate |
| --- | --- | --- |
| rosetta_run_gate1 | POST /api/v1/gates/1/evaluate | Gate 1 |
| rosetta_evaluate_decision_trace | POST /api/v1/decision-traces/[id]/evaluate | Gate 2 |
| rosetta_create_promotion_candidate | POST /api/v1/promotion-candidates | Gate 2 |
| rosetta_create_governance_review | POST /api/v1/governance-reviews | Gate 3 |
| rosetta_approve_governance_review | POST /api/v1/governance-reviews/[id]/approve | Gate 3 |
| rosetta_reject_governance_review | POST /api/v1/governance-reviews/[id]/reject | Gate 3 (destructive) |
| rosetta_request_governance_review_revision | POST /api/v1/governance-reviews/[id]/request-revision | Gate 3 |
| rosetta_rollback_a_d_r | POST /api/v1/adrs/[id]/rollback | ADR (destructive) |
4. When to use which tier¶
- Composite first for the high-frequency flows (turn, engagement-turn, governance batch, full-context retrieval, canvas→Slack).
- 1:1 read wrapper when you hold a uid and want the canonical record, or when the sparse context default suffices.
- 1:1 write wrapper when a composite does too much, when writes are spread
across turns, or when you need fine-grained error handling — always under
core/write-safety.md.
The composite-vs-1:1 choice is intent-driven, not capability-driven.
5. Idempotency contract¶
| Tool(s) | Key / behavior |
|---|---|
rosetta_turn / rosetta_engagement_turn |
(sessionId, projectId, userId, turnNumber); create step idempotent, turnNumber increments server-side |
rosetta_create_conversation |
(sessionId, projectId, userId) → 201 create / 200 exists (NOT an error) |
rosetta_create_decision_trace / rosetta_record |
(sessionUid, decisionPoint) |
rosetta_record_adr_application |
(adrUid, engagementUid, surfacedBy) |
rosetta_upsert_practitioner |
email (always 200) |
rosetta_apply_engagement_twin |
client-supplied Idempotency-Key (uuid); 200 success / 409 conflict |
| reads | idempotent by definition |
Status codes: 200 where you expected 201 = idempotent hit (normal; do not
alarm). 409 = conflict → reload state, do not blind-retry. 422 =
referential failure (e.g. invalid userId FK on conversation create, since
v0.8.3) → surface and fix the reference. 401/403 = auth/partition (see §7,
core/write-safety.md). Retry is safe on the idempotent writes above; it is NOT
safe on a 409.
6. Enum catalog (writes are validated server-side; off-enum = 400)¶
| Field | Allowed values |
|---|---|
decisionType |
architecture, configuration, trade-off, scope |
outcome |
accepted, rejected, modified, deferred |
retrievalStrategy |
graphrag, keyword, hybrid, direct_lookup |
surfacedBy |
agent_recommendation, manual_attachment, architecture_review |
phase (flow state) |
discovery, clarification, pattern-matching, recommendation, validation |
solutionMode / icp |
customer-360, agentforce-first, marketing-cdp, data-governance, analytics-first, integration-first, unknown |
overrideMode |
base, supplement, refine, replace, suppress (corrected v0.8.2 — the old extend/inherit values are gone) |
Pre-validate against this table before any write; the server rejects off-enum values with 400.
7. Server tool-policy (the boundary)¶
The server exposes tools by allowlist (deny-by-default) —
config/mcp/tool-policy.yaml. Allowed tags: context, patterns, adrs,
digital-twin, spec-manifests, projects, conversations, flow,
governance, practitioners, identity, engagement-twin,
engagement-memory, engagements, engagement-canvas. Denied (NOT exposed,
not callable, must never be hand-rolled): accounts, account-members,
platform-admin, engagement-access (ACL grant/revoke), export
(bulk Cypher/Markdown exfiltration), presence (web-only SSE/heartbeat), and
forkProject. If a flow seems to need a denied capability, that is an operator /
out-of-band action, not a plugin call.
8. Wire-contract notes¶
engagementIdis a slug, not a UUID:^[A-Za-z0-9_.:\-]+$, ≤64 (e.g.nto-02,eng-nto-01). Applies to context, conversation create,rosetta_engagement_turn, twin/canvas/memory/lifecycle calls.sessionId/projectId/userIdremain UUIDs.rosetta_get_engagement_twintakes NOinclude=; read the full TwinDocument and filter node types client-side. Usesince=[int revision]for a delta read.rosetta_compile_spec_manifesttakes exactly one ofprojectId(uuid) orengagementId(slug) — engagement-scoped compile since v0.8.1.- 422 documents referential-integrity failures on conversation create
(MySQL
user_idFK; theproject_idFK was dropped in platform migration 033).
9. Schema introspection¶
Per-tool schemas live in api/rosetta-v1.yaml#/components/schemas/; the
tools/list response carries a description per tool. Read the OpenAPI spec
directly — do NOT introspect by calling a tool with an empty payload (the error
is not a schema).
10. What NOT to do¶
- Do not invent tool names or call a tool the §7 tool-policy denies.
- Do not call
/api/v1/*directly, bypassing MCP — the bearer lives in the binary (RCP-C-6); bypassing it leaks the token. - Do not call a composite for one of its writes — use the 1:1 wrapper.
- Do not blind-retry a 409; do not treat a 200-where-you-expected-201 as an error.
- Do not perform a destructive write without operator confirmation
(
core/write-safety.md). - Do not retry 401 with a different token (config error;
core/mcp-token.md).
Consumed by¶
skills/agent-orchestration/SKILL.mdskills/context-retrieval-flows/SKILL.mdskills/conversation-lifecycle/SKILL.mdskills/decision-trace-capture/SKILL.mdskills/engagement-twin/SKILL.mdskills/governance-lifecycle/SKILL.mdskills/engagement-lifecycle/SKILL.mdskills/engagement-canvas/SKILL.md