ckb/.agents/modules/mcp/server/server.py
Michał Kopeć aab4b9e5e2 Template 2.0.3: Windows encoding, line endings, BOM, paths, hooks
Fixes F7-F11 from the 2.0.0 script review:
- UTF-8 stdout/stderr in every script; UTF-8 decoding of git/rg/yt-dlp
  output and of hook stdin
- utf-8-sig reads, so BOM files keep their frontmatter
- fingerprints match LF or CRLF checkouts (lint, lint_quick.sh,
  consolidate); prefix match on the full digest; short ones reported
- POSIX paths in lint output; rg --path-separator /
- hook installers default to the running interpreter, quote paths,
  --check reports a missing interpreter, odd settings are an error

New tests/unit/test_windows.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 15:32:26 +01:00

464 lines
22 KiB
Python

#!/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, encoding="utf-8", errors="replace")
if _r.returncode == 0 and _r.stdout.strip():
ENV[_var] = _r.stdout.strip()
ABOUT_PLACEHOLDERS = {
"One sentence on what this knowledge base holds and who it is for.",
"Jedno zdanie o tym, co zawiera ta baza wiedzy i dla kogo jest.",
}
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, then of ABOUT.pl.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, encoding="utf-8", errors="replace")
name = re.sub(r"\.git$", "", Path(r.stdout.strip()).name) 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 / "ABOUT.pl.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-sig").split("\n---", 1)[0], re.M)
desc = m.group(1).strip().strip('"') if m else ""
if desc in ABOUT_PLACEHOLDERS:
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/<name>/ > libs/<name>/.
- 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/<scope>.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()