knowledge-bundle-mcp 0.1.0__py3-none-any.whl

knowledge_bundle_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: knowledge-bundle-mcp
+Version: 0.1.0
+Summary: MCP bundle for people with a self-hosted knowledge base. First module: Open Notebook.
+Project-URL: Repository, https://github.com/seayniclabs/knowledge
+Author: Seaynic Labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: knowledge-base,mcp,model-context-protocol,notes,open-notebook
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]<2,>=1.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Knowledge
+
+<!-- mcp-name: io.github.seayniclabs/knowledge -->
+
+Knowledge is an MCP server for people who run their own knowledge base. It lets an AI assistant search, read and write the notes in it, from one install.
+
+It is a **bundle**: one server made of modules. You switch on the modules you use. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.
+
+**Audience:** people who self-host [Open Notebook](https://github.com/lfnovo/open-notebook) and want their assistant to use it.
+
+| Module | What it does | Status |
+|---|---|---|
+| `open_notebook` | Open Notebook over its REST API: list notebooks, search (keyword or meaning), read notes and sources, create a note (you approve each one) | 0.1 |
+
+Knowledge works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, Sonique, Hermes, OpenClaw and others. It runs on your computer and stores nothing. Your notes stay in your Open Notebook server.
+
+## Install
+
+Knowledge needs Python 3.11 or newer. With [uv](https://docs.astral.sh/uv/) you don't install anything ahead of time:
+
+```bash
+uvx knowledge-bundle-mcp --version
+```
+
+Or with pip:
+
+```bash
+pip install knowledge-bundle-mcp
+```
+
+## Settings
+
+Set these as environment variables in your MCP client's config, or put them in a config file (see below). Knowledge starts without any of them and tells you what's missing when you call a tool.
+
+| Variable | Module | What it is |
+|---|---|---|
+| `KNOWLEDGE_OPEN_NOTEBOOK_URL` | open_notebook | Address of your Open Notebook server, e.g. `https://notebook.example.com`. No path. |
+| `KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD` | open_notebook | Only if your server has a password (`OPEN_NOTEBOOK_PASSWORD` on the server). Leave it unset otherwise. |
+| `KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM` | open_notebook | `true` by default: you approve each new note. `false` lets the assistant create notes on its own. |
+| `KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS` | open_notebook | Optional. Comma-separated notebook names the assistant may write to without asking, e.g. `Research,Inbox` |
+| `KNOWLEDGE_<MODULE>_ENABLED` | any | `false` turns a module off, e.g. `KNOWLEDGE_OPEN_NOTEBOOK_ENABLED=false` |
+
+**Config file (optional).** Knowledge also reads `~/.config/knowledge/config.toml`, or the file named by `KNOWLEDGE_CONFIG`. Environment variables win over the file.
+
+```toml
+[open_notebook]
+url = "https://notebook.example.com"
+password = "change-me"
+require_confirm = true
+```
+
+## Add it to your MCP client
+
+Most clients use the same JSON shape. Put it where your client keeps MCP servers:
+
+```json
+{
+  "mcpServers": {
+    "knowledge": {
+      "command": "uvx",
+      "args": ["knowledge-bundle-mcp"],
+      "env": {
+        "KNOWLEDGE_OPEN_NOTEBOOK_URL": "https://notebook.example.com"
+      }
+    }
+  }
+}
+```
+
+| Client | Where the config goes |
+|---|---|
+| Claude Desktop | `claude_desktop_config.json` (Settings → Developer → Edit Config) |
+| Claude Code | `claude mcp add knowledge -- uvx knowledge-bundle-mcp`, then add the `env` values, or a project `.mcp.json` |
+| Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project |
+| VS Code | `.vscode/mcp.json`, using `"servers"` instead of `"mcpServers"` |
+| Sonique, Hermes, OpenClaw, others | Any client that launches a stdio MCP server: command `uvx`, args `["knowledge-bundle-mcp"]`, plus the env values |
+
+**Over HTTP.** For clients that connect to a URL instead of launching a process:
+
+```bash
+knowledge-mcp --transport http --port 8765
+```
+
+It serves streamable HTTP at `http://127.0.0.1:8765/mcp`. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `knowledge_modules` | Which modules are on, which settings are missing, and what each tool does. Call this first. |
+| `open_notebook_notebooks` | Your notebooks, most recently updated first, paged |
+| `open_notebook_search` | Matching sources and notes. `mode` is `text` (keywords) or `vector` (meaning; needs an embedding model on the server). Optional `notebook_id`. Paged. |
+| `open_notebook_notes` | The notes in one notebook, titles only, paged |
+| `open_notebook_note_get` | One note's content, cut at `max_chars` |
+| `open_notebook_source_get` | One source: title, topics, extracted text, notebooks |
+| `open_notebook_note_create` | Saves a note after you approve it. Without `confirm=true` it only returns a preview. |
+
+Every tool returns structured data with a published schema, so an assistant can work with the results instead of parsing text. Errors always look like `knowledge.<module>.<code>: <message> Fix: <hint>`.
+
+## Safety
+
+- Knowledge only calls the Open Notebook server you configure. It sends nothing anywhere else and keeps no data of its own.
+- `open_notebook_note_create` changes your notes, so **you** approve each one. When the assistant asks to save, Knowledge asks you directly through your MCP client (MCP elicitation) and shows the notebook, title and full text. The assistant can't answer that question for you.
+- Some MCP clients can't ask you questions yet. In those, Knowledge refuses to write unless you've pre-approved the notebook with `KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS`, or turned approval off with `KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false`.
+- Before anything is written, text that looks like a credential (API keys, tokens, private keys, passwords in URLs) is refused. The error names the kind of credential found, never the value.
+- Use an `https://` address for your server, and give the password only to Knowledge, not to other tools.
+
+## Develop
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+## License
+
+MIT. Published by Seaynic Labs.

knowledge_bundle_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+knowledge_mcp/__init__.py,sha256=qc5lHwohszvftUPcy7XCEwXhHpBeVansrBWWtYWj51I,100
+knowledge_mcp/config.py,sha256=n6bGWQR36r2eo5sfXbuMAS0yeqHlfafBhOipJne1XuI,1985
+knowledge_mcp/errors.py,sha256=OzI8It1HcDGKUYVJTHfyyX9Yvsitrk5i-PF7u0UEh4k,900
+knowledge_mcp/scrub.py,sha256=OooDySiBAiaoExYViyg6A1LbkwLDkGlJiivNZliSlkw,1963
+knowledge_mcp/server.py,sha256=rPpjtj0kGwpqbjmJl0o7Sx6WnBjFA-QdCWCXlRaDQNA,3632
+knowledge_mcp/modules/__init__.py,sha256=ZxIRApVbu-n1n-SUZtyklLBC3c9FB3FB1ROvrG0FHHs,2092
+knowledge_mcp/modules/open_notebook.py,sha256=6v9Pz1HPEDVuMkExpy1kNpQZXYCidvaLR90UZPGtRuw,21681
+knowledge_bundle_mcp-0.1.0.dist-info/METADATA,sha256=RJ-xTZ0hOx2HxRxt11KTX13tYz0ydJizuZEKBoZEpM0,6443
+knowledge_bundle_mcp-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+knowledge_bundle_mcp-0.1.0.dist-info/entry_points.txt,sha256=pAaPfmdZQdWOPFtaoGr3qKxt0dIz96gWvhC3dh2a0uk,60
+knowledge_bundle_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=NnI9eeFE_jBI35s6INYnWMoCrELXjX4GF0gsipF7puQ,1069
+knowledge_bundle_mcp-0.1.0.dist-info/RECORD,,

knowledge_bundle_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

knowledge_bundle_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+knowledge-mcp = knowledge_mcp.server:main

knowledge_bundle_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seaynic Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

knowledge_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Knowledge: an MCP bundle for people with a self-hosted knowledge base."""
+
+__version__ = "0.1.0"

knowledge_mcp/config.py

@@ -0,0 +1,56 @@
+"""Settings come from environment variables, then an optional TOML file.
+
+Environment variables win. The file is ``$KNOWLEDGE_CONFIG`` if set, otherwise
+``$XDG_CONFIG_HOME/knowledge/config.toml`` (``~/.config/knowledge/config.toml``).
+Each module reads its own ``[<module>]`` table; ``KNOWLEDGE_<MODULE>_<KEY>`` overrides
+any key in it. Nothing here assumes a particular MCP client.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Mapping
+
+TRUE = {"1", "true", "yes", "on"}
+FALSE = {"0", "false", "no", "off"}
+
+
+def config_path(env: Mapping[str, str]) -> Path:
+    if env.get("KNOWLEDGE_CONFIG"):
+        return Path(env["KNOWLEDGE_CONFIG"]).expanduser()
+    base = env.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "knowledge" / "config.toml"
+
+
+class Config:
+    def __init__(self, env: Mapping[str, str] | None = None, file_data: dict | None = None):
+        self.env = dict(os.environ if env is None else env)
+        if file_data is None:
+            path = config_path(self.env)
+            file_data = tomllib.loads(path.read_text()) if path.is_file() else {}
+        self.file = file_data
+
+    def get(self, module: str, key: str, default: str | None = None) -> str | None:
+        value = self.env.get(f"KNOWLEDGE_{module.upper()}_{key.upper()}")
+        if value not in (None, ""):
+            return value
+        value = self.file.get(module, {}).get(key)
+        if value not in (None, ""):
+            return str(value)
+        return default
+
+    def flag(self, module: str, key: str, default: bool) -> bool:
+        value = self.get(module, key)
+        if value is None:
+            return default
+        value = value.strip().lower()
+        if value in TRUE:
+            return True
+        if value in FALSE:
+            return False
+        return default
+
+    def enabled(self, module: str, default: bool) -> bool:
+        return self.flag(module, "enabled", default)

knowledge_mcp/errors.py

@@ -0,0 +1,26 @@
+"""One error shape for every module, so scripts can rely on it.
+
+Every failure a tool reports reads: ``knowledge.<module>.<code>: <message> Fix: <hint>``.
+"""
+
+from mcp.server.fastmcp.exceptions import ToolError
+
+
+class KnowledgeError(ToolError):
+    def __init__(self, module: str, code: str, message: str, hint: str = ""):
+        self.module = module
+        self.code = code
+        text = f"knowledge.{module}.{code}: {message}"
+        if hint:
+            text += f" Fix: {hint}"
+        super().__init__(text)
+
+
+def not_configured(module: str, missing: list[str]) -> KnowledgeError:
+    return KnowledgeError(
+        module,
+        "not_configured",
+        f"missing setting(s) {', '.join(missing)}.",
+        "set them as environment variables or in the [" + module + "] section of the "
+        "config file, then restart the server. Call knowledge_modules to see every setting.",
+    )

knowledge_mcp/modules/__init__.py

@@ -0,0 +1,70 @@
+"""Module contract and registry.
+
+A module is one integration (Open Notebook, ...). It declares its settings and
+registers its tools on the shared server. Adding a module = adding a file here and
+listing it in ``all_modules``. Modules added after 0.1 must set ``default_enabled = False``
+so an update never turns on something the user did not choose.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from ..config import Config
+from ..errors import not_configured
+
+ClientFactory = Callable[[], httpx.AsyncClient]
+
+
+def default_client_factory() -> httpx.AsyncClient:
+    return httpx.AsyncClient(timeout=60.0)
+
+
+@dataclass(frozen=True)
+class Setting:
+    key: str
+    help: str
+    secret: bool = False
+    required: bool = True
+
+    def env_var(self, module: str) -> str:
+        return f"KNOWLEDGE_{module.upper()}_{self.key.upper()}"
+
+
+@dataclass
+class Module:
+    name: str
+    summary: str
+    settings: list[Setting]
+    default_enabled: bool = True
+    tools: dict[str, str] = field(default_factory=dict)  # tool name -> one-line purpose
+
+    def missing(self, config: Config) -> list[str]:
+        return [
+            s.env_var(self.name)
+            for s in self.settings
+            if s.required and not config.get(self.name, s.key)
+        ]
+
+    def require(self, config: Config, *keys: str) -> dict[str, str]:
+        """Return the named settings, or raise a not_configured error naming the env vars."""
+        values = {k: config.get(self.name, k) for k in keys}
+        absent = [
+            s.env_var(self.name) for s in self.settings if s.key in keys and not values[s.key]
+        ]
+        if absent:
+            raise not_configured(self.name, absent)
+        return values  # type: ignore[return-value]
+
+    def register(self, mcp: FastMCP, config: Config, client_factory: ClientFactory) -> None:
+        raise NotImplementedError
+
+
+def all_modules() -> list[Module]:
+    from .open_notebook import OpenNotebookModule
+
+    return [OpenNotebookModule()]

knowledge_mcp/modules/open_notebook.py

@@ -0,0 +1,468 @@
+"""Open Notebook: notebooks, search, sources and notes, over its REST API.
+
+Endpoints and shapes were read from Open Notebook's own FastAPI routers (api/routers/*.py):
+GET /api/notebooks, POST /api/search, GET /api/notes, GET/POST /api/notes,
+GET /api/notes/{id}, GET /api/sources/{id}, GET /api/notebooks (for names).
+Auth: when the server has OPEN_NOTEBOOK_PASSWORD set, every /api call needs
+``Authorization: Bearer <password>``; with no password set, no header is needed.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from urllib.parse import urlsplit
+
+import httpx
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import BaseModel, Field
+
+from ..config import Config
+from ..errors import KnowledgeError
+from ..scrub import check_text
+from . import ClientFactory, Module, Setting
+
+MODULE = "open_notebook"
+READ_ONLY = ToolAnnotations(readOnlyHint=True, openWorldHint=False)
+WRITES_NOTE = ToolAnnotations(readOnlyHint=False, destructiveHint=False, idempotentHint=False, openWorldHint=False)
+
+MAX_NOTE_CHARS = 180_000
+MAX_TITLE_CHARS = 200
+MAX_QUERY_CHARS = 500
+MAX_SNIPPET_CHARS = 500
+MAX_FETCH = 200  # most items any one call will ask the server for
+
+NOTEBOOK_ID = re.compile(r"notebook:[A-Za-z0-9_-]{1,120}")
+NOTE_ID = re.compile(r"note:[A-Za-z0-9_-]{1,120}")
+SOURCE_ID = re.compile(r"source:[A-Za-z0-9_-]{1,120}")
+
+
+# --- typed results ----------------------------------------------------------
+
+class NotebookInfo(BaseModel):
+    id: str
+    name: str
+    description: str = ""
+    archived: bool = False
+    source_count: int = 0
+    note_count: int = 0
+    updated: str = ""
+
+
+class NotebookPage(BaseModel):
+    notebooks: list[NotebookInfo]
+    offset: int
+    limit: int
+    has_more: bool
+    next_offset: int | None = None
+
+
+class SearchHit(BaseModel):
+    id: str
+    kind: Literal["source", "note", "insight", "other"]
+    title: str | None = None
+    snippet: str | None = Field(None, description="Matched text; matched words are wrapped in backticks.")
+    parent_id: str | None = None
+    score: float | None = Field(None, description="Relevance (text) or similarity (vector). Higher is better.")
+
+
+class SearchPage(BaseModel):
+    query: str
+    mode: Literal["text", "vector"]
+    notebook_id: str | None = None
+    hits: list[SearchHit]
+    offset: int
+    limit: int
+    has_more: bool
+    next_offset: int | None = None
+
+
+class NoteSummary(BaseModel):
+    id: str
+    title: str | None = None
+    note_type: str | None = None
+    updated: str = ""
+
+
+class NotePage(BaseModel):
+    notebook_id: str
+    notes: list[NoteSummary]
+    offset: int
+    limit: int
+    has_more: bool
+    next_offset: int | None = None
+
+
+class NoteDetail(BaseModel):
+    id: str
+    title: str | None = None
+    note_type: str | None = None
+    content: str | None = None
+    content_chars: int
+    truncated: bool
+    created: str = ""
+    updated: str = ""
+
+
+class SourceDetail(BaseModel):
+    id: str
+    title: str | None = None
+    topics: list[str] = []
+    embedded: bool = False
+    embedded_chunks: int = 0
+    notebooks: list[str] = []
+    status: str | None = None
+    full_text: str | None = None
+    content_chars: int = 0
+    truncated: bool = False
+    created: str = ""
+    updated: str = ""
+
+
+class NoteWrite(BaseModel):
+    created: bool = Field(description="True only when the note was saved.")
+    title: str
+    notebook_id: str
+    notebook_name: str
+    content_chars: int
+    id: str | None = None
+    preview: str | None = Field(None, description="Start of the content, when nothing was saved yet.")
+    approved_by: str | None = Field(None, description='"person", "allowlist" or "settings".')
+    embedding_command_id: str | None = None
+    note: str | None = None
+
+
+class WriteApproval(BaseModel):
+    create: bool = Field(description="Save this note to the notebook now?")
+
+
+# --- helpers ----------------------------------------------------------------
+
+def _window(limit: int, offset: int) -> tuple[int, int]:
+    return max(1, min(limit, 100)), max(0, offset)
+
+
+def _page_bounds(offset: int, limit: int, total_seen: int) -> tuple[bool, int | None]:
+    has_more = total_seen > offset + limit
+    return has_more, (offset + limit if has_more else None)
+
+
+def _check_id(value: str, pattern: re.Pattern[str], field: str, shape: str) -> str:
+    if not pattern.fullmatch(value or ""):
+        raise KnowledgeError(
+            MODULE, "bad_input", f"{field} {value!r} is not a valid id.",
+            f"pass an id of the form {shape}, as returned by the list or search tools.",
+        )
+    return value
+
+
+def _clip(text: Any, max_chars: int) -> tuple[str | None, bool]:
+    if text is None:
+        return None, False
+    s = str(text)
+    if len(s) <= max_chars:
+        return s, False
+    return s[:max_chars], True
+
+
+def _float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _kind(item_id: str) -> str:
+    prefix = item_id.split(":", 1)[0]
+    return {"source": "source", "note": "note", "source_insight": "insight"}.get(prefix, "other")
+
+
+def _allowlist(config: Config) -> list[str]:
+    raw = config.get(MODULE, "allowed_notebooks") or ""
+    return [n.strip().lower() for n in raw.split(",") if n.strip()]
+
+
+def _can_ask_person(ctx: Context) -> bool:
+    try:
+        caps = ctx.session.client_params.capabilities  # type: ignore[union-attr]
+    except (ValueError, AttributeError):
+        return False
+    return bool(caps and caps.elicitation)
+
+
+def _approval_text(title: str, notebook_name: str, content: str) -> str:
+    return "\n".join([
+        "Save this note to Open Notebook?",
+        f"Notebook: {notebook_name!r}",
+        f"Title: {title!r}",
+        f"Content ({len(content)} characters):",
+        content,
+    ])
+
+
+# --- module -----------------------------------------------------------------
+
+class OpenNotebookModule(Module):
+    def __init__(self) -> None:
+        super().__init__(
+            name=MODULE,
+            summary="Your self-hosted Open Notebook: list notebooks, search, read notes and sources, "
+                    "and create a note (you approve each one).",
+            settings=[
+                Setting("url", "Address of your Open Notebook server, e.g. https://notebook.example.com "
+                        "(no path). Required for every tool."),
+                Setting("password", "The password you set on the server with OPEN_NOTEBOOK_PASSWORD. "
+                        "Leave unset if the server has no password.", secret=True, required=False),
+                Setting("require_confirm", "true (default): you approve each new note. false: the "
+                        "assistant may create notes on its own.", required=False),
+                Setting("allowed_notebooks", "Comma-separated notebook names the assistant may write to "
+                        "without asking, e.g. Research,Inbox.", required=False),
+            ],
+            tools={
+                "open_notebook_notebooks": "List notebooks (paged).",
+                "open_notebook_search": "Search sources and notes by keyword (text) or meaning (vector).",
+                "open_notebook_notes": "List the notes in one notebook (paged, titles only).",
+                "open_notebook_note_get": "Read one note's content.",
+                "open_notebook_source_get": "Read one source: its title, topics and extracted text.",
+                "open_notebook_note_create": "Create a note in a notebook. Preview first; you approve it.",
+            },
+        )
+
+    def register(self, mcp: FastMCP, config: Config, client_factory: ClientFactory) -> None:
+        module = self
+
+        def base_url() -> str:
+            url = module.require(config, "url")["url"].strip().rstrip("/")
+            parts = urlsplit(url)
+            if parts.scheme not in ("http", "https") or not parts.netloc:
+                raise KnowledgeError(
+                    MODULE, "bad_url", "KNOWLEDGE_OPEN_NOTEBOOK_URL must start with http:// or https:// "
+                    "and name a host.",
+                    "use the address you open in a browser, e.g. https://notebook.example.com.",
+                )
+            return url
+
+        async def call(method: str, path: str, *, params: dict[str, Any] | None = None,
+                       json_body: dict[str, Any] | None = None) -> Any:
+            url = base_url()
+            headers: dict[str, str] = {}
+            password = config.get(MODULE, "password")
+            if password:
+                headers["Authorization"] = f"Bearer {password}"
+            try:
+                async with client_factory() as client:
+                    r = await client.request(method, f"{url}/api{path}", params=params,
+                                             json=json_body, headers=headers)
+            except httpx.HTTPError as e:
+                raise KnowledgeError(MODULE, "unreachable",
+                                     f"could not reach Open Notebook ({type(e).__name__}).",
+                                     "check KNOWLEDGE_OPEN_NOTEBOOK_URL and that the server is running.")
+            if r.status_code == 401:
+                raise KnowledgeError(MODULE, "auth_failed", "Open Notebook rejected the request (401).",
+                                     "set KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD to the server's password, or "
+                                     "unset it if the server has no password.")
+            if r.status_code >= 400:
+                detail = ""
+                try:
+                    body = r.json()
+                    detail = str(body.get("detail", "")) if isinstance(body, dict) else ""
+                except ValueError:
+                    pass
+                detail = (detail or r.reason_phrase or "error")[:200]
+                if r.status_code == 404:
+                    raise KnowledgeError(MODULE, "not_found", f"Open Notebook: {detail}.",
+                                         "check the id with the list or search tools.")
+                raise KnowledgeError(MODULE, "api_error", f"Open Notebook returned {r.status_code}: {detail}.")
+            try:
+                return r.json()
+            except ValueError:
+                raise KnowledgeError(MODULE, "api_error", "Open Notebook did not return JSON.",
+                                     "check that KNOWLEDGE_OPEN_NOTEBOOK_URL points at the server, not a web page.")
+
+        async def notebook_name(notebook_id: str) -> str:
+            data = await call("GET", "/notebooks")
+            for nb in data if isinstance(data, list) else []:
+                if str(nb.get("id", "")) == notebook_id:
+                    return str(nb.get("name") or "")
+            raise KnowledgeError(MODULE, "not_found", f"no notebook with id {notebook_id!r}.",
+                                 "call open_notebook_notebooks to list the ids.")
+
+        @mcp.tool(annotations=READ_ONLY)
+        async def open_notebook_notebooks(limit: int = 20, offset: int = 0,
+                                          include_archived: bool = False) -> NotebookPage:
+            """List your notebooks, most recently updated first. Page with offset=<next_offset>."""
+            limit, offset = _window(limit, offset)
+            params: dict[str, Any] = {"order_by": "updated desc"}
+            if not include_archived:
+                params["archived"] = "false"
+            data = await call("GET", "/notebooks", params=params)
+            items = data if isinstance(data, list) else []
+            window = items[offset: offset + limit]
+            has_more, nxt = _page_bounds(offset, limit, len(items))
+            return NotebookPage(
+                notebooks=[NotebookInfo(
+                    id=str(nb.get("id", "")), name=str(nb.get("name") or ""),
+                    description=str(nb.get("description") or ""), archived=bool(nb.get("archived")),
+                    source_count=int(nb.get("source_count") or 0), note_count=int(nb.get("note_count") or 0),
+                    updated=str(nb.get("updated") or ""),
+                ) for nb in window],
+                offset=offset, limit=limit, has_more=has_more, next_offset=nxt,
+            )
+
+        @mcp.tool(annotations=READ_ONLY)
+        async def open_notebook_search(
+            query: str,
+            notebook_id: str | None = None,
+            mode: Literal["text", "vector"] = "text",
+            include_sources: bool = True,
+            include_notes: bool = True,
+            limit: int = 10,
+            offset: int = 0,
+        ) -> SearchPage:
+            """Search sources and notes. mode 'text' matches keywords; 'vector' matches meaning and
+            needs an embedding model set up on the server. Limit a search to one notebook with
+            notebook_id. Page with offset=<next_offset>."""
+            q = query.strip()
+            if not q:
+                raise KnowledgeError(MODULE, "bad_input", "query is empty.", "pass the words to search for.")
+            if len(q) > MAX_QUERY_CHARS:
+                raise KnowledgeError(MODULE, "bad_input", f"query is longer than {MAX_QUERY_CHARS} characters.",
+                                     "shorten it.")
+            if notebook_id is not None:
+                _check_id(notebook_id, NOTEBOOK_ID, "notebook_id", "notebook:<id>")
+            limit, offset = _window(limit, offset)
+            need = offset + limit + 1  # one extra row tells us whether another page exists
+            if need > MAX_FETCH:
+                raise KnowledgeError(MODULE, "bad_input", "offset is too large for search paging.",
+                                     "narrow the query with notebook_id, or use a smaller offset.")
+            body: dict[str, Any] = {"query": q, "type": mode, "limit": need,
+                                    "search_sources": include_sources, "search_notes": include_notes}
+            if notebook_id:
+                body["notebook_ids"] = [notebook_id]
+            data = await call("POST", "/search", json_body=body)
+            raw = data.get("results", []) if isinstance(data, dict) else []
+            hits = []
+            for r in raw:
+                item_id = str(r.get("id", ""))
+                snippet, _ = _clip(r.get("content"), MAX_SNIPPET_CHARS)
+                parent = r.get("parent_id")
+                hits.append(SearchHit(
+                    id=item_id, kind=_kind(item_id),  # type: ignore[arg-type]
+                    title=r.get("title"), snippet=snippet,
+                    parent_id=str(parent) if parent else None,
+                    score=_float(r.get("relevance", r.get("similarity"))),
+                ))
+            window = hits[offset: offset + limit]
+            has_more, nxt = _page_bounds(offset, limit, len(hits))
+            return SearchPage(query=q, mode=mode, notebook_id=notebook_id, hits=window,
+                              offset=offset, limit=limit, has_more=has_more, next_offset=nxt)
+
+        @mcp.tool(annotations=READ_ONLY)
+        async def open_notebook_notes(notebook_id: str, limit: int = 20, offset: int = 0) -> NotePage:
+            """List the notes in one notebook, titles only. Read a note with open_notebook_note_get.
+            Page with offset=<next_offset>."""
+            _check_id(notebook_id, NOTEBOOK_ID, "notebook_id", "notebook:<id>")
+            limit, offset = _window(limit, offset)
+            data = await call("GET", "/notes", params={"notebook_id": notebook_id})
+            items = data if isinstance(data, list) else []
+            window = items[offset: offset + limit]
+            has_more, nxt = _page_bounds(offset, limit, len(items))
+            return NotePage(
+                notebook_id=notebook_id,
+                notes=[NoteSummary(id=str(n.get("id", "")), title=n.get("title"),
+                                   note_type=n.get("note_type"), updated=str(n.get("updated") or ""))
+                       for n in window],
+                offset=offset, limit=limit, has_more=has_more, next_offset=nxt,
+            )
+
+        @mcp.tool(annotations=READ_ONLY)
+        async def open_notebook_note_get(note_id: str, max_chars: int = 8000) -> NoteDetail:
+            """Read one note. Long content is cut at max_chars (up to 50000) and marked truncated."""
+            _check_id(note_id, NOTE_ID, "note_id", "note:<id>")
+            limit = max(200, min(max_chars, 50_000))
+            n = await call("GET", f"/notes/{note_id}")
+            content, truncated = _clip(n.get("content"), limit)
+            return NoteDetail(id=str(n.get("id", note_id)), title=n.get("title"), note_type=n.get("note_type"),
+                              content=content, content_chars=len(str(n.get("content") or "")),
+                              truncated=truncated, created=str(n.get("created") or ""),
+                              updated=str(n.get("updated") or ""))
+
+        @mcp.tool(annotations=READ_ONLY)
+        async def open_notebook_source_get(source_id: str, max_chars: int = 8000) -> SourceDetail:
+            """Read one source: its title, topics, extracted text (cut at max_chars, up to 50000) and
+            the notebooks it belongs to."""
+            _check_id(source_id, SOURCE_ID, "source_id", "source:<id>")
+            limit = max(200, min(max_chars, 50_000))
+            s = await call("GET", f"/sources/{source_id}")
+            text, truncated = _clip(s.get("full_text"), limit)
+            return SourceDetail(
+                id=str(s.get("id", source_id)), title=s.get("title"),
+                topics=[str(t) for t in (s.get("topics") or [])],
+                embedded=bool(s.get("embedded")), embedded_chunks=int(s.get("embedded_chunks") or 0),
+                notebooks=[str(n) for n in (s.get("notebooks") or [])], status=s.get("status"),
+                full_text=text, content_chars=len(str(s.get("full_text") or "")), truncated=truncated,
+                created=str(s.get("created") or ""), updated=str(s.get("updated") or ""),
+            )
+
+        @mcp.tool(annotations=WRITES_NOTE)
+        async def open_notebook_note_create(
+            ctx: Context, notebook_id: str, title: str, content: str, confirm: bool = False,
+        ) -> NoteWrite:
+            """Create a note in a notebook. Without confirm=true it only returns a preview. With
+            confirm=true you are asked to approve it (unless the notebook is pre-approved in settings);
+            the assistant cannot approve on your behalf. Text that looks like a credential is refused."""
+            _check_id(notebook_id, NOTEBOOK_ID, "notebook_id", "notebook:<id>")
+            title = title.strip()
+            if not title or len(title) > MAX_TITLE_CHARS or any(ord(c) < 32 for c in title):
+                raise KnowledgeError(MODULE, "bad_input",
+                                     f"title must be 1 to {MAX_TITLE_CHARS} characters with no control characters.",
+                                     "give the note a short plain title.")
+            if not content.strip():
+                raise KnowledgeError(MODULE, "bad_input", "content is empty.", "provide the note text.")
+            if len(content) > MAX_NOTE_CHARS:
+                raise KnowledgeError(MODULE, "bad_input", f"content is longer than {MAX_NOTE_CHARS} characters.",
+                                     "split it into several notes.")
+            check_text(title, "title")
+            check_text(content, "content")
+
+            name = await notebook_name(notebook_id)
+            allowlist = _allowlist(config)
+            outside = bool(allowlist) and name.lower() not in allowlist
+            base = dict(title=title, notebook_id=notebook_id, notebook_name=name, content_chars=len(content))
+
+            if not confirm:
+                note = "Preview only. Call again with confirm=true; you will be asked to approve it."
+                if outside:
+                    note = (f"Preview only. Notebook {name!r} is not in "
+                            "KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS, so you will be asked to approve it.")
+                return NoteWrite(created=False, preview=content[:600], note=note, **base)
+
+            # Approval comes from the person or from settings, never from the model's own arguments.
+            approved_by = None
+            if not config.flag(MODULE, "require_confirm", True):
+                approved_by = "settings"
+            elif allowlist and not outside:
+                approved_by = "allowlist"
+            elif _can_ask_person(ctx):
+                answer = await ctx.elicit(_approval_text(title, name, content), WriteApproval)
+                if answer.action != "accept" or not answer.data.create:
+                    return NoteWrite(created=False, note="You declined. Nothing was saved.", **base)
+                approved_by = "person"
+            else:
+                raise KnowledgeError(
+                    MODULE, "approval_unavailable",
+                    "this MCP client cannot ask you to approve a write, and the notebook is not pre-approved.",
+                    "set KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS to the notebook names the assistant may write "
+                    "to, or KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false to let it write on its own.",
+                )
+
+            data = await call("POST", "/notes", json_body={
+                "title": title, "content": content, "note_type": "human", "notebook_id": notebook_id,
+            })
+            return NoteWrite(
+                created=True, id=data.get("id"), approved_by=approved_by,
+                embedding_command_id=data.get("command_id"),
+                note="Saved. Search indexing runs in the background and may take a moment.", **base,
+            )

knowledge_mcp/scrub.py

@@ -0,0 +1,47 @@
+"""Refuse to save text that looks like a credential.
+
+The check reports the kind of credential it found, never the matched value.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .errors import KnowledgeError
+
+_RULES: list[tuple[str, re.Pattern[str]]] = [
+    ("private_key", re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----")),
+    ("api_key_sk", re.compile(r"\bsk-[A-Za-z0-9_-]{16,}")),
+    ("github_token", re.compile(r"\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})")),
+    ("slack_token", re.compile(r"\bxox[abposr]-[A-Za-z0-9-]{10,}")),
+    ("aws_access_key", re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b")),
+    ("google_api_key", re.compile(r"\bAIza[0-9A-Za-z_-]{30,}")),
+    ("gitlab_token", re.compile(r"\bglpat-[A-Za-z0-9_-]{16,}")),
+    ("resend_api_key", re.compile(r"\bre_[A-Za-z0-9]{20,}")),
+    ("bearer_token", re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]{20,}")),
+    ("password_in_url", re.compile(r"[a-z][a-z0-9+.-]*://[^\s/@:]+:[^\s/@]+@", re.I)),
+    (
+        "credential_assignment",
+        re.compile(
+            r"(?i)\b(?:password|passwd|api[_-]?key|client[_-]?secret|access[_-]?token"
+            r"|auth[_-]?token|secret)\s*[:=]\s*['\"]?[^\s'\"]{6,}"
+        ),
+    ),
+]
+
+
+def find_credential_kinds(text: str) -> list[str]:
+    """Names of the credential types found in ``text``, sorted, without duplicates."""
+    return sorted({name for name, pattern in _RULES if pattern.search(text)})
+
+
+def check_text(text: str, field: str, module: str = "open_notebook") -> None:
+    kinds = find_credential_kinds(text)
+    if kinds:
+        raise KnowledgeError(
+            module,
+            "blocked_secret",
+            f"the {field} looks like it contains a credential ({', '.join(kinds)}). Nothing was saved.",
+            "remove the credential from the text and try again. Notes are read back by every "
+            "assistant that searches this knowledge base, so secrets must stay out of them.",
+        )

knowledge_mcp/server.py

@@ -0,0 +1,102 @@
+"""Knowledge server: one process, one tool per module operation, plus a discovery call."""
+
+from __future__ import annotations
+
+import argparse
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import BaseModel
+
+from . import __version__
+from .config import Config, config_path
+from .modules import ClientFactory, Module, all_modules, default_client_factory
+
+INSTRUCTIONS = (
+    "Knowledge connects to your self-hosted knowledge base (first module: Open Notebook). "
+    "Call knowledge_modules first: it says which modules are on, which settings are missing, and what each tool does. "
+    "Tools return structured results; errors read 'knowledge.<module>.<code>: <message> Fix: <hint>'."
+)
+
+
+class SettingInfo(BaseModel):
+    env_var: str
+    help: str
+    secret: bool
+    set: bool
+
+
+class ModuleInfo(BaseModel):
+    name: str
+    summary: str
+    enabled: bool
+    configured: bool
+    missing: list[str]
+    tools: dict[str, str]
+    settings: list[SettingInfo] | None = None
+
+
+class ModulesResult(BaseModel):
+    version: str
+    config_file: str
+    modules: list[ModuleInfo]
+
+
+def build_server(
+    config: Config | None = None,
+    client_factory: ClientFactory = default_client_factory,
+    modules: list[Module] | None = None,
+    **settings,
+) -> FastMCP:
+    config = config or Config()
+    modules = modules if modules is not None else all_modules()
+    mcp = FastMCP("knowledge", instructions=INSTRUCTIONS, **settings)
+    # FastMCP 1.x reports the SDK's version unless the low-level server is told otherwise.
+    mcp._mcp_server.version = __version__
+
+    for module in modules:
+        if config.enabled(module.name, module.default_enabled):
+            module.register(mcp, config, client_factory)
+
+    @mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=False))
+    def knowledge_modules(module: str | None = None) -> ModulesResult:
+        """Which modules are on, what settings are missing, and what each tool does.
+        Pass a module name for its full settings list."""
+        infos = []
+        for m in modules:
+            if module and m.name != module:
+                continue
+            missing = m.missing(config)
+            info = ModuleInfo(
+                name=m.name, summary=m.summary,
+                enabled=config.enabled(m.name, m.default_enabled),
+                configured=not missing, missing=missing, tools=m.tools,
+            )
+            if module:
+                info.settings = [
+                    SettingInfo(env_var=s.env_var(m.name), help=s.help, secret=s.secret,
+                                set=bool(config.get(m.name, s.key)))
+                    for s in m.settings
+                ]
+            infos.append(info)
+        return ModulesResult(version=__version__, config_file=str(config_path(config.env)), modules=infos)
+
+    return mcp
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="knowledge-mcp", description=INSTRUCTIONS)
+    parser.add_argument("--transport", choices=["stdio", "http"], default="stdio")
+    parser.add_argument("--host", default="127.0.0.1", help="HTTP only. Keep 127.0.0.1 unless you add auth in front.")
+    parser.add_argument("--port", type=int, default=8765, help="HTTP only.")
+    parser.add_argument("--version", action="version", version=f"knowledge-mcp {__version__}")
+    args = parser.parse_args(argv)
+
+    if args.transport == "http":
+        build_server(host=args.host, port=args.port).run(transport="streamable-http")
+    else:
+        build_server().run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()