kb0-mcp 0.1.0__tar.gz

kb0_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

kb0_mcp-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

kb0_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: kb0-mcp
+Version: 0.1.0
+Summary: Python client for kb0 — the knowledge base layer for AI agents (MCP, markdown, git).
+Project-URL: Homepage, https://kb0.dev
+Project-URL: Repository, https://github.com/vitorchristoval/kb0
+Project-URL: Documentation, https://github.com/vitorchristoval/kb0/tree/main/docs
+Author: Vitor Christoval
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agents,knowledge-base,markdown,mcp,rag,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# kb0 (Python client)
+
+Native Python client for [**kb0**](https://github.com/vitorchristoval/kb0) — the knowledge base layer for AI agents. Markdown-first, git-backed, MCP-native.
+
+This package hides the MCP plumbing and gives you a clean async `VaultClient`.
+
+```bash
+pip install kb0-mcp
+```
+
+> The PyPI package is `kb0-mcp`; you still `import kb0` in code.
+>
+> **Requires the kb0 server.** This is a client — it spawns the `kb0` binary as a
+> subprocess. Install it once with Node: `npm install -g kb0-mcp`, then `kb0 init my-vault`.
+
+## Quickstart
+
+```python
+import asyncio
+from kb0 import VaultClient
+
+async def main():
+    async with VaultClient(vault="./my-vault", agent="my-bot") as kb:
+        # write a note (author, id, timestamps set by the server)
+        res = await kb.write(
+            "notes/auth.md",
+            title="Auth: we chose JWT",
+            content="Short-lived access + refresh tokens. See [[notes/security.md]].",
+            tags=["security"],
+        )
+        print("created", res["path"], "hash", res["hash"])
+
+        # search (hybrid by default)
+        hits = await kb.search("authentication design")
+        for r in hits["results"]:
+            print(r["score"], r["title"], r["path"])
+
+        # read + update with optimistic locking
+        note = await kb.read("notes/auth.md")
+        await kb.update(
+            "notes/auth.md",
+            content=note["content"] + "\n\nUpdate: rotating keys monthly.",
+            expected_hash=note["hash"],
+        )
+
+asyncio.run(main())
+```
+
+## Configuration
+
+`VaultClient` passes everything through to `kb0 serve`:
+
+```python
+VaultClient(
+    vault="./my-vault",       # vault directory
+    agent="my-bot",           # agent identity (provenance + ACL)
+    openai_api_key="sk-...",  # optional — enables semantic search
+    strict=False,             # require .vault-policy.yaml if True
+    command="kb0",            # override the binary path if needed
+    env={"KB0_EMBEDDING_MODEL": "text-embedding-3-large"},
+)
+```
+
+## API
+
+All methods are async and return plain dicts (the tool's structured output).
+
+| Method | kb0 tool |
+|---|---|
+| `await kb.write(path, *, title, content, status="draft", tags=None)` | `vault.write` |
+| `await kb.read(path)` | `vault.read` |
+| `await kb.update(path, *, content, expected_hash, title=None, status=None, tags=None)` | `vault.update` |
+| `await kb.delete(path)` | `vault.delete` |
+| `await kb.search(query, *, mode="hybrid", ranking="rrf", limit=10, filters=None)` | `vault.search` |
+| `await kb.list(*, prefix=None, tag=None, status=None, limit=50)` | `vault.list` |
+| `await kb.recent(limit=10)` | `vault.recent` |
+| `await kb.backlinks(path)` | `vault.backlinks` |
+| `await kb.links(path)` | `vault.links` |
+| `await kb.status()` | `vault.status` |
+
+## Errors
+
+Failures raise typed exceptions you can catch:
+
+```python
+from kb0 import KbConflictError, KbACLDeniedError, KbNotFoundError
+
+try:
+    await kb.update("notes/x.md", content="...", expected_hash=stale_hash)
+except KbConflictError:
+    note = await kb.read("notes/x.md")   # re-read, get the current hash, retry
+```
+
+`KbError` is the base class; `KbNotFoundError`, `KbConflictError`,
+`KbValidationError`, and `KbACLDeniedError` are its subclasses.
+
+## Why a subprocess?
+
+kb0 is an MCP server. The Python client launches `kb0 serve` over stdio and speaks
+MCP to it — the same protocol Claude Desktop uses. Your vault stays a local folder
+of markdown under git; this client is just an ergonomic way for Python agents to
+talk to it. See the [main repo](https://github.com/vitorchristoval/kb0) for the
+architecture.
+
+## License
+
+Apache 2.0.

kb0_mcp-0.1.0/README.md

@@ -0,0 +1,107 @@
+# kb0 (Python client)
+
+Native Python client for [**kb0**](https://github.com/vitorchristoval/kb0) — the knowledge base layer for AI agents. Markdown-first, git-backed, MCP-native.
+
+This package hides the MCP plumbing and gives you a clean async `VaultClient`.
+
+```bash
+pip install kb0-mcp
+```
+
+> The PyPI package is `kb0-mcp`; you still `import kb0` in code.
+>
+> **Requires the kb0 server.** This is a client — it spawns the `kb0` binary as a
+> subprocess. Install it once with Node: `npm install -g kb0-mcp`, then `kb0 init my-vault`.
+
+## Quickstart
+
+```python
+import asyncio
+from kb0 import VaultClient
+
+async def main():
+    async with VaultClient(vault="./my-vault", agent="my-bot") as kb:
+        # write a note (author, id, timestamps set by the server)
+        res = await kb.write(
+            "notes/auth.md",
+            title="Auth: we chose JWT",
+            content="Short-lived access + refresh tokens. See [[notes/security.md]].",
+            tags=["security"],
+        )
+        print("created", res["path"], "hash", res["hash"])
+
+        # search (hybrid by default)
+        hits = await kb.search("authentication design")
+        for r in hits["results"]:
+            print(r["score"], r["title"], r["path"])
+
+        # read + update with optimistic locking
+        note = await kb.read("notes/auth.md")
+        await kb.update(
+            "notes/auth.md",
+            content=note["content"] + "\n\nUpdate: rotating keys monthly.",
+            expected_hash=note["hash"],
+        )
+
+asyncio.run(main())
+```
+
+## Configuration
+
+`VaultClient` passes everything through to `kb0 serve`:
+
+```python
+VaultClient(
+    vault="./my-vault",       # vault directory
+    agent="my-bot",           # agent identity (provenance + ACL)
+    openai_api_key="sk-...",  # optional — enables semantic search
+    strict=False,             # require .vault-policy.yaml if True
+    command="kb0",            # override the binary path if needed
+    env={"KB0_EMBEDDING_MODEL": "text-embedding-3-large"},
+)
+```
+
+## API
+
+All methods are async and return plain dicts (the tool's structured output).
+
+| Method | kb0 tool |
+|---|---|
+| `await kb.write(path, *, title, content, status="draft", tags=None)` | `vault.write` |
+| `await kb.read(path)` | `vault.read` |
+| `await kb.update(path, *, content, expected_hash, title=None, status=None, tags=None)` | `vault.update` |
+| `await kb.delete(path)` | `vault.delete` |
+| `await kb.search(query, *, mode="hybrid", ranking="rrf", limit=10, filters=None)` | `vault.search` |
+| `await kb.list(*, prefix=None, tag=None, status=None, limit=50)` | `vault.list` |
+| `await kb.recent(limit=10)` | `vault.recent` |
+| `await kb.backlinks(path)` | `vault.backlinks` |
+| `await kb.links(path)` | `vault.links` |
+| `await kb.status()` | `vault.status` |
+
+## Errors
+
+Failures raise typed exceptions you can catch:
+
+```python
+from kb0 import KbConflictError, KbACLDeniedError, KbNotFoundError
+
+try:
+    await kb.update("notes/x.md", content="...", expected_hash=stale_hash)
+except KbConflictError:
+    note = await kb.read("notes/x.md")   # re-read, get the current hash, retry
+```
+
+`KbError` is the base class; `KbNotFoundError`, `KbConflictError`,
+`KbValidationError`, and `KbACLDeniedError` are its subclasses.
+
+## Why a subprocess?
+
+kb0 is an MCP server. The Python client launches `kb0 serve` over stdio and speaks
+MCP to it — the same protocol Claude Desktop uses. Your vault stays a local folder
+of markdown under git; this client is just an ergonomic way for Python agents to
+talk to it. See the [main repo](https://github.com/vitorchristoval/kb0) for the
+architecture.
+
+## License
+
+Apache 2.0.

kb0_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kb0-mcp"
+version = "0.1.0"
+description = "Python client for kb0 — the knowledge base layer for AI agents (MCP, markdown, git)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Vitor Christoval" }]
+keywords = ["mcp", "ai-agents", "knowledge-base", "rag", "markdown", "vault"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = ["mcp>=1.0.0"]
+
+[project.urls]
+Homepage = "https://kb0.dev"
+Repository = "https://github.com/vitorchristoval/kb0"
+Documentation = "https://github.com/vitorchristoval/kb0/tree/main/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kb0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kb0_mcp-0.1.0/src/kb0/__init__.py

@@ -0,0 +1,21 @@
+"""kb0 — Python client for the kb0 knowledge base layer for AI agents."""
+
+from .client import VaultClient
+from .errors import (
+    KbACLDeniedError,
+    KbConflictError,
+    KbError,
+    KbNotFoundError,
+    KbValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "VaultClient",
+    "KbError",
+    "KbNotFoundError",
+    "KbConflictError",
+    "KbValidationError",
+    "KbACLDeniedError",
+]

kb0_mcp-0.1.0/src/kb0/client.py

@@ -0,0 +1,188 @@
+"""Async Python client for a kb0 vault over MCP (stdio)."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from .errors import error_from_text
+
+
+def _text_of(result: Any) -> str:
+    parts: list[str] = []
+    for block in getattr(result, "content", None) or []:
+        text = getattr(block, "text", None)
+        if text:
+            parts.append(text)
+    return "\n".join(parts)
+
+
+def _unwrap(result: Any) -> Any:
+    """Turn an MCP CallToolResult into a plain dict, or raise a typed KbError."""
+    if getattr(result, "isError", False):
+        raise error_from_text(_text_of(result))
+
+    structured = getattr(result, "structuredContent", None)
+    if structured is not None:
+        return structured
+
+    text = _text_of(result)
+    try:
+        return json.loads(text)
+    except (ValueError, TypeError):
+        return {"text": text}
+
+
+class VaultClient:
+    """A thin client over the kb0 MCP server.
+
+    Spawns ``kb0 serve`` as a subprocess and exposes the 10 vault tools as
+    native async methods. Use as an async context manager::
+
+        async with VaultClient(vault="./my-vault", agent="my-bot") as kb:
+            await kb.write("notes/idea.md", title="Idea", content="...")
+            hits = await kb.search("auth design")
+    """
+
+    def __init__(
+        self,
+        vault: str,
+        agent: str,
+        *,
+        command: str = "kb0",
+        env: dict[str, str] | None = None,
+        openai_api_key: str | None = None,
+        strict: bool = False,
+    ) -> None:
+        self.vault = str(vault)
+        self.agent = agent
+        self.command = command
+        self._extra_env = env
+        self._openai_api_key = openai_api_key
+        self._strict = strict
+        self._session: Any = None
+        self._stack: Any = None
+
+    async def __aenter__(self) -> "VaultClient":
+        # Imported lazily so the package can be imported (and unit-tested with a
+        # mock session) without the mcp SDK installed.
+        from contextlib import AsyncExitStack
+
+        from mcp import ClientSession, StdioServerParameters
+        from mcp.client.stdio import stdio_client
+
+        env = dict(os.environ)
+        if self._extra_env:
+            env.update(self._extra_env)
+        if self._openai_api_key:
+            env["OPENAI_API_KEY"] = self._openai_api_key
+
+        args = ["serve", "--agent", self.agent, "--vault", self.vault]
+        if self._strict:
+            args.append("--strict")
+
+        params = StdioServerParameters(command=self.command, args=args, env=env)
+
+        self._stack = AsyncExitStack()
+        read, write = await self._stack.enter_async_context(stdio_client(params))
+        session = await self._stack.enter_async_context(ClientSession(read, write))
+        await session.initialize()
+        self._session = session
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        if self._stack is not None:
+            await self._stack.aclose()
+        self._stack = None
+        self._session = None
+
+    async def _call(self, name: str, arguments: dict[str, Any]) -> Any:
+        if self._session is None:
+            raise RuntimeError("VaultClient is not connected — use 'async with VaultClient(...)'")
+        result = await self._session.call_tool(name, arguments)
+        return _unwrap(result)
+
+    # ── tools ──────────────────────────────────────────────────────────────────
+
+    async def write(
+        self,
+        path: str,
+        *,
+        title: str,
+        content: str,
+        status: str = "draft",
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        return await self._call(
+            "vault.write",
+            {"path": path, "title": title, "content": content, "status": status, "tags": tags or []},
+        )
+
+    async def read(self, path: str) -> dict[str, Any]:
+        return await self._call("vault.read", {"path": path})
+
+    async def update(
+        self,
+        path: str,
+        *,
+        content: str,
+        expected_hash: str,
+        title: str | None = None,
+        status: str | None = None,
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        args: dict[str, Any] = {"path": path, "content": content, "expectedHash": expected_hash}
+        if title is not None:
+            args["title"] = title
+        if status is not None:
+            args["status"] = status
+        if tags is not None:
+            args["tags"] = tags
+        return await self._call("vault.update", args)
+
+    async def delete(self, path: str) -> dict[str, Any]:
+        return await self._call("vault.delete", {"path": path})
+
+    async def search(
+        self,
+        query: str,
+        *,
+        mode: str = "hybrid",
+        ranking: str = "rrf",
+        limit: int = 10,
+        filters: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        args: dict[str, Any] = {"query": query, "mode": mode, "ranking": ranking, "limit": limit}
+        if filters is not None:
+            args["filters"] = filters
+        return await self._call("vault.search", args)
+
+    async def list(
+        self,
+        *,
+        prefix: str | None = None,
+        tag: str | None = None,
+        status: str | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        args: dict[str, Any] = {"limit": limit}
+        if prefix is not None:
+            args["prefix"] = prefix
+        if tag is not None:
+            args["tag"] = tag
+        if status is not None:
+            args["status"] = status
+        return await self._call("vault.list", args)
+
+    async def recent(self, limit: int = 10) -> dict[str, Any]:
+        return await self._call("vault.recent", {"limit": limit})
+
+    async def backlinks(self, path: str) -> dict[str, Any]:
+        return await self._call("vault.backlinks", {"path": path})
+
+    async def links(self, path: str) -> dict[str, Any]:
+        return await self._call("vault.links", {"path": path})
+
+    async def status(self) -> dict[str, Any]:
+        return await self._call("vault.status", {})

kb0_mcp-0.1.0/src/kb0/errors.py

@@ -0,0 +1,49 @@
+"""Typed errors mirroring kb0's structured error codes."""
+
+from __future__ import annotations
+
+
+class KbError(Exception):
+    """Base class for all kb0 errors returned by the vault."""
+
+    code = "ERROR"
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class KbNotFoundError(KbError):
+    code = "NOT_FOUND"
+
+
+class KbConflictError(KbError):
+    """Raised when vault.update is called with a stale expected_hash."""
+
+    code = "CONFLICT"
+
+
+class KbValidationError(KbError):
+    code = "VALIDATION"
+
+
+class KbACLDeniedError(KbError):
+    code = "ACL_DENIED"
+
+
+def error_from_text(text: str) -> KbError:
+    """Map a kb0 error message back to a typed exception.
+
+    kb0 formats each error code with a stable prefix, so matching on it is
+    reliable (both sides live in the same project).
+    """
+    stripped = text.strip()
+    if stripped.startswith("Not found"):
+        return KbNotFoundError(text)
+    if stripped.startswith("Conflict"):
+        return KbConflictError(text)
+    if stripped.startswith("Permission denied"):
+        return KbACLDeniedError(text)
+    if stripped.startswith("Validation"):
+        return KbValidationError(text)
+    return KbError(text)

kb0_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,141 @@
+"""Unit tests for VaultClient — uses a fake MCP session, no subprocess needed."""
+
+import unittest
+from types import SimpleNamespace
+
+from kb0 import (
+    KbACLDeniedError,
+    KbConflictError,
+    KbNotFoundError,
+    VaultClient,
+)
+from kb0.errors import error_from_text
+
+
+def fake_result(structured=None, text=None, is_error=False):
+    content = [SimpleNamespace(text=text)] if text is not None else []
+    return SimpleNamespace(structuredContent=structured, content=content, isError=is_error)
+
+
+class FakeSession:
+    """Records tool calls and returns a queued result per call."""
+
+    def __init__(self):
+        self.calls = []
+        self.results = []
+
+    def queue(self, result):
+        self.results.append(result)
+
+    async def call_tool(self, name, arguments):
+        self.calls.append((name, arguments))
+        return self.results.pop(0)
+
+
+def connected_client():
+    client = VaultClient(vault="/tmp/vault", agent="test-agent")
+    client._session = FakeSession()
+    return client
+
+
+class WriteTests(unittest.IsolatedAsyncioTestCase):
+    async def test_write_sends_expected_arguments(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(structured={"path": "n.md", "hash": "a" * 64, "id": "uuid"}))
+
+        out = await kb.write("n.md", title="N", content="body", tags=["x"])
+
+        name, args = kb._session.calls[0]
+        self.assertEqual(name, "vault.write")
+        self.assertEqual(args["path"], "n.md")
+        self.assertEqual(args["title"], "N")
+        self.assertEqual(args["tags"], ["x"])
+        self.assertEqual(out["id"], "uuid")
+
+    async def test_write_defaults_status_and_tags(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(structured={}))
+        await kb.write("n.md", title="N", content="c")
+        _, args = kb._session.calls[0]
+        self.assertEqual(args["status"], "draft")
+        self.assertEqual(args["tags"], [])
+
+
+class UpdateTests(unittest.IsolatedAsyncioTestCase):
+    async def test_update_maps_expected_hash_to_camelcase(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(structured={"path": "n.md", "hash": "b" * 64}))
+        await kb.update("n.md", content="v2", expected_hash="a" * 64)
+        _, args = kb._session.calls[0]
+        self.assertEqual(args["expectedHash"], "a" * 64)
+        self.assertNotIn("expected_hash", args)
+
+    async def test_update_omits_unset_optional_fields(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(structured={}))
+        await kb.update("n.md", content="v2", expected_hash="h")
+        _, args = kb._session.calls[0]
+        self.assertNotIn("title", args)
+        self.assertNotIn("status", args)
+
+
+class SearchListTests(unittest.IsolatedAsyncioTestCase):
+    async def test_search_passes_mode_and_limit(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(structured={"results": [], "warnings": []}))
+        await kb.search("query", mode="keyword", limit=5)
+        _, args = kb._session.calls[0]
+        self.assertEqual(args["mode"], "keyword")
+        self.assertEqual(args["limit"], 5)
+
+    async def test_list_omits_unset_filters(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(structured={"notes": [], "total": 0}))
+        await kb.list(tag="work")
+        _, args = kb._session.calls[0]
+        self.assertEqual(args["tag"], "work")
+        self.assertNotIn("prefix", args)
+
+
+class ErrorTests(unittest.IsolatedAsyncioTestCase):
+    async def test_not_found_raises_typed_error(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(text="Not found: `ghost.md`", is_error=True))
+        with self.assertRaises(KbNotFoundError):
+            await kb.read("ghost.md")
+
+    async def test_conflict_raises_typed_error(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(text="Conflict at `n.md`: ...", is_error=True))
+        with self.assertRaises(KbConflictError):
+            await kb.update("n.md", content="x", expected_hash="wrong")
+
+    async def test_acl_denied_raises_typed_error(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(text="Permission denied: not allowed", is_error=True))
+        with self.assertRaises(KbACLDeniedError):
+            await kb.write("secret.md", title="T", content="c")
+
+    async def test_call_without_connection_raises(self):
+        kb = VaultClient(vault="/tmp/v", agent="a")
+        with self.assertRaises(RuntimeError):
+            await kb.read("x.md")
+
+
+class UnwrapTests(unittest.IsolatedAsyncioTestCase):
+    async def test_falls_back_to_json_text_when_no_structured(self):
+        kb = connected_client()
+        kb._session.queue(fake_result(text='{"ok": true}'))
+        out = await kb.status()
+        self.assertEqual(out, {"ok": True})
+
+
+class ErrorMappingTests(unittest.TestCase):
+    def test_prefixes_map_to_codes(self):
+        self.assertIsInstance(error_from_text("Not found: x"), KbNotFoundError)
+        self.assertIsInstance(error_from_text("Conflict at x"), KbConflictError)
+        self.assertIsInstance(error_from_text("Permission denied: x"), KbACLDeniedError)
+
+
+if __name__ == "__main__":
+    unittest.main()