Files
summercms/.planning/phases/19.7-generic-mcp-module/19.7-DISCUSSION-LOG.md
2026-10-18 12:41:37 +02:00

5.3 KiB

Phase 19.7: Generic MCP module - Discussion Log

Audit trail only. Do not use as input to planning, research, or execution agents. Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

Date: 2026-10-18 Phase: 19.7-generic-mcp-module Areas discussed: Prerequisites & sequencing, Tool declaration & dispatch, Session credentials & filtering, Transport & SDK


Prerequisites & sequencing

Question Options Selected
Where are the two prerequisite todos built? Fold into 19.7 / Separate decimal phase first / Permissions in, link deferred Fold into 19.7
Dependency on 19.4 sm-oauthserver-plugin Requires 19.4 done / Pluggable authenticator Requires 19.4 done
Where does the account link live? (first pass) sm-user-plugin / cabana / inside the MCP module User asked: "sm-user-plugin really recommended, rethink this and give me better rationale against each"
Where does the account link live? (after rationale) sm-user-plugin + cabana seam / cabana generic identities / inside the MCP module sm-user-plugin + cabana seam
How is the link proven? Site sign-in round-trip / Enter frontend credentials in admin / You decide Site sign-in round-trip
When is the link resolved? Per request / Stored in grant Per request
Link cardinality 1 frontend ↔ 1 backend / 1 backend ↔ many frontend 1 ↔ 1
Admin link management Permission-gated, unlink + link / Superuser only, unlink only Permission-gated, unlink + link

Notes: The rationale given for the second pass:

  • Only sm-user-plugin can verify a frontend sign-in, and the framework cannot import it.
  • My Profile and backend Users are both cabana screens, so a generic cabana seam is needed whichever side owns the link.
  • A cabana-owned table would need an identity-prover registry, and it would leave orphan rows on frontend-user deletion.
  • An MCP-owned link has every downside of the cabana option and none of its upsides.

Tool declaration & dispatch

Question Options Selected
Binding Route by method+path / Own handler func / Both Route by method+path
Argument mapping Struct tags / Separate structs Struct tags
Naming Auto-prefix plugin code / Plugin picks full name / App-configurable prefix Auto-prefix plugin code
Result Route JSON passthrough / Typed output required Route JSON passthrough
Annotations Derived, overridable / Explicit only Derived, overridable
Targets Token-guarded only / Any route Token-guarded only
First tools Journal + user plugin tools / Framework + example only Journal + user plugin tools
Handler-auth routes (Journal) Declared on tool, middleware merged / Move Journal to middleware Declared on tool, middleware merged
Identity into handler Pre-resolved principal in context / Mint short-lived JWT Pre-resolved principal in context

Notes: Two follow-up questions came from a scouting finding. Journal's management routes carry only throttle:journal-api and authenticate inside the handler (requireBackendPrincipal).


Session credentials & filtering

Question Options Selected
Personal tokens for MCP sessions Yes, single identity / Yes, behind a config flag / OAuth only Yes, behind a config flag
OAuth read/write read = read-only tools / Scopes ignored read = read-only tools
Backend reach Separate backend scope + consent line / Automatic with link Separate backend scope + consent line
Admin permissions via MCP Full admin perms, read/write capped / Exclude superuser Full admin perms, read/write capped
Which identity runs a call The tool's declared guard / Prefer backend The tool's declared guard
list_changed (asked assuming stateless) No, recompute per request / Yes, via event bus No (later revised, see Transport)

Transport & SDK

Question Options Selected
SDK Official modelcontextprotocol/go-sdk / mark3labs/mcp-go / Hand-written JSON-RPC Official go-sdk
Session model Stateless / Stateful with Redis Stateful with Redis
Features (first pass) Tools only / Tools + prompts / Tools + resources "Tools + prompts + resources ?"
Features (after explanation) Design for all, ship tools + prompts / All three / Tools only, design for all Design for all, ship tools + prompts
list_changed with sessions Yes, via event bus + Redis / No, re-check only Yes, via event bus + Redis
Session lifetime Sliding idle TTL, ends on revoke / You decide Sliding idle TTL, ends on revoke
Module name conch / pier / buoy pier

Notes: Choosing stateful sessions reopened the earlier list_changed answer, which was revised to push notifications. Authorization stays per request, and sessions are bound to their principal(s).


Claude's Discretion

  • Go identifiers, the table and permission names, and the config key spellings.
  • The link-request token format and TTL, and the link-lookup cache bound.
  • Which Journal and user tools ship beyond the minimum.
  • The shape of the cabana seam.

Deferred Ideas

  • MCP resources and subscriptions (follow-up phase).
  • Tools generated from fields.yaml (ruled out).