#!/usr/bin/env python3 """ckb MCP server: exposes a Cascade KB to any MCP client - Claude's web and desktop apps, Claude Code, or anything else that speaks MCP. python3 server.py # streamable HTTP on CKB_MCP_HOST:CKB_MCP_PORT CKB_MCP_TRANSPORT=stdio python3 server.py Configuration is environment-only; env.example lists every variable. Reads are cascade-aware (the ckb-retrieve script ranks, read_page serves the evidence). Writes never touch wiki/: add_to_inbox drops material into raw/inbox/ for the next ckb-ingest, withdraw_submission deletes one's own un-ingested item, and request_retraction queues the removal of an ingested source for ckb-retract. Every write names its target KB and is confirmed by the user (see _gate), because one client may hold several KB connectors and a misrouted write is a leak. """ import hashlib import hmac import inspect import json import os import secrets import time import re import subprocess import sys from pathlib import Path HERE = Path(__file__).resolve().parent sys.path.insert(0, str(HERE)) from kb import KB, Author, PolicyError # noqa: E402 import auth # noqa: E402 from typing import Annotated # noqa: E402 from pydantic import BaseModel, Field # noqa: E402 from mcp.server.elicitation import AcceptedElicitation, ElicitationResult # noqa: E402 from mcp.server.mcpserver import Context, Elicit, MCPServer, Resolve # noqa: E402 from mcp.server.mcpserver.exceptions import ToolError # noqa: E402 from mcp.types import ToolAnnotations # noqa: E402 ENV = os.environ TRANSPORT = ENV.get("CKB_MCP_TRANSPORT", "http") AUTH = ENV.get("CKB_MCP_AUTH", "none" if TRANSPORT == "stdio" else "token") WRITE = ENV.get("CKB_MCP_WRITE", "inbox") HOST = ENV.get("CKB_MCP_HOST", "127.0.0.1") PORT = int(ENV.get("CKB_MCP_PORT", "8765")) MCP_PATH = "/" + ENV.get("CKB_MCP_PATH", "/mcp").strip("/") PUBLIC_URL = ENV.get("CKB_MCP_PUBLIC_URL", f"http://{HOST}:{PORT}").rstrip("/") if AUTH not in ("none", "token", "oauth"): raise SystemExit(f"CKB_MCP_AUTH must be none, token or oauth, not {AUTH!r}") if WRITE not in ("inbox", "off"): raise SystemExit(f"CKB_MCP_WRITE must be inbox or off, not {WRITE!r}") # auto: the user confirms every write - in the client's own dialog when it supports # elicitation, else by a second call carrying a signed confirmation code. off: no # confirmation (one KB, or an automated agent), the kb argument is still checked. CONFIRM = ENV.get("CKB_MCP_CONFIRM", "auto") if CONFIRM not in ("auto", "off"): raise SystemExit(f"CKB_MCP_CONFIRM must be auto or off, not {CONFIRM!r}") # Signs confirmation codes. Random per process unless set; set it when running # several replicas of one KB, so a code issued by one is accepted by another. _CONFIRM_KEY = (ENV.get("CKB_MCP_CONFIRM_SECRET") or secrets.token_hex(32)).encode() CONFIRM_TTL = 900 if (TRANSPORT == "http" and AUTH == "none" and HOST not in ("127.0.0.1", "localhost", "::1") and ENV.get("CKB_MCP_ALLOW_UNAUTHENTICATED") != "1"): raise SystemExit("Refusing to serve without authentication on a non-loopback address. " "Set CKB_MCP_AUTH=token or oauth, or CKB_MCP_ALLOW_UNAUTHENTICATED=1 behind a VPN.") kb_store = KB( ENV.get("CKB_ROOT", str(HERE.parents[3])), git_mode=ENV.get("CKB_MCP_GIT", "off"), pull_interval=int(ENV.get("CKB_MCP_PULL_INTERVAL", "60")), max_inbox_bytes=int(ENV.get("CKB_MCP_MAX_INBOX_BYTES", "200000")), committer=Author(ENV.get("CKB_MCP_GIT_NAME", "ckb-mcp"), ENV.get("CKB_MCP_GIT_EMAIL", "ckb-mcp@localhost")), remote=ENV.get("CKB_MCP_GIT_REMOTE", "origin"), branch=ENV.get("CKB_MCP_GIT_BRANCH") or None, ) kb_store.check_dedicated_clone() # Author of submissions when no per-user identity exists (none mode, single token): # the env vars, else this checkout's git identity, as Rule E resolves a session's author. for _var, _key in (("CKB_MCP_AUTHOR_NAME", "user.name"), ("CKB_MCP_AUTHOR_EMAIL", "user.email")): if not ENV.get(_var): _r = subprocess.run(["git", "-C", str(kb_store.root), "config", _key], capture_output=True, text=True) if _r.returncode == 0 and _r.stdout.strip(): ENV[_var] = _r.stdout.strip() ABOUT_PLACEHOLDER = "One sentence on what this knowledge base holds and who it is for." def _kb_identity(): """(name, description) telling this KB apart when one client connects to several. Name: CKB_MCP_NAME, else the origin repo's name, else the folder name. Description: CKB_MCP_DESCRIPTION, else the tldr of ABOUT.md (unless still the scaffold's placeholder), else wiki/overview.md's tldr.""" name = ENV.get("CKB_MCP_NAME") if not name: r = subprocess.run(["git", "-C", str(kb_store.root), "remote", "get-url", "origin"], capture_output=True, text=True) name = Path(r.stdout.strip()).name.removesuffix(".git") if r.returncode == 0 and r.stdout.strip() else kb_store.root.name desc = ENV.get("CKB_MCP_DESCRIPTION", "") for f in (kb_store.root / "ABOUT.md", kb_store.root / "wiki" / "overview.md"): if desc or not f.is_file(): continue m = re.search(r"^tldr:\s*(.+)$", f.read_text(encoding="utf-8").split("\n---", 1)[0], re.M) desc = m.group(1).strip().strip('"') if m else "" if desc == ABOUT_PLACEHOLDER: desc = "" return re.sub(r"[^A-Za-z0-9_-]+", "-", name).strip("-") or "ckb", desc KB_NAME, KB_DESC = _kb_identity() ABOUT = f"the '{KB_NAME}' knowledge base" + (f" ({KB_DESC})" if KB_DESC else "") INSTRUCTIONS = f"""\ This server is {ABOUT}: a Cascade Knowledge Base, a curated wiki (wiki/) layered over read-only upstream KBs (linked/) and indexed external sources (libs/). Other connectors may serve other knowledge bases. Use this one for questions about '{KB_NAME}', and name the KB when you cite it. Answering: - Start with search_kb; for orientation call kb_overview once. - Cascade priority, first match wins: wiki/ > linked// > libs//. - A search hit's tldr is compressed. Before relying on a page, read_page it, and when it matters, read the sources it cites under raw/archive/ or outputs/. - Cite page paths in answers. Flag pages marked stale or superseded_by, and results from raw/inbox/ (submitted but not yet ingested, so unreviewed). - If nothing answers the question, say so plainly rather than guessing. Adding knowledge: - add_to_inbox stores new material in raw/inbox/. It is NOT in the wiki until someone runs the ingest workflow, so tell the user it was queued, never that the wiki was updated. Put the facts in content, with dates, names and where they came from; one topic per submission. Writing safely when several KBs are connected: - Every write takes kb='{KB_NAME}'. Pass it only when the user means this KB. If the material could belong to more than one connected KB, ask which one first; never pick by guess. - A write may come back as confirmation_required. Ask the user the question it gives, and call again with the confirmation code only after they say yes. Never confirm on their behalf. - Wrong KB? list_my_submissions shows what you sent here. Still pending: withdraw_submission deletes it. Already ingested: request_retraction queues its removal, with everything built from it, for the maintainers. Then submit it again through the right KB's connector. """ auth_settings, verifier = (None, None) if AUTH == "oauth": auth_settings, verifier = auth.oauth_settings(ENV, PUBLIC_URL + MCP_PATH) class KBServer(MCPServer): async def list_tools(self): """Read-only callers do not see write tools at all, so a model never offers an action the server would refuse. call-time checks stay the real guard.""" tools = await super().list_tools() if WRITE_TOOLS and not _caller()[1]: tools = [t for t in tools if t.name not in WRITE_TOOLS] return tools WRITE_TOOLS = set() mcp = KBServer( name=KB_NAME, title=f"{KB_NAME} (Cascade KB)", instructions=INSTRUCTIONS, version=(kb_store.root / "VERSION").read_text().strip() if (kb_store.root / "VERSION").is_file() else "", auth=auth_settings, token_verifier=verifier, ) READ = ToolAnnotations(read_only_hint=True, open_world_hint=False) def _d(text): """Tool description prefixed with the KB name, so a client holding several KB connectors can tell their identically named tools apart.""" return f"[{KB_NAME}] " + inspect.cleandoc(text) def _caller(): """(Author, may_write) for the current request; (None, False) if unauthenticated.""" who = auth.caller(AUTH, ENV) if who is None: return None, False name, email, may_write = who return Author(name, email), may_write and WRITE != "off" def _run(fn, *a, **kw): try: return fn(*a, **kw) except PolicyError as e: raise ToolError(str(e)) from e @mcp.tool(annotations=READ, description=_d("""Orientation: the owner's ABOUT.md (purpose, audience, scope, owners), the KB's routing index, its overview page, which upstream layers (linked/, libs/) exist, and how many inbox items await ingest. Call once at the start of a conversation about this KB.""")) def kb_overview() -> str: return f"Knowledge base: {ABOUT}\n\n" + _run(kb_store.overview) @mcp.tool(annotations=READ, description=_d("""Ranked candidate pages for a question, fused from exact-text, title/tldr, project-scope, graph and trust signals, across wiki/, linked/ and libs/. Each candidate has path, title, type, tldr, staleness, confidence and the sources it cites. `scope` narrows to a wiki/projects/.md project. This ranks; it does not verify - read_page the candidates you rely on.""")) def search_kb(query: str, top: int = 10, scope: str | None = None) -> dict: return _run(kb_store.search, query, top=max(1, min(top, 30)), scope=scope) @mcp.tool(annotations=READ, description=_d("""Full text of one file, by KB-root-relative path (e.g. wiki/entities/foo.md, or a cited source such as raw/archive/2026-09-01/notes.md). Readable areas: wiki/, linked/, libs/, raw/inbox/, raw/archive/, outputs/, and your own retraction requests in raw/retractions/.""")) def read_page(path: str) -> str: return _run(kb_store.read_page, path, viewer=_caller()[0]) @mcp.tool(annotations=READ, description=_d("""Markdown pages under a directory (recursive) with title, type and tldr. Use for browsing, e.g. 'wiki/entities' or 'wiki/decisions'; prefer search_kb for questions.""")) def list_pages(directory: str = "wiki") -> list[dict]: return _run(kb_store.list_pages, directory, viewer=_caller()[0]) # ------------------------------------------------------------- write gate --- class Confirm(BaseModel): confirm: bool = Field(description=f"Yes - do this in the '{KB_NAME}' knowledge base") def _kb_matches(kb_arg): return (kb_arg or "").strip().lower() == KB_NAME.lower() def _writer(): author, may_write = _caller() if not may_write: raise ToolError("your account may read this KB but not change it") return author def _can_ask(kb, ctx): """Whether to ask the user through the client. Elicitation needs the stateless-safe 2026-07-28 protocol; an older client cannot be asked mid-call by this server and gets a confirmation code instead.""" caps = ctx.client_capabilities return (CONFIRM != "off" and _kb_matches(kb) and bool(caps and caps.elicitation) and (ctx.protocol_version or "") >= "2026-07-28" and _caller()[1]) def _q_add(title): return f"Add “{title}” to the '{KB_NAME}' knowledge base" + (f" ({KB_DESC})" if KB_DESC else "") + "?" def _q_withdraw(path): return f"Withdraw “{path}” from the '{KB_NAME}' inbox? The file is deleted." def _q_retract(path): return f"Request removal of “{path}” and everything built from it in the '{KB_NAME}' KB?" # Resolvers run before the tool body and receive tool arguments by name. def _ask_add(kb: str, title: str, ctx: Context): return Elicit(_q_add(title), Confirm) if _can_ask(kb, ctx) else None def _ask_withdraw(kb: str, path: str, ctx: Context): return Elicit(_q_withdraw(path), Confirm) if _can_ask(kb, ctx) else None def _ask_retract(kb: str, path: str, ctx: Context): return Elicit(_q_retract(path), Confirm) if _can_ask(kb, ctx) else None def _code(action, author, payload, ts): msg = json.dumps([action, KB_NAME, author.email, payload, ts], sort_keys=True, ensure_ascii=False) return f"{ts}.{hmac.new(_CONFIRM_KEY, msg.encode(), hashlib.sha256).hexdigest()[:24]}" def _gate(action, kb_arg, author, payload, answer, confirmation, question): """None when the write may go ahead; otherwise a confirmation_required result. Raises when the target KB is wrong or the user said no.""" if not _kb_matches(kb_arg): about = f" ({KB_DESC})" if KB_DESC else "" raise ToolError(f"This connector is the '{KB_NAME}' KB{about}, not '{kb_arg}'. Nothing was written. " f"If '{kb_arg}' is another KB, use its own connector. If the user meant this KB, " f"confirm that with them and call again with kb='{KB_NAME}'.") if CONFIRM == "off": return None if isinstance(answer, AcceptedElicitation) and answer.data is not None: if answer.data.confirm: return None raise ToolError("The user did not confirm. Nothing was written.") if answer is not None and not isinstance(answer, AcceptedElicitation): raise ToolError("The user declined. Nothing was written.") # No elicitation: a signed code binds this exact action, KB, caller and payload. if confirmation: ts, _, _ = confirmation.partition(".") if ts.isdigit() and 0 <= time.time() - int(ts) <= CONFIRM_TTL and \ hmac.compare_digest(confirmation, _code(action, author, payload, int(ts))): return None raise ToolError("That confirmation code is invalid or expired, or the arguments changed since it was " "issued. Nothing was written. Call again without it for a new one.") return { "status": "confirmation_required", "nothing_written": True, "kb": KB_NAME, "kb_description": KB_DESC, "question_for_user": question, "confirmation": _code(action, author, payload, int(time.time())), "expires_in_seconds": CONFIRM_TTL, "next_step": "Ask the user the question above, in this conversation. Only if they answer yes, call this " "tool again with exactly the same arguments plus this confirmation code. If they say no " "or name another KB, do not call it again here.", } @mcp.tool(annotations=READ, description=_d("""Your own submissions to this KB, made through MCP: pending ones still in raw/inbox/, and ingested ones in raw/archive/ with the wiki pages and graph edges built from them, and whether a retraction is already requested. Use it to find a submission that went to the wrong KB.""")) def list_my_submissions() -> list[dict]: author, _ = _caller() if author is None: raise ToolError("no authenticated identity on this request") return _run(kb_store.submissions, author) if WRITE == "inbox": WRITE_TOOLS.update({"add_to_inbox", "withdraw_submission", "request_retraction"}) @mcp.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=False, open_world_hint=False), description=_d(f"""Submit new knowledge to the '{KB_NAME}' KB's inbox (raw/inbox/) for the next ingest. `kb` must be '{KB_NAME}': pass it only when the user means this KB, and ask them first if the material could belong to another connected KB. The user confirms the target before anything is written; if the result is confirmation_required, follow its next_step. It does not edit the wiki: tell the user it was queued. `content` is Markdown with the facts themselves - who, what, when, decisions, numbers - not a summary of the chat. `source` says where it came from (meeting, URL, document, person).""")) def add_to_inbox( kb: str, title: str, content: str, source: str | None = None, confirmation: str | None = None, answer: Annotated[ElicitationResult[Confirm], Resolve(_ask_add)] = None, ) -> dict: author = _writer() payload = {"title": title, "content": hashlib.sha256((content or "").encode()).hexdigest(), "source": source} gate = _gate("add", kb, author, payload, answer, confirmation, _q_add(title)) return gate or _run(kb_store.add_to_inbox, title, content, author, source=source) @mcp.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=True, idempotent_hint=True, open_world_hint=False), description=_d(f"""Withdraw (delete) one of your own submissions that is still pending in raw/inbox/ of the '{KB_NAME}' KB - e.g. one sent to the wrong KB. Only the person who submitted an item can withdraw it; `path` comes from list_my_submissions. Once ingested, a submission is in raw/archive/ and this refuses: use request_retraction. Confirmed by the user like any write.""")) def withdraw_submission( kb: str, path: str, confirmation: str | None = None, answer: Annotated[ElicitationResult[Confirm], Resolve(_ask_withdraw)] = None, ) -> dict: author = _writer() gate = _gate("withdraw", kb, author, {"path": path}, answer, confirmation, _q_withdraw(path)) return gate or _run(kb_store.withdraw, path, author) @mcp.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=True, open_world_hint=False), description=_d(f"""Ask for an ingested source in raw/archive/ of the '{KB_NAME}' KB to be removed together with everything built from it (wiki pages, claims, graph edges). This files a request in raw/retractions/; the KB's maintainers carry it out with the ckb-retract workflow, so tell the user it is requested, not done. `reason` says why, e.g. "sent to the wrong KB; belongs in project-beta". Only the person who submitted the source can ask; `path` comes from list_my_submissions. Confirmed by the user like any write.""")) def request_retraction( kb: str, path: str, reason: str, confirmation: str | None = None, answer: Annotated[ElicitationResult[Confirm], Resolve(_ask_retract)] = None, ) -> dict: author = _writer() gate = _gate("retract", kb, author, {"path": path, "reason": reason}, answer, confirmation, _q_retract(path)) return gate or _run(kb_store.request_retraction, path, author, reason) @mcp.resource("ckb://rules", name="kb-rules", mime_type="text/markdown", description="The KB's full operating rules (AGENTS.md): layout, page schema, cascade, links.") def rules() -> str: return kb_store.rules() @mcp.prompt(description="Answer a question from the knowledge base, with citations.") def answer_from_kb(question: str) -> str: return (f"Answer from the Cascade Knowledge Base: {question}\n\n" "Use search_kb, then read_page the candidates you rely on (and the sources " "they cite when a fact matters). Cite page paths. Say what is stale, " "unreviewed (raw/inbox/) or missing rather than filling gaps.") @mcp.custom_route("/health", methods=["GET"]) async def health(request): from starlette.responses import JSONResponse return JSONResponse({"status": "ok", "kb": KB_NAME, "auth": AUTH, "write": WRITE, "git": kb_store.git_mode}) def http_app(): from mcp.server.transport_security import TransportSecuritySettings hosts = [h for h in ENV.get("CKB_MCP_ALLOWED_HOSTS", "").replace(",", " ").split() if h] security = TransportSecuritySettings(enable_dns_rebinding_protection=bool(hosts), allowed_hosts=hosts) # Stateless + JSON responses: every request stands alone, which survives # restarts, reverse proxies and several replicas without session affinity. app = mcp.streamable_http_app(streamable_http_path=MCP_PATH, stateless_http=True, json_response=True, transport_security=security) if AUTH == "token": app = auth.TokenAuthMiddleware(app, auth.load_tokens(ENV), mcp_path=MCP_PATH) return app def _redact(value, secrets_): if isinstance(value, str): for s in secrets_: value = value.replace(s, "***") return value def main(): if TRANSPORT == "stdio": if AUTH != "none": raise SystemExit("stdio has no transport to authenticate; use CKB_MCP_AUTH=none") mcp.run("stdio") return import logging import uvicorn if AUTH == "token": # The secret-path form puts the token in the request line; keep it out of the access log. secrets_ = [t["token"] for t in auth.load_tokens(ENV)] class Redact(logging.Filter): def filter(self, record): if isinstance(record.args, tuple): record.args = tuple(_redact(a, secrets_) for a in record.args) return True logging.getLogger("uvicorn.access").addFilter(Redact()) print(f"ckb-mcp: serving '{KB_NAME}' from {kb_store.root} on {HOST}:{PORT}{MCP_PATH} (auth={AUTH}, write={WRITE}, git={kb_store.git_mode})", file=sys.stderr) uvicorn.run(http_app(), host=HOST, port=PORT, proxy_headers=True, forwarded_allow_ips=ENV.get("CKB_MCP_TRUSTED_PROXIES", "127.0.0.1"), log_level="info") if __name__ == "__main__": main()