Repository navigation
feat(knowledge-base): secured personal MCP server (FIX-855) - #705
Merged
Merged
Conversation
… (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
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
Contributor
Bugbot couldn't run - usage limit reachedBugbot 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.
Contributor
Bugbot couldn't run - usage limit reachedBugbot 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) |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Hardens the incubated
labs/knowledge-baselab 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
src/capability.ts): addedcreateConcept/updateConcept/deleteConceptfns(single-concept CRUD, incremental — never prunes the corpus likeimportOkfdoes);readConceptnow returns{ state, body };relatevalidates both endpoints exist. Exposes the nav tools so the flow reuses one tool surface.src/concepts.ts): flipped the concept collection toscope: "user"so the corpus binds to the authenticated principal and survives the stateless fresh-session-per-tools/callmodel.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 viaKB_MCP_SECRET(nodefaultUserIdfallback), constructed only when the secret is set. A sharedconceptIdFromUrinormalizer lets a search-result uri be pasted into any id-taking tool.fsdev.config.ts): registerscreateMcpTransportAdapter(), adds a Postgresprodprofile selected byFSD_DB_URL/DATABASE_URL, and fails closed at config load if the hosted profile is missingKB_MCP_SECRET(covers every entry that imports the config).src/server.ts): standaloneserve()entry (@flow-state-dev/node), no app wrapper. Refuses to bind a non-loopback interface withoutKB_MCP_SECRETas a second guard against an unauthenticated network exposure.README.md): new "Use it as an MCP server", "Stand it up", "Verify it works" sections; revised v0 limitations.explore/research/askdemo actions — their sample-bundle seeding callsimportBundle, whose whole-bundle sync would prune the durable user-scoped corpus.@flow-state-dev/knowledge-baseisprivate: true).Key decisions & ramifications
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.scope: "user"+ Postgres over session scope — per-principal isolation is native (scope_idderives fromuserId); makes a write visible to the next statelesstools/call; multi-user becomes a later config flip, not a redesign.assertSafeConceptIdnarrowed to OKF-reserved names only — a deviation from the spec's sketch: the framework'scollection.create()/getOptional()already reject../empty/control-char keys vianormalizeResourcePathbefore the capability runs (verified), so re-implementing traversal rejection would duplicate landed validation (BP-029). Onlyindex/logneed a lab-level guard.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 pullingnext/reactdeps into the lab for a posture nobody has asked to deploy yet.defaultUserIdfallback — the secure personal-use floor; a second bind guard inserver.tscloses 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 realserve()host over the loopback socket, backed by a PGlite-executor Postgresprodprofile (durable, real schema init — not in-memory).create_conceptin one HTTP request; a genuinely separate request'sread_conceptcarries the held-out passphrase andlist_conceptscarries the id (proving cross-call, user-scoped persistence under stateless MCP); an unauthenticatedtools/callis refused with 401.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.pnpm typecheck— clean across all 57 packages; package-boundary validation passes.server.tsbind 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_conceptsregex 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; Postgresprodvs local dev profiles are wired infsdev.config.ts, with fail-closedKB_MCP_SECRETwhen Postgres is configured.Capability & flow: adds
createConcept/updateConcept/deleteConcept, richerreadConcept, stricterrelate, and reserved-id guards; replaces the old explore/research demo with MCP handlers plusconceptIdFromUrifor search-result ids.src/server.tsadds standalonepnpm servewith 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-baselab into a secured personal MCP wiki. The main changes are:serve()entry with a bind guard.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.
What T-Rex did
Important Files Changed
serve()entry with a non-loopback bind guard requiringKB_MCP_SECRET.serve()goal check using PGlite-backed Postgres stores and bearer auth.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%%{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 unauthorizedReviews (2): Last reviewed commit: "refactor(knowledge-base): update filesys..." | Re-trigger Greptile