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).