06 — MCP Tooling
06 — MCP Tooling
Section titled “06 — MCP Tooling”Last verified: 15/05/2026 (S240 — Theme F RATIFIED)
Scope: KH MCP server surface, mempalace integration pattern (direct — ratified S240), wing wire-up convention, tool/resource/prompt inventory, MCP-action review pass, and the migration path to wrapped (DEFERRED-POST-LAUNCH).
Status: [CURRENT-CANONICAL] — sixth of the 9-way split superseding docs/plans/phase-0-investigation/0.9-intended-architecture.md. Theme F RATIFIED S240, unblocking this sub-doc.
Layer: 2 — references 01-vision.md for product framing; references 03-tech-stack.md §10 (mempalace stack entry); forward-refs 02-data-flow.md §4 (op_id propagation) and 04-workspace-types.md (workspace schema).
Companion sub-docs: 01-vision.md, 02-data-flow.md, 03-tech-stack.md, 04-workspace-types.md, 05-qa-flow.md, 07-collapse-list.md, 08-new-features.md, 09-diagrams.md.
1. Purpose + scope
Section titled “1. Purpose + scope”This sub-doc is the canonical record of the KH MCP server surface — its transport architecture, tool/resource/prompt inventory, mempalace integration pattern, and the wing wire-up convention that scopes memory operations to KH workspaces. It also carries the MCP-action review pass: a category-level verdict on which tool groups are retained as-is, which require refinement, which are candidates for removal, and which warrant extension.
The sub-doc resolves the one remaining STILL-OPEN gate blocking the 9-way architecture split: Theme F (mempalace direct vs wrapped in KH MCP), RATIFIED S240 per Liam pre-decision recorded in docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md §8 + commit 6930b4f5.
Cross-references:
03-tech-stack.md§10 — mempalace listed as a stack component (dev-session memory substrate, not v1 ingest pipeline substrate); this sub-doc resolves the integration-pattern cross-ref noted there.02-data-flow.md§4 — op_id propagation convention; mempalace operations are outside the KH audit_log surface under the direct pattern (documented in §4.3 below as an accepted limitation for v1).04-workspace-types.md—workspace_idis the unit of tenant scope; thewing ↔ workspace_idmapping (Q4.5, Shape C, RATIFIED S229) is the load-bearing wire-up convention in §5.
2. KH MCP server architecture
Section titled “2. KH MCP server architecture”2.1 Transport + entry point
Section titled “2.1 Transport + entry point”The KH MCP server runs as a Next.js API route at app/api/mcp/[transport]/route.ts, deployed on Vercel. Transport: MCP SDK’s WebStandardStreamableHTTPServerTransport directly — a fresh server + transport is created per request. createMcpHandler is NOT used on this route (Vercel breaks it — see §8.1 anti-pattern entry); mcp-handler is reserved for the .well-known endpoint only.
2.2 Tool registration structure
Section titled “2.2 Tool registration structure”58 tools are registered across 16 category files in lib/mcp/tools/. The barrel (tools/index.ts) calls registerXxxTools(server) in discovery order; registration order determines Claude client tool-discovery order. All tools use defineTool (or defineAppTool for MCP App trigger tools) from tools/shared.ts, which enforces all four ToolAnnotations fields at compile time via one of four named annotation constants.
Every tool:
- Creates a per-user Supabase client via
createMcpClient(extra.authInfo)so Supabase RLS applies per authenticated user. - Returns dual content: Markdown text (
content[0].type='text') for human display + structured JSON (structuredContent) for machine consumption viatoStructuredContent(). - Write tools additionally call
checkMcpRole(extra.authInfo, ['admin', 'editor'])before any mutation.
Tool names are intentionally prefix-free (search_knowledge_base not kb_search_knowledge_base) — KH MCP is designed as a single-purpose connector per lib/mcp/tools/index.ts line 26-28. The direct mempalace pattern (§4) introduces a second server with a different namespace; the prefix-free convention reflects KH MCP’s own tool surface.
2.3 Plugin bundle
Section titled “2.3 Plugin bundle”KH distributes a plugin bundle at lib/mcp/plugin-bundle.ts — auto-generated base64 ZIP, ~9 lines of committed source, regenerated via bun run build:plugin. The bundle is committed so Vercel can serve without filesystem reads. Regenerate and commit after any change to plugin files. (CLAUDE.md “Plugin bundle is committed” gotcha.)
2.4 MCP Apps
Section titled “2.4 MCP Apps”Four MCP Apps ship as Vite single-file builds in mcp-apps/: coverage-matrix, bid-dashboard, reorient-me, intelligence-feed. Build pipeline: bun run build:mcp-apps → scripts/bundle-mcp-apps.ts inlines HTML into app-bundles.ts as committed string constants. Apps are exposed as resources at ui://{name}/app.html (see §3 inventory snapshot). Per-app type contracts between mcp-apps/{name}/src/types.ts and formatters/*.ts are tested by mcp-app-contracts.test.ts.
2.5 MCP evaluation layers
Section titled “2.5 MCP evaluation layers”Three eval layers gate the KH MCP server per CI:
| Layer | Command | Scope |
|---|---|---|
| L1 — Protocol compliance | bun run test:mcp-eval | 42 checks |
| L3 — Response quality | bun run test:mcp-eval:rq | 17 checks |
| L4 — Functional correctness | bun run test:mcp-eval:fc | 37 checks (live DB) |
Canonical tool/prompt lists for evals: scripts/mcp-eval/fixtures.ts — not the inventory doc. (lib/mcp/CLAUDE.md “Eval spec: docs/specs/mcp-evaluation-spec.md — note: tool counts in the spec are stale; fixtures.ts is the canonical source.”)
3. Tool / resource / prompt inventory snapshot
Section titled “3. Tool / resource / prompt inventory snapshot”The auto-generated inventory at docs/generated/mcp-inventory.md is the live reference; this section provides a stable snapshot at S240 by category. Do not enumerate individual tools here — consult the generated doc. The snapshot is current as of 2026-05-11T09:54:30 UTC.
Summary: 58 tools (42 read-only, 16 write, 2 destructive), 12 resources (3 templates, 4 app resources, 5 static), 7 prompts.
Tool categories (16 files):
| Category | File | Count | Primary purpose |
|---|---|---|---|
| Search / browse | search.ts | 5 | Semantic + keyword search, similarity, dedup candidates, chunk search |
| Content item operations | content.ts | 9 | Get, create, update, batch-get, workspace items, owner assign, document versions/diff |
| Bid / procurement ops | bids.ts | 5 | List bids, bid detail, question detail, cite content, content effectiveness |
| Dashboard | dashboard.ts | 4 | Dashboard summary, reorientation briefing, freshness report, expiring content |
| Quality | quality.ts | 7 | Quality summary, coverage gaps, audit, dedup, suggest creation, briefing, actions |
| Governance / admin | governance.ts | 5 | Delete/archive, governance status, publication status, queue, review action |
| Review | review.ts | 3 | Review queue, assignments, create assignment |
| AI operations | ai.ts | 2 | Classify content, generate summary |
| Entities | entities.ts | 2 | Entity relationships, certification status |
| Templates | templates.ts | 3 | List, coverage, gaps |
| MCP Apps (trigger) | apps.ts | 4 | Show coverage matrix, bid dashboard, reorient me, intelligence feed |
| Intelligence | intelligence.ts | 2 | Summary, trigger poll |
| Guides | guides.ts | 4 | List, get, create, update |
| Change report | change-report.ts | 1 | Get change report by period |
| Supersession | supersession.ts | 1 | Mark content item superseded |
| Workspaces | workspaces.ts | 1 | List user workspaces |
Resources: 3 template resources (kb://items/{id}, kb://bids/{id}, kb://qa/{id}), 5 static resources (coverage, dashboard, taxonomy, entities, quality-briefing), 4 app resources (ui://{name}/app.html).
Prompts: 7 — reorient, bid_briefing, coverage_analysis, draft_response, review_item, sector_briefing, bid_pipeline_review.
Note: inventory is a snapshot at S240; the live auto-generated source is authoritative. Regenerate with bun run generate:mcp-inventory when tool registrations change.
4. Mempalace integration — direct pattern (RATIFIED-S240)
Section titled “4. Mempalace integration — direct pattern (RATIFIED-S240)”4.1 Ratification
Section titled “4.1 Ratification”Pattern: Direct. Mempalace runs as a separate Anthropic plugin (mempalace@mempalace v3.3.5) enabled in ~/.claude/settings.json enabledPlugins. Claude calls mempalace tools directly — mempalace_search, mempalace_diary_read, mempalace_diary_write, mempalace_status, etc. — without any KH MCP adapter code. KH MCP has zero coupling to mempalace.
Ratified S240 per Liam pre-decision: commit 6930b4f5 (“Liam S240 ratification — direct pattern (mempalace as separate Anthropic plugin alongside KH MCP) for v1”). Full rationale, tradeoff analysis, and comparison matrix: docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md §4-§7.
4.2 Why direct is the correct v1 pattern
Section titled “4.2 Why direct is the correct v1 pattern”The load-bearing factor is architectural feasibility. KH MCP server-side code runs on Vercel serverless functions. Mempalace is an Anthropic plugin that executes within Claude’s local plugin runtime — it is not a standalone HTTP server callable from Vercel. Full server-side wrapping is not possible in the current architecture. The wrapped pattern becomes viable only when mempalace v4 PG-backend reaches production-stable as a deployable standalone MCP HTTP server (Q4.6, DEFERRED-POST-LAUNCH per 0.9-decision-graph.md §3.C).
Beyond feasibility, direct provides genuine operational strengths for v1:
- Upgrade resilience. Mempalace is under active development (PR #1396, v3.3.5, v4-alpha activity). Direct means KH does not track mempalace’s API surface; any new mempalace tools become immediately available without KH code changes.
- Failure isolation. If mempalace crashes or the known
mempalace_searchwing-filter bug escalates, KH MCP continues serving unaffected. Blast radius is narrow and owned by the plugin, not KH. - Zero adapter maintenance. No adapter code means no adapter test surface, no adapter upgrade cadence, no adapter deploy cycle.
4.3 System-prompt enforcement of wing: <workspace_id>
Section titled “4.3 System-prompt enforcement of wing: <workspace_id>”Direct is not a “do nothing” option. The wire-up checklist requirement (docs/plans/phase-0-investigation/10-feedback-investigation-findings/03-q113-q55-q311-q45-workspace-types.md §6.3; confirmed Q4.5 Shape C, RATIFIED S229) requires that every mempalace MCP call operating on workspace data passes wing: <workspace_id>, where workspace_id is the active workspace context.
Under the direct pattern, this enforcement is via system-prompt instruction, not code. Claude is instructed: every mempalace MCP call that operates on workspace data MUST pass wing: <workspace_id>. Calls without wing in a workspace context are prohibited. This is the strongest enforcement available without server-side wrapping.
Accepted limitation: code cannot verify wing parameter presence at call time. For the current single-tenant Phew deployment, prompt-discipline enforcement is tolerable. For multi-tenant scale, this is a known gap — tracked as a migration trigger for the wrapped pattern (§7).
4.4 Known mempalace tool surface limitations
Section titled “4.4 Known mempalace tool surface limitations”Per CLAUDE.md “Memory (Mempalace)” and docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md §2.1:
mempalace_search— PARTIAL. Default (nowingparam) works as of v3.3.5. Anywingfilter errors withError executing plan: Internal error: Error finding id. Workaround: search withoutwingparam; filter results client-side bywingfield. Alternatively, fall back to git log + grep for wing-scoped recall. Tracked as OQ-Q45-A (non-blocking for KH schema; production-readiness track item).mempalace_diary_write/mempalace_diary_read— work for defaultwing_<agent>; cross-projectwingparameter errors. Use AAAK format (entity codes + emotion markers + pipe-separated fields).mempalace_status,mempalace_list_wings,mempalace_kg_stats,mempalace_kg_query— operational.
These are v3.3.5 caveats. Under the direct pattern, KH MCP is not responsible for hiding or routing around them — Claude handles workarounds as documented above.
4.5 Observability gap (accepted for v1)
Section titled “4.5 Observability gap (accepted for v1)”Under direct, mempalace operations are entirely outside KH’s telemetry surface. Memory writes, reads, and failures do not appear in audit_log or the Sentry/structured-logger surface (logBestEffortWarn). Op_id propagation (N7 RESOLVED-S236, per 02-data-flow.md) does not extend to mempalace calls. This is an accepted v1 limitation — the gap is resolved when the migration to wrapped occurs (§7).
5. Wing wire-up convention
Section titled “5. Wing wire-up convention”5.1 One wing per worktree
Section titled “5.1 One wing per worktree”Mempalace organises memory into wings, one per worktree. As of S43:
| Wing | Drawers |
|---|---|
knowledge-hub | 75,878 |
knowledge-hub-prod-readiness | 22,773 |
knowledge-hub-kpf | 7,342 |
knowledge-hub-ui-ux | 15,299 |
| (minor worktrees) | ~7,000 |
| Total | ~128,000 across 12 wings |
Stop + PreCompact hooks fire automatically each session — no manual ingest needed. (CLAUDE.md “Memory (Mempalace)”.)
5.2 Wing ↔ workspace_id mapping
Section titled “5.2 Wing ↔ workspace_id mapping”Per Q4.5 Shape C (RATIFIED S229, decision-graph §3.B Q4.5): mempalace wing parameter maps 1:1 to KH workspace_id. No schema change needed for this mapping — it is a convention enforced via system-prompt (§4.3). Every workspace-scoped mempalace call passes wing: <workspace_id> from the active workspace context.
This is a KH-specific convention on top of the generic mempalace wing model. Mempalace itself is unaware of KH workspaces; the mapping is pure call-discipline.
5.3 Diary format — AAAK
Section titled “5.3 Diary format — AAAK”Mempalace diary entries use the AAAK format: entity codes + emotion markers + pipe-separated fields. Example: [ENT:content-items|TYPE:schema|STATUS:investigating]. This is the platform-wide diary format per CLAUDE.md “Memory (Mempalace)”. KH-specific extensions to the AAAK format should be agreed at the session level and documented in continuation prompts.
5.4 Auto-memory file system — phased out
Section titled “5.4 Auto-memory file system — phased out”The auto-memory file system (feedback_*.md / project_*.md / reference_*.md in ~/.claude/projects/.../memory/) is phased out as of 2026-05-10. Do NOT author new files in that pattern. New lessons graduate to: (a) one-line CLAUDE.md Gotcha entry, (b) next continuation prompt’s “Critical rules from recent sessions” section (max 5 items), or (c) a substantive memory-shape ratification. (CLAUDE.md “Memory (Mempalace)”.)
6. MCP-action review pass — refine / remove / extend
Section titled “6. MCP-action review pass — refine / remove / extend”This section is a category-level review pass — one verdict per tool group rather than per-tool. Theme F (mempalace integration pattern — §4 above) is RESOLVED-S240 and is a separate concern; the wider per-tool audit of all 58 KH MCP tools is a distinct work package, deferred to a dedicated audit deliverable (see §6.11 below) and not covered exhaustively here.
This section’s category-level review is sufficient for the architecture record. The detailed per-tool audit — and the refresh of docs/client-documentation/Knowledge Hub — Claude Integration Guide.md (last verified 23/04/2026 against 54/12/7 — now stale against the current 58/12/7 inventory) — are queued for a follow-up audit work package.
Verdicts use four tiers: [RETAIN-AS-IS] / [REFINE] / [REMOVE] / [EXTEND].
6.1 Search / browse (5 tools)
Section titled “6.1 Search / browse (5 tools)”Verdict: [RETAIN-AS-IS]
search_knowledge_base, search_qa_library, find_similar_items, find_duplicate_candidates, search_content_chunks are the primary KB retrieval surface. Signatures are stable. The visibility_filter parameter pattern is consistent across the search category. No pre-launch changes needed.
Note: search_qa_library is corpus-level (no workspace partition, per Q-OQR1-06). This is correct — Q&A pairs are corpus-level + scope_tag-driven. The tool signature reflects the ratified shape.
6.2 Content item operations (9 tools)
Section titled “6.2 Content item operations (9 tools)”Verdict: [RETAIN-AS-IS] with one watch item.
Core item operations (get_content_item, create_content_item, update_content_item, get_content_items, get_workspace_items) are stable. Owner-assignment tools (assign_content_owner, bulk_assign_owner) and document version/diff tools (get_document_versions, get_document_diff) are clean.
Watch item: create_content_item accepts source_document_id and source_document fields — the source-binding shape may evolve as the cocoindex ingest path lands (per 02-data-flow.md). No pre-launch change needed; post-launch refinement if the source-document shape from cocoindex diverges from the current manual-ingest contract.
6.3 Bid / procurement operations (5 tools)
Section titled “6.3 Bid / procurement operations (5 tools)”Verdict: [REFINE] — rename pending Q-OQR1-16 combined PR
list_active_bids, get_bid_detail, get_bid_question, cite_content, get_content_effectiveness serve the procurement application. bid naming in tool names (list_active_bids, get_bid_detail, get_bid_question) predates the Q-OQR1-02 procurement umbrella rename. The canonical rename (bid_workspaces → procurement_workspaces, application_type='bid' → application_type='procurement') lands in the Q-OQR1-16 combined PR (RATIFIED-S235, migration STILL-OPEN). Tool renaming is [LOCKSTEP-WITH-MIGRATION] — do NOT rename tools before the combined PR lands. After migration: rename list_active_bids → list_active_procurement, get_bid_detail → get_procurement_detail, get_bid_question → get_procurement_question. The cite_content and get_content_effectiveness tools are application-agnostic; no rename needed.
Category: tech spec needed for the tool-rename sequencing. Checked 00-synthesis-v2.md §3.5 + Q-OQR1-02 ratification + 0.9-decision-graph.md §11.3 combined-PR scope — tool-level rename timing is not explicitly scheduled. Suggested prerequisite: confirm tool renames are in-scope for the combined PR, or open a separate tech spec. Flag to Liam: should list_active_bids etc. rename as part of the Q-OQR1-16 combined PR, or in a separate MCP-tooling PR?
6.4 Dashboard (4 tools)
Section titled “6.4 Dashboard (4 tools)”Verdict: [REFINE] — Q4.10 reorientation transition (PROVISIONAL)
get_dashboard_summary, get_freshness_report, get_expiring_content are [RETAIN-AS-IS].
get_reorientation (tool #7) carries a PROVISIONAL status per 0.9-decision-graph.md §3.B Q4.10: “Replace get_reorientation with mempalace per-user memory.” Under the direct pattern (§4), get_reorientation stays for v1; mempalace per-session memory (mempalace_diary_read, mempalace_search) is additive, not a replacement. The static get_reorientation and mempalace per-session memory coexist. Q4.10 PROVISIONAL remains provisional — revisit at v1.1 or when mempalace v4 lands as standalone.
6.5 Quality (7 tools)
Section titled “6.5 Quality (7 tools)”Verdict: [RETAIN-AS-IS]
Quality category (get_quality_summary, get_coverage_gaps, audit_content, find_all_duplicates, suggest_content_creation, get_quality_briefing, get_quality_actions) is stable. These are read-only tools serving governance and curation workflows. No pre-launch changes needed.
6.6 Governance / admin (5 tools) + Supersession (1 tool) + Review (3 tools)
Section titled “6.6 Governance / admin (5 tools) + Supersession (1 tool) + Review (3 tools)”Verdict: [RETAIN-AS-IS]
Governance category (delete_content_item, update_governance_status, update_publication_status, get_governance_queue, review_governance_item), supersession (supersede_content_item), and review (get_review_queue, get_assignments_for_user, create_review_assignment) are stable write surfaces. Two tools are marked destructive (delete_content_item, supersede_content_item) with DESTRUCTIVE_WRITE_ANNOTATIONS. No pre-launch changes needed.
6.7 AI operations (2 tools)
Section titled “6.7 AI operations (2 tools)”Verdict: [RETAIN-AS-IS]
classify_content and generate_summary are stable. Both use per-user Supabase clients; write tools call checkMcpRole. No pre-launch changes needed. Note: classifyContent userId must be a UUID (pipeline service account a0000000-0000-4000-8000-000000000001 per CLAUDE.md); this is a call-site concern, not a tool-signature concern.
6.8 Intelligence (2 tools)
Section titled “6.8 Intelligence (2 tools)”Verdict: [REFINE] — trigger_intelligence_poll is write-without-guard
get_intelligence_summary is [RETAIN-AS-IS].
trigger_intelligence_poll is marked write (No read-only) but has no domain or workspace_id scope parameter — it triggers a platform-wide intelligence poll. This is an unbounded write that any editor can trigger. Pre-launch consideration: add a workspace_id scope guard or restrict to admin role. Category: tech spec needed — assess blast radius of a free-trigger poll and whether workspace scoping is appropriate.
6.9 Remaining categories (entities, templates, apps, guides, change-report, workspaces)
Section titled “6.9 Remaining categories (entities, templates, apps, guides, change-report, workspaces)”Verdict: [RETAIN-AS-IS]
Entities (2), templates (3), MCP Apps trigger (4), guides (4), change-report (1), workspaces (1) — stable read and safe-write surfaces. No pre-launch changes needed. The show_* app tools serve the four MCP App interactive surfaces (§2.4).
One note: get_change_report uses user-facing label “Change Reports” — internal code still uses “digest” per CLAUDE.md Gotcha. The tool name (get_change_report) is correct; internal implementation drift is not a tool-surface concern.
6.10 Summary verdict
Section titled “6.10 Summary verdict”| Category | Verdict | Pre-launch action |
|---|---|---|
| Search / browse (5) | [RETAIN-AS-IS] | None |
| Content item ops (9) | [RETAIN-AS-IS] | Monitor source-doc shape on cocoindex landing |
| Bid / procurement ops (5) | [REFINE] | Rename 3 tools [LOCKSTEP-WITH-MIGRATION]; tech spec needed for sequencing |
| Dashboard (4) | [REFINE] | Q4.10 PROVISIONAL — coexist with mempalace; revisit v1.1 |
| Quality (7) | [RETAIN-AS-IS] | None |
| Governance + supersession + review (9) | [RETAIN-AS-IS] | None |
| AI ops (2) | [RETAIN-AS-IS] | None |
| Intelligence (2) | [REFINE] | trigger_intelligence_poll scope guard — tech spec needed |
| Entities + templates + apps + guides + change-report + workspaces (15) | [RETAIN-AS-IS] | None |
Two tech specs flagged as prerequisites before launch: bid/procurement tool rename sequencing; trigger_intelligence_poll scope guard.
6.11 Per-tool audit — separate work package (S241+)
Section titled “6.11 Per-tool audit — separate work package (S241+)”The category-level summary above is the architecture record; it is not a substitute for a per-tool audit. The wider audit — covering all 58 tools individually with per-tool retain/refine/remove/extend verdicts, cognitive-overhead reduction analysis (loading 50+ tools risks user + Claude context bloat), and a refreshed docs/client-documentation/Knowledge Hub — Claude Integration Guide.md — is a separate work package queued for S241+.
Scope (audit work package):
- Per-tool review — each of the 58 tools (read-only / write / destructive split as per
docs/generated/mcp-inventory.mdsummary) gets an individual verdict. Consolidation candidates surface (e.g. multiple search tools that could collapse into a single parametrised tool; multiple dashboards that overlap with mempalace surfaces). - Cognitive overhead reduction — flag tools that overlap with mempalace’s surface (already-available memory ops should not duplicate as KH tools); flag tools whose use cases are now better served by general MCP tools shipped with Claude Desktop / Claude.ai.
- Client-documentation refresh —
Knowledge Hub — Claude Integration Guide.mdis stale (last verified 23/04/2026 against 54/12/7; current 58/12/7). The refresh aligns the user-facing description with the post-audit tool surface — not the pre-auditmcp-inventory.mdraw dump. - Tier-vocabulary application — verdicts use the 6-tag tier vocabulary from
07-collapse-list.md([RATIFIED-RETIRE]/[RATIFIED-RENAME]/[RATIFIED-DO-NOT-BUILD]/[DEFERRED-v1.1]/[CONDITIONAL-RETIRE]/[LOCKSTEP-WITH-MIGRATION]).
Output: New deliverable at docs/specs/mcp-tooling-audit/ (PRODUCT.md for the user-facing rationale + TECH.md for the per-tool verdict register). Architecture record cross-refs the audit doc when it lands.
Sources to gather at audit start:
docs/generated/mcp-inventory.md— current 58 tools / 12 resources / 7 promptslib/mcp/— registration sites for context on each tool’s purposedocs/client-documentation/Knowledge Hub — Claude Integration Guide.md— current user-facing description (stale; audit produces the refresh)- This sub-doc §6.1-§6.10 — category-level priors that scope each per-tool review
- Mempalace MCP tool inventory — to identify overlapping / consolidatable surfaces
7. Migration path to wrapped pattern (DEFERRED-POST-LAUNCH)
Section titled “7. Migration path to wrapped pattern (DEFERRED-POST-LAUNCH)”Tag: [DEFERRED-POST-LAUNCH]
Per docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md §8.3, the wrapped pattern becomes viable when mempalace v4 PG-backend reaches production-stable and is deployable as a standalone MCP HTTP server (Q4.6 gate, 0.9-decision-graph.md §3.C).
When that gate clears:
- KH MCP can call mempalace via
@modelcontextprotocol/sdkclient from within Vercel functions — no client-side proxy process required. wing: <workspace_id>injection becomes code-enforced in KH MCP tool handlers. Prompt-discipline enforcement (§4.3) is retired.- Composite tools become feasible:
get_reorientation(tool #7) can internally call mempalace memory search to augment its output, returning a unified context block. Q4.10 PROVISIONAL resolves in favour of integrated replacement. - Mempalace tool names (currently visible as
mempalace_*in Claude’s context under the direct pattern) disappear behind KH-namespaced wrappers — consistent with the “AI is invisible infrastructure” principle perdocs/reference/ai-visibility-policy.md. - Memory operations enter KH’s telemetry surface (
logBestEffortWarn,audit_log) with op_id propagation per N7 RESOLVED-S236.
Migration is additive. KH wraps the tools it needs to intercept (workspace-scoped memory search, workspace-scoped diary write) while retaining direct access for dev-workflow tools (mempalace_status, mempalace_list_wings) where KH scoping is not relevant. A hybrid configuration — wrapper for tenant-scoped tools, direct for dev-workflow tools — is the likely v1.1 shape.
Prerequisite gate: mempalace v4 PG-backend deployable as a standalone MCP HTTP server. This is outside KH’s control; track against Q4.6 in 0.9-decision-graph.md §3.C.
8. Anti-patterns + retired patterns
Section titled “8. Anti-patterns + retired patterns”| Anti-pattern | Why retired | Citation |
|---|---|---|
createMcpHandler for the KH MCP server on Vercel | Breaks on Vercel — use WebStandardStreamableHTTPServerTransport directly with a fresh server + transport per request. mcp-handler is valid for .well-known only. | CLAUDE.md “mcp-handler breaks on Vercel”; 03-tech-stack.md §3.3 |
Reusing McpServer or transport instances across Vercel requests | Vercel warm instances corrupt shared state with a reused server. Fresh server + transport per request is mandatory. | lib/mcp/CLAUDE.md “Fresh server per request” gotcha |
Auto-memory file system (feedback_*.md / project_*.md / reference_*.md in ~/.claude/projects/.../memory/) | Phased out 2026-05-10; replaced by mempalace plugin. Do NOT author new files in that pattern. | CLAUDE.md “Memory (Mempalace)”: “Auto-memory file system phased out” |
| CopilotKit embedded chat sidebar | Removed S109. No embedded chat sidebar pattern exists or is planned. All AI-assisted interactions run invisibly in the background or route to Claude via bridge actions. | docs/reference/ai-visibility-policy.md Rule 4; 03-tech-stack.md §13 retired table |
| Labelling mempalace as an “AI memory feature” | Mempalace is invisible development infrastructure — session continuity for the dev team. It is not a user-facing product feature; do not surface it in user-facing copy or UI. | docs/reference/ai-visibility-policy.md; CLAUDE.md “Key Product Design Principles” — AI as invisible infrastructure |
Calling mempalace_search with wing parameter in v3.3.5 | Wing-filter errors: Error executing plan: Internal error: Error finding id. Workaround: search default (no wing param), filter client-side by wing field. | CLAUDE.md “Memory (Mempalace)”; OQ-Q45-A |
| Wrapping mempalace tools in KH MCP server-side code pre-v4 | Mempalace plugin runs in Claude’s local plugin runtime, not as an HTTP server callable from Vercel. Full server-side wrapping is architecturally infeasible until mempalace v4 standalone HTTP server is deployable. | docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md §6 |
9. Source-doc supersession
Section titled “9. Source-doc supersession”This sub-doc is one of nine that supersede docs/plans/phase-0-investigation/0.9-intended-architecture.md (2015 lines, S229). The source doc’s MCP-tooling framing predates the Theme F resolution and the full tool-inventory shape. Full audit trail of superseded items: docs/specs/core-docs-pathway-assessment/INV-architecture-split-readiness.md §2. Canonical-state sources downstream sub-docs cite: 00-synthesis-v2.md §5.2 row 1 (Theme F — CLOSED-S240); theme-f-mempalace-investigation.md §8 (direct-pattern rationale + migration path).
Source doc preserved as pre-split snapshot during Waves 1-4; archived to .planning/.archive/.specs/ after 09-diagrams.md closes per CLAUDE.md “Historical planning”.
9.1 Heritage docs feeding this sub-doc
Section titled “9.1 Heritage docs feeding this sub-doc”Per construction guide §4.1 — three-tier status taxonomy ([CURRENT-CANONICAL] / [PARTIALLY-SUPERSEDED] / [FULLY-SUPERSEDED]).
| Doc | Date | Status | Useful for |
|---|---|---|---|
docs/specs/core-docs-pathway-assessment/theme-f-mempalace-investigation.md | 15/05/2026 (S240) | [CURRENT-CANONICAL] — 299-line investigation doc; the primary ratification substrate for this sub-doc’s §4 direct-pattern ratification, §7 migration path, and §8 anti-pattern entry for pre-v4 wrapping. | Full pattern analysis, tradeoff matrix, robustness/extensibility/operational/architecture axes, Liam ratification decision, migration trigger gate. |
docs/plans/phase-0-investigation/10-feedback-investigation-findings/00-synthesis-v2.md §5.2 row 1 | 15/05/2026 | [CURRENT-CANONICAL] — Theme F register entry; records STILL-OPEN → CLOSED-S240 transition. | Theme F canonical register entry; MCP-action review pass scheduling context. |
docs/plans/phase-0-investigation/feedback-findings-review.md §5.1 | 14/05/2026 | [PARTIALLY-SUPERSEDED] — §5.1 Theme F entry records STILL-OPEN framing that is now resolved; rest of doc remains canonical for other themes. | Historical Theme F question statement; Q4.5 wire-up checklist origin (finding 03 §6.3). |
docs/client-documentation/Knowledge Hub — Claude Integration Guide.md | (companion to Platform Overview) | [CURRENT-CANONICAL] for Claude integration onboarding narrative. | Claude-via-MCP user-journey framing; end-user integration positioning that MCP tooling serves. |
docs/reference/ai-integration-strategy.md | 11/03/2026 (verified 28/04/2026) | [PARTIALLY-SUPERSEDED] — §3 four-layer architecture (MCP Server / MCP Apps / Cowork Plugin / Claude Code Plugin) holds; §17 + §18 build-status framing predates Phase 0.9. | Four-layer integration model (§3); MCP Server approach (§4.1); Cowork plugin patterns (§6). |
End of sub-doc. Theme F RATIFIED-S240. Wave 2 tail: 08-new-features.md. Wave 3: 09-diagrams.md (sequencing-gated on Waves 1-2 prose sub-docs landing).