Metadata-Version: 2.5
Name: knowledge-bundle-mcp
Version: 0.2.1
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,skills
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 -->

**Made by [Seaynic Labs](https://seayniclabs.com).** Need tools like this built around your own systems? [We do that](https://seayniclabs.com/#business).

Knowledge lets an AI assistant search, read and write the notes in your self-hosted [Open Notebook](https://github.com/lfnovo/open-notebook), and comes with skills that teach it to do that work well: meeting notes, decision records, weekly reviews and source-backed research.

It is a **bundle**: tools, skills and instructions in one install. The tools are 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.

<!-- security-card:start (generated by scripts/security_card.py) -->
| Security card | |
|---|---|
| Network | Only the Open Notebook server you configure (KNOWLEDGE_OPEN_NOTEBOOK_URL). Open Notebook fetches the links you add, not Knowledge. Nothing else, no telemetry. |
| Files | Reads its config file (~/.config/knowledge/config.toml). Reads a local file only when you name it in open_notebook_add_source, and only after you approve it (the file goes to your Open Notebook server). Writes one local approval log (~/.local/state/knowledge/approvals.jsonl). |
| Secrets | API keys and passwords come from your environment or config file. They are never tool arguments and never returned to the model. |
| Read-only tools | 6: `open_notebook_notebooks`, `open_notebook_search`, `open_notebook_notes`, `open_notebook_note_get`, `open_notebook_source_get`, `knowledge_modules` |
| Needs your approval | `open_notebook_note_create`, `open_notebook_add_source`: you approve each write in your app, or pre-approve notebooks in settings (not for local files). The AI cannot approve for you. |
| Startup cost | about 4,600 tokens (8 tools, 7 skill prompts) |
| Changes | Tool descriptions are locked by hash (`tool-manifest.lock.json`); CI fails if they change silently. |
<!-- security-card:end -->

## Skills

| Skill | What it does | Source |
|---|---|---|
| `getting-started` | Checks the settings, runs the first calls, explains approvals and errors | Seaynic Labs (MIT) |
| `research-with-sources` | Answers from your notebooks, cites each claim, flags sources that disagree | Seaynic Labs (MIT) |
| `weekly-review` | Done, open and next-week items from the notes you changed this week | Seaynic Labs (MIT) |
| `meeting-notes` | Structured meeting notes as a Markdown file, optionally saved to a notebook | Seaynic Labs (MIT) |
| `decision-record` | A numbered Architecture Decision Record in a `Decisions/` folder | Seaynic Labs (MIT) |
| `icm-architect` | Organises a knowledge base as a folder structure that agents can walk | Jake Van Clief (MIT), [credits](CREDITS.md) |
| `obsidian-markdown` | Obsidian-flavoured Markdown: wikilinks, callouts, properties | Steph Ango (MIT), [credits](CREDITS.md) |

Skills reach every app. Claude Code and other skill-aware apps read the `skills/` folder. Any MCP app gets the same text as prompts: `getting-started`, for example, is the prompt named `getting-started`. Third-party skills keep their own license files. See [CREDITS.md](CREDITS.md).

## 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
```

**Pinned install.** For a fixed setup, pin the exact version. The plugin manifest pins it the same way:

```bash
uvx knowledge-bundle-mcp==0.2.1 --version
```

**As a Claude Code plugin.** One install gives you the MCP server and the skills. This needs the `seayniclabs/plugins` marketplace, which is published with the release:

```
/plugin marketplace add seayniclabs/plugins
/plugin install knowledge@seayniclabs
```

The plugin still needs your Open Notebook address in its settings. The plugin file is [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json).

## First five minutes

1. Set `KNOWLEDGE_OPEN_NOTEBOOK_URL` to your server's address (step 2 below shows where).
2. Run the check. It prints `ok` or `FIX` for each item and exits 0 when everything is ready:

   ```bash
   knowledge-bundle-mcp --doctor
   ```

3. Start your assistant and ask it to list your notebooks. It calls `open_notebook_notebooks` and shows you the names.
4. Ask it to search a word you know is in one of your notes. It calls `open_notebook_search`.
5. Ask it to save a note. It shows a preview first, then asks you to approve the save in your app.

## 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 and link. `false` lets the assistant save them on its own. Local files always need your approval. |
| `KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS` | open_notebook | Optional. Comma-separated notebook names the assistant may save links and notes to without asking, e.g. `Research,Inbox` |
| `KNOWLEDGE_APPROVAL_LOG` | any | Optional. Where the approval log is written. Default: `~/.local/state/knowledge/approvals.jsonl` |
| `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-bundle-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.

## Try these

Paste any of these into your assistant once Knowledge passes `--doctor`:

1. "List my notebooks and tell me which one changed most recently."
2. "Search my notebooks for what I wrote about the Q3 budget, and cite each note."
3. "Write a weekly review of the notes I changed this week, using the weekly-review skill."
4. "Make an ADR for choosing SQLite over Postgres for the prototype, with the alternatives table filled in."
5. "Save this link to my Research notebook: https://example.com/article. Show me the preview first."

## Tools

| Tool | What it returns |
|---|---|
| `knowledge_modules` | Which modules are on, which settings are missing, the skills, and the publisher. 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, processing status |
| `open_notebook_note_create` | Saves a note after you approve it. Without `confirm=true` it only returns a preview. |
| `open_notebook_add_source` | Adds a web link, or a local file you name, as a source. Preview first; you approve it. Processed in the background. |

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` and `open_notebook_add_source` change your notebooks, 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, the title and the full text or link. The assistant can't answer that question for you.
- A local file is read only after you name it, and it is uploaded only after you approve its full path and size. Files named like credential stores (`.env`, `.netrc`, private keys, `*.pem`, `*.key`) and files in `~/.ssh`, `~/.aws` or `~/.gnupg` are refused.
- 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`. Local files are never pre-approved.
- Before anything is written or sent, 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
python3 scripts/check_skills.py
.venv/bin/python scripts/tool_lock.py --check
.venv/bin/python scripts/security_card.py --check
```

`scripts/tool_lock.py` (without `--check`) rewrites `tool-manifest.lock.json` after a deliberate change to a tool, prompt or instruction. Add a changelog line in the same commit.

## Security

Report a vulnerability privately through GitHub (Security tab, "Report a vulnerability"). See [SECURITY.md](SECURITY.md). Every approval, decline and refusal is logged locally in `~/.local/state/knowledge/approvals.jsonl`: titles, notebook names and sizes, never the text. Set `KNOWLEDGE_APPROVAL_LOG` to move it.

## License

MIT. Published by Seaynic Labs. Third-party skills are credited in [CREDITS.md](CREDITS.md) and keep their own licenses.

---

**Built by [Seaynic Labs](https://seayniclabs.com).** We build tools like this around a business's own systems: local-first, with a person approving every change. [See custom integrations](https://seayniclabs.com/#business).
