Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Record the MCP server delivery decisions

Damian Legawiec3e19766735c2
diff --git a/docs/plans/6.0-mcp-server.md b/docs/plans/6.0-mcp-server.md
index 0483c37a3d..0fdae70ee3 100644
--- a/docs/plans/6.0-mcp-server.md
+++ b/docs/plans/6.0-mcp-server.md
@@ -1,6 +1,6 @@
# Admin MCP Server
-**Status:** Draft — design finalized 2026-09-16, nothing built
+**Status:** In Progress — Migration Path steps 1–5 (core registry, reporting tools, workflow tools and generic record writes, the `spree_mcp` gem, docs) are being built on `feat/spree-mcp-server`
**Target:** Spree 6.0
**Depends on:** `6.0-action-actors.md` (shipped 2026-09-16 — the API key is a valid actor, so a workflow run over MCP records who did it), `5.5-admin-api-cli.md` (shipped — the CLI-first precondition this plan waited on), `5.5-admin-api-key-scopes.md` (shipped — secret keys + scopes are the credential), `6.0-admin-rbac.md` (the permission catalog gates every tool), `6.0-analytics-semantic-layer.md` (the reporting registry feeds the reporting tools), `6.0-service-workflows.md` (writes execute through workflows), `6.0-dashboard-assistant.md` (moves onto the registry defined here)
**Author:** Damian Legawiec (design driven with Claude)
@@ -134,6 +134,23 @@ because every back-office write already is a workflow.
names the workflow tool instead, so there is exactly one way to write each
thing. No task tools at 6.0; a composed tool is added only when usage shows
a job spanning several workflows that the model fails to sequence.
+- **Steps 1–5 ship as one pull request (2026-09-16).** The "Order of
+ operations" below proposed a registry-only PR first, with `spree_mcp`
+ branching from `main` after it merged. Shipping the whole plan in one branch
+ instead: the registry has no caller until the MCP adapter exists, so a
+ registry-only PR asks reviewers to judge a contract against no consumer, and
+ the second PR would re-open every shape question with the first already
+ merged. Accepted cost: a large diff across `spree_core`, `spree_api` and a
+ new gem. Mitigated by committing in the plan's phase order, so the history
+ reads as the staged migration the plan describes.
+- **The registry is copied out of `feat/dash-assistant`; that branch is not
+ touched (2026-09-16).** Files come across with `git checkout
+ feat/dash-assistant -- <path>` so blame follows the code, then the three
+ changes (rename, principal on the context, derived resource map) are applied
+ here. Deleting the originals and repointing the RubyLLM adapter stays step 3
+ of the order of operations, for whoever owns that branch — it is a live
+ worktree this run does not own.
+
- **No `spree mcp` command in `@spree/cli` at 6.0 (2026-09-15).** The mounted
Streamable HTTP endpoint serves every current client directly with a key in
the client config; a stdio proxy or a config printer is a second thing to
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index ee1141018d..79e769fa1e 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -6131,6 +6131,27 @@ documented exactly two callers — that list grows as flows are added, but the
rule it protects stands: never wire it to a settings screen, since re-running
it against a configured store is a data reset.
+
+## 2026-09-16 — The MCP server ships as one pull request, not a registry PR then an adapter PR
+
+Plan: `6.0-mcp-server.md`. Refines that plan's "Order of operations", which
+proposed extracting the agent-tool registry into `spree_core` on its own
+branch, merging it, and only then branching `spree_mcp` from `main`.
+
+**Decision.** Migration Path steps 1 to 5 — the core registry, the reporting
+tools, the workflow tools with their allowlist and generic record writes, the
+`spree_mcp` gem, and the documentation — ship in one branch. A registry-only
+pull request would ask reviewers to judge a contract with no caller, and the
+follow-up would re-open every shape question with the first already merged.
+The commits follow the plan's phase order so the history still reads as the
+staged migration.
+
+**Consequences for other work.** The `feat/dash-assistant` branch is read but
+never written by this work: its files are copied across with `git checkout` so
+blame follows the code, and deleting the originals and repointing the RubyLLM
+adapter at `Spree.agent_tools` remains that branch's own step. Until it does,
+the registry classes exist in both places, and the constraint against adding
+tools under `Spree::Assistant::Tools` stands.
## 2026-09-29 — Webhook payloads stay on Store serializers; every event is declared
Plan: `6.0-typed-webhook-events.md`.