knowledge-bundle-mcp 0.1.0__tar.gz

knowledge_bundle_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv -p ${{ matrix.python }} && uv pip install -e '.[dev]'
+      - run: .venv/bin/pytest -q
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      # The gitleaks CLI is free; the GitHub Action needs a license for organization repos.
+      - name: gitleaks (full history)
+        run: docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:v8.30.1 git /repo --no-banner --redact
+      - name: Identifier scan
+        env:
+          IDENTIFIER_PATTERNS: ${{ secrets.IDENTIFIER_PATTERNS }}
+        run: python3 scripts/scan_identifiers.py .

knowledge_bundle_mcp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env
+.env.*
+
+# mcp-publisher writes login tokens into the working directory
+.mcpregistry_*

knowledge_bundle_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Knowledge follows [semantic versioning](https://semver.org). Modules added after 0.1 ship switched off.
+
+## 0.1.0 — unreleased
+
+- First release as one bundle, with one module: `open_notebook` (Open Notebook over its REST API).
+- `knowledge_modules` discovery tool: which modules are on, which settings are missing, what each tool does.
+- Tools: list notebooks, search (keyword or vector, optionally one notebook), list a notebook's notes, read a note, read a source, create a note.
+- Paged results with `offset` and `next_offset`; every tool returns structured data with a published output schema.
+- `open_notebook_note_create` previews by default. Saving needs the person's approval: asked through MCP elicitation, or given ahead of time with `KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS` or `KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false`. The assistant's own `confirm=true` is never enough.
+- Text that looks like a credential is refused before anything is written; the error names the kind, never the value.
+- Optional server password (Bearer), read from settings only.
+- Runs over stdio or streamable HTTP. Starts with no settings and reports what is missing when a tool is called.
+
+MIT License
+
+Copyright (c) 2026 Seaynic Labs

knowledge_bundle_mcp-0.1.0/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_bundle_mcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "knowledge-bundle-mcp"
+version = "0.1.0"
+description = "MCP bundle for people with a self-hosted knowledge base. First module: Open Notebook."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Seaynic Labs" }]
+# mcp is capped below 2: 2.x removed FastMCP, and unpinned installs crash.
+dependencies = [
+    "mcp[cli]>=1.27,<2",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+keywords = ["mcp", "model-context-protocol", "open-notebook", "knowledge-base", "notes"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Repository = "https://github.com/seayniclabs/knowledge"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+knowledge-mcp = "knowledge_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/knowledge_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

knowledge_bundle_mcp-0.1.0/scripts/scan_identifiers.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Fail if any tracked file contains a forbidden string.
+
+The patterns are not stored in this repository. Pass them in with
+``--patterns FILE`` or the ``IDENTIFIER_PATTERNS`` environment variable
+(one case-insensitive regular expression per line; ``#`` starts a comment).
+A line starting with ``!`` is an allowed exception: a match that also matches
+an exception is ignored.
+
+Usage:  python scripts/scan_identifiers.py --patterns ~/patterns.txt [path ...]
+Exit status 0 = clean, 1 = hits found, 2 = no patterns given.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def load(text: str) -> tuple[list[re.Pattern], list[re.Pattern]]:
+    block, allow = [], []
+    for line in text.splitlines():
+        line = line.split(" #", 1)[0].strip()
+        if not line or line.startswith("#"):
+            continue
+        (allow if line.startswith("!") else block).append(re.compile(line.lstrip("!"), re.I))
+    return block, allow
+
+
+def tracked_files(root: Path) -> list[Path]:
+    try:
+        out = subprocess.run(["git", "ls-files", "-co", "--exclude-standard"], cwd=root,
+                             capture_output=True, text=True, check=True).stdout
+        return [root / p for p in out.splitlines()]
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        skip = {".git", ".venv", "venv", "node_modules", "__pycache__", "dist", "build"}
+        return [p for p in root.rglob("*") if p.is_file() and not skip & set(p.parts)]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--patterns", help="file of patterns (default: $IDENTIFIER_PATTERNS)")
+    ap.add_argument("paths", nargs="*", default=["."])
+    args = ap.parse_args()
+
+    text = Path(args.patterns).expanduser().read_text() if args.patterns else os.environ.get("IDENTIFIER_PATTERNS", "")
+    block, allow = load(text)
+    if not block:
+        print("scan_identifiers: no patterns given (use --patterns or IDENTIFIER_PATTERNS)", file=sys.stderr)
+        return 2
+
+    hits = 0
+    for root in map(Path, args.paths):
+        for f in tracked_files(root) if root.is_dir() else [root]:
+            try:
+                lines = f.read_text(errors="ignore").splitlines()
+            except OSError:
+                continue
+            for n, line in enumerate(lines, 1):
+                for pat in block:
+                    for m in pat.finditer(line):
+                        if any(a.search(line) for a in allow):
+                            continue
+                        hits += 1
+                        # Print where, not the line itself: the line may hold the thing we're hiding.
+                        print(f"{f}:{n}: matches pattern #{block.index(pat) + 1}")
+    print(f"scan_identifiers: {hits} hit(s)", file=sys.stderr)
+    return 1 if hits else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

knowledge_bundle_mcp-0.1.0/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.seayniclabs/knowledge",
+  "description": "Search, read and write your self-hosted Open Notebook knowledge base from an AI assistant.",
+  "repository": {
+    "url": "https://github.com/seayniclabs/knowledge",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "knowledge-bundle-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "KNOWLEDGE_OPEN_NOTEBOOK_URL",
+          "description": "Address of your Open Notebook server, e.g. https://notebook.example.com",
+          "isRequired": false
+        },
+        {
+          "name": "KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD",
+          "description": "Password for your Open Notebook server, if it has one",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM",
+          "description": "true (default): you approve each new note. false: the assistant may write on its own",
+          "isRequired": false
+        },
+        {
+          "name": "KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS",
+          "description": "Comma-separated notebook names the assistant may write to without asking",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

knowledge_bundle_mcp-0.1.0/src/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_bundle_mcp-0.1.0/src/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_bundle_mcp-0.1.0/src/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_bundle_mcp-0.1.0/src/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()]