Skip to content

feat(knowledge-base): secured personal MCP server (FIX-855) - #705

Merged
jhoffner merged 4 commits into
mainfrom
claude/kb-mcp-5tdlvr
Jul 10, 2026
Merged

jhoffner merged 4 commits into
mainfrom
claude/kb-mcp-5tdlvr

Conversation

@jhoffner

@jhoffner jhoffner commented Jul 8, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Hardens the incubated labs/knowledge-base lab into a hosted, user-scoped, bearer-secured MCP server — a small always-on personal wiki that Claude (or any MCP client) can read, search, create, update, delete, and link concepts on, over a secured network connection. This is wiring over landed primitives (MCP transport FIX-22, principal-resolver auth FIX-23, Postgres store, standalone Node host FIX-712, OKF capability FIX-813) — no new framework, no public API surface, all lab-local.

Implements the spec on FIX-855 (Steps 1–5, 7; the optional Vercel posture in Step 6 was explicitly skippable and is documented-not-shipped).

Changes

  • Capability (src/capability.ts): added createConcept / updateConcept / deleteConcept fns (single-concept CRUD, incremental — never prunes the corpus like importOkf does); readConcept now returns { state, body }; relate validates both endpoints exist. Exposes the nav tools so the flow reuses one tool surface.
  • Storage (src/concepts.ts): flipped the concept collection to scope: "user" so the corpus binds to the authenticated principal and survives the stateless fresh-session-per-tools/call model.
  • Flow (src/flow.ts): rewritten to expose 8 MCP tools (list / read / search / grep / create / update / delete / relate). OKF import/export stay CLI-only (mcp: { enabled: false }) — they take server-side filesystem paths. Bearer-secret auth via KB_MCP_SECRET (no defaultUserId fallback), constructed only when the secret is set. A shared conceptIdFromUri normalizer lets a search-result uri be pasted into any id-taking tool.
  • Config (fsdev.config.ts): registers createMcpTransportAdapter(), adds a Postgres prod profile selected by FSD_DB_URL/DATABASE_URL, and fails closed at config load if the hosted profile is missing KB_MCP_SECRET (covers every entry that imports the config).
  • Serving (src/server.ts): standalone serve() entry (@flow-state-dev/node), no app wrapper. Refuses to bind a non-loopback interface without KB_MCP_SECRET as a second guard against an unauthenticated network exposure.
  • Docs (README.md): new "Use it as an MCP server", "Stand it up", "Verify it works" sections; revised v0 limitations.
  • Dropped the prior explore / research / ask demo actions — their sample-bundle seeding calls importBundle, whose whole-bundle sync would prune the durable user-scoped corpus.
  • Internal-only changeset (@flow-state-dev/knowledge-base is private: true).

Key decisions & ramifications

  1. Concept CRUD lives in the capability fns, not flow-local handlers — holds the KB vocabulary in one place (FIX-813 decision Add CI workflow for type checking and testing #4); the flow actions stay thin.
  2. scope: "user" + Postgres over session scope — per-principal isolation is native (scope_id derives from userId); makes a write visible to the next stateless tools/call; multi-user becomes a later config flip, not a redesign.
  3. assertSafeConceptId narrowed to OKF-reserved names only — a deviation from the spec's sketch: the framework's collection.create()/getOptional() already reject ../empty/control-char keys via normalizeResourcePath before the capability runs (verified), so re-implementing traversal rejection would duplicate landed validation (BP-029). Only index/log need a lab-level guard.
  4. Standalone serve() is the only serving path built — the Vercel/Next.js serverless posture (spec Step 6) was explicitly optional; it's documented as an alternative, not shipped. Avoids pulling next/react deps into the lab for a posture nobody has asked to deploy yet.
  5. Static bearer secret, no defaultUserId fallback — the secure personal-use floor; a second bind guard in server.ts closes the "dev profile silently chosen, still bound to 0.0.0.0" hole. Rotation / multi-user deferred.

Goal verdict

PASS — model-free end-to-end goal check at goals/personal-knowledge-mcp/persists-a-concept-across-stateless-calls/, run on the real path: a real serve() host over the loopback socket, backed by a PGlite-executor Postgres prod profile (durable, real schema init — not in-memory). create_concept in one HTTP request; a genuinely separate request's read_concept carries the held-out passphrase and list_concepts carries the id (proving cross-call, user-scoped persistence under stateless MCP); an unauthenticated tools/call is refused with 401.

pnpm tsx goals/personal-knowledge-mcp/persists-a-concept-across-stateless-calls/run.mts

Test plan

  • pnpm --filter @flow-state-dev/knowledge-base test — 49 passing (capability CRUD, user-scope isolation, MCP router round-trip, fail-closed config guard, existing OKF round-trip specs).
  • pnpm --filter @flow-state-dev/knowledge-base typecheck — clean.
  • Root pnpm typecheck — clean across all 57 packages; package-boundary validation passes.
  • server.ts bind guard verified manually across loopback+no-secret (serves), 0.0.0.0+no-secret (refuses), 0.0.0.0+secret (serves).

Reviewed by three parallel review agents (completeness vs. spec, simplification, quality/security); all confirmed no MUST-FIX. The security review's SHOULD-FIX items are addressed here (bind guard, rollback error masking) or documented as known limitations (non-atomic duplicate-id guard, grep ReDoS surface).

Fixes FIX-855

🤖 Generated with Claude Code

https://claude.ai/code/session_01HybZJ1EfNe1SHACTFNdsCZ


Generated by Claude Code


Note

Medium Risk
Changes touch authentication, hosted config fail-closed behavior, and network-exposed MCP CRUD over a user corpus; mitigations include bearer resolution, dual secret guards, and broad tests, but remote grep_concepts regex and static single-key auth remain documented limitations.

Overview
Turns the knowledge-base incubation lab into a bearer-secured personal MCP wiki: eight remote tools for concept list/read/search/grep/CRUD/relate, with OKF import/export kept CLI-only (filesystem paths).

Persistence & scope: concept storage moves from session to scope: "user" so writes survive stateless MCP calls for the same principal; Postgres prod vs local dev profiles are wired in fsdev.config.ts, with fail-closed KB_MCP_SECRET when Postgres is configured.

Capability & flow: adds createConcept / updateConcept / deleteConcept, richer readConcept, stricter relate, and reserved-id guards; replaces the old explore/research demo with MCP handlers plus conceptIdFromUri for search-result ids. src/server.ts adds standalone pnpm serve with a non-loopback bind guard when the secret is missing.

Verification: new goal check (serve() + PGlite Postgres + separate HTTP requests), expanded unit tests (MCP auth, config guard, user isolation), and README updates. Prior AI gateway demo dependencies are removed; goals package picks up MCP/node/postgres deps for the runner.

Reviewed by Cursor Bugbot for commit 6a3fe65. Configure here.

Greptile Summary

This PR turns the labs/knowledge-base lab into a secured personal MCP wiki. The main changes are:

  • Adds bearer-secured MCP tools for listing, reading, searching, creating, updating, deleting, and relating concepts.
  • Moves concept storage to user scope so writes survive stateless MCP calls for the authenticated principal.
  • Adds Postgres-backed hosted config, fail-closed secret checks, and a standalone serve() entry with a bind guard.
  • Keeps OKF import/export CLI-only and updates docs for server use, deployment, verification, and limitations.
  • Adds unit tests and a real-path goal check for MCP persistence and unauthenticated rejection.

Confidence Score: 5/5

Safe to merge with low risk for the changed lab-local surface.

No blocking correctness or security issues were identified in the MCP auth, config guards, user-scoped storage, CRUD handlers, server bind guard, or tests.

No files require special attention.

T-Rex T-Rex Logs

What T-Rex did

  • The log shows the active profile as prod and that the real flow ran for createConcept, readConcept, and listConcepts with distinct ephemeral request/session IDs.
  • The createConcept call returned the id topics/goal-check-concept.
  • The readConcept call in a separate request returned found:true and included the held-out body/passphrase content.
  • The listConcepts call returned an array of ids containing topics/goal-check-concept.
  • The final PASS confirms prod profile persistence on the durable PGlite setup and that unauthenticated tool calls receive a 401 on the loopback host.

View all artifacts

T-Rex Ran code and verified through T-Rex

Important Files Changed

Filename Overview
labs/knowledge-base/src/flow.ts Replaces demo actions with secured MCP CRUD/search tools, URI normalization, and CLI-only OKF import/export actions.
labs/knowledge-base/src/capability.ts Adds single-concept CRUD helpers, reserved-id validation, endpoint validation for relations, and exposes shared nav tools.
labs/knowledge-base/fsdev.config.ts Registers the MCP adapter, selects dev/prod store profiles, and fails closed when hosted auth is missing.
labs/knowledge-base/src/server.ts Adds a standalone serve() entry with a non-loopback bind guard requiring KB_MCP_SECRET.
labs/knowledge-base/src/concepts.ts Switches concepts from session scope to user scope for stateless MCP persistence by principal.
goals/personal-knowledge-mcp/persists-a-concept-across-stateless-calls/run.mts Adds a real-path loopback serve() goal check using PGlite-backed Postgres stores and bearer auth.
labs/knowledge-base/test/flow.spec.ts Covers the MCP tool surface, auth rejection, CRUD round-trip, URI normalization, and relation error handling.
labs/knowledge-base/test/capability.spec.ts Covers capability CRUD behavior, rollback, reserved ids, relation validation, and nav preset exposure.
labs/knowledge-base/test/config.spec.ts Covers dev/prod profile selection and the fail-closed secret requirement for hosted profiles.
labs/knowledge-base/test/user-scope.spec.ts Adds tests proving same-user persistence and cross-user isolation over a shared store.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Client as MCP Client
participant Server as src/server.ts serve()
participant Router as MCP transport adapter
participant Auth as Bearer principal resolver
participant Flow as knowledge flow tools
participant KB as knowledgeBase capability
participant Store as User-scoped concept store

Client->>Server: POST /api/flows/knowledge/mcp\nAuthorization: Bearer KB_MCP_SECRET
Server->>Router: route MCP JSON-RPC tools/call
Router->>Auth: resolve bearer principal
Auth-->>Router: "userId = owner"
Router->>Flow: execute selected tool\n(create/read/search/update/delete/relate)
Flow->>KB: call capability fn or nav tool
KB->>Store: read/write concepts under user scope
Store-->>KB: concept state/body/results
KB-->>Flow: tool result content
Flow-->>Router: JSON result content
Router-->>Client: 200 JSON-RPC response

Client->>Server: POST without/invalid Authorization
Server->>Router: route MCP request
Router->>Auth: resolve principal
Auth-->>Client: 401 unauthorized
Loading
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Client as MCP Client
participant Server as src/server.ts serve()
participant Router as MCP transport adapter
participant Auth as Bearer principal resolver
participant Flow as knowledge flow tools
participant KB as knowledgeBase capability
participant Store as User-scoped concept store

Client->>Server: POST /api/flows/knowledge/mcp\nAuthorization: Bearer KB_MCP_SECRET
Server->>Router: route MCP JSON-RPC tools/call
Router->>Auth: resolve bearer principal
Auth-->>Router: "userId = owner"
Router->>Flow: execute selected tool\n(create/read/search/update/delete/relate)
Flow->>KB: call capability fn or nav tool
KB->>Store: read/write concepts under user scope
Store-->>KB: concept state/body/results
KB-->>Flow: tool result content
Flow-->>Router: JSON result content
Router-->>Client: 200 JSON-RPC response

Client->>Server: POST without/invalid Authorization
Server->>Router: route MCP request
Router->>Auth: resolve principal
Auth-->>Client: 401 unauthorized
Loading

Reviews (2): Last reviewed commit: "refactor(knowledge-base): update filesys..." | Re-trigger Greptile

claude added 3 commits July 8, 2026 21:54
… (FIX-855)

Adds concept-level CRUD (createConcept/updateConcept/deleteConcept) to the
knowledgeBase capability, flips the concept collection to scope: "user",
and rewrites the lab flow to expose 8 MCP tools (list/read/search/grep/
create/update/delete/relate) with bearer-secret auth over KB_MCP_SECRET.
OKF import/export stay CLI-only (mcp: { enabled: false }) since they take
server-side filesystem paths.

Wires the MCP transport adapter + a Postgres store profile (fail-closed on
a missing secret at config load), adds a standalone serve() entry point
(no app wrapper), and drops the prior explore/research/ask demo actions
(their sample-bundle seeding would prune the durable user-scoped corpus).

Adds a model-free goal check proving cross-call persistence over a real
serve() host backed by a PGlite Postgres store, plus vitest coverage for
the capability CRUD, user-scope isolation, the MCP router surface, and the
config's fail-closed guard.

Fixes FIX-855

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HybZJ1EfNe1SHACTFNdsCZ
…erdict log

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HybZJ1EfNe1SHACTFNdsCZ
…d exposure (FIX-855)

Address review findings on the FIX-855 implementation:

- server.ts refuses to bind a non-loopback interface without KB_MCP_SECRET,
  closing the gap where an unset/mistyped DATABASE_URL silently selects the
  dev profile (no secret guard) while still binding 0.0.0.0 — which would
  fall through to the default body-userId resolver.
- createConcept's rollback tolerates a failing delete so the original
  write error is preserved rather than masked.
- README documents the non-atomic duplicate-id guard and the grep_concepts
  regex (ReDoS) surface as known limitations; tightens the concept-id
  sanitization comment for accuracy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HybZJ1EfNe1SHACTFNdsCZ
@linear-code

linear-code Bot commented Jul 8, 2026

Copy link
Copy Markdown

FIX-855

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@vercel

vercel Bot commented Jul 8, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
flow-state-dev-kitchen-sink Ready Ready Preview, Comment Jul 10, 2026 12:30am
2 Skipped Deployments
Project Deployment Actions Updated (UTC)
flow-state-dev-docs Ignored Ignored Preview Jul 10, 2026 12:30am
flow-state-dev-ui Ignored Ignored Preview Jul 10, 2026 12:30am

@cursor

cursor Bot commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_6e306490-87be-49da-9a21-71bb15acefd7)

…r logging

- Changed the primary store in the development configuration from in-memory to filesystem-based, allowing for persistent data storage.
- Added logging to indicate the server's starting port, improving visibility during server initialization.
@cursor

cursor Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_f53e2d31-104e-4666-959e-4ae7ff83c199)

@jhoffner
jhoffner merged commit 54c786f into main Jul 10, 2026
13 checks passed
@jhoffner
jhoffner deleted the claude/kb-mcp-5tdlvr branch July 10, 2026 00:32

This branch was successfully deployed

1 active deployment
Preview – flow-state-dev-kitchen-sink — 6a3fe657 Deployed Jul 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants