agent-labbook 0.13.0__tar.gz

agent_labbook-0.13.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Binbin Shen
+
+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.

agent_labbook-0.13.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: agent-labbook
+Version: 0.13.0
+Summary: Notion auth and project binding for Codex, Claude Code, and other MCP clients.
+Author-email: Binbin Shen <binbinsh@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/binbinsh/agent-labbook
+Project-URL: Repository, https://github.com/binbinsh/agent-labbook
+Keywords: codex,claude-code,mcp,notion,oauth
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.26.0
+Dynamic: license-file
+
+# agent-labbook
+
+Agent Labbook is the Notion connection layer for Codex, Claude Code, and other MCP clients. It starts Notion auth, lets you choose which pages or data sources belong to a project, stores tokens and bindings locally in `.labbook/`, and returns the API context your agent needs to call Notion directly.
+
+Use it when you want to:
+
+- connect a repo to specific Notion pages or data sources for an agent
+- let an agent read or update project docs and data sources through the official Notion API
+- avoid building your own Notion auth wrapper for coding agents
+
+It is not a full Notion SDK. After setup, your agent should use the official Notion API directly.
+
+## Install
+
+Use Agent Labbook as a local MCP server for the current project.
+
+Requirements:
+
+- Python 3.10 or newer
+- `uv`
+- a Codex, Claude Code, or other MCP-capable client that can run a local MCP server
+
+Recommended setup:
+
+```bash
+codex mcp add labbook -- uvx agent-labbook mcp
+claude mcp add --scope project labbook -- uvx agent-labbook mcp
+```
+
+- or use the checked-in [`.mcp.json`](./.mcp.json) when the repository itself is the MCP source
+
+## Typical Flow
+
+1. Run `notion_status`.
+2. Run `notion_auth_browser`, or `notion_start_headless_auth` if connecting through SSH or another headless environment.
+3. Choose the Notion pages or data sources for this project.
+4. Run `notion_get_api_context`.
+5. Use the returned token, headers, and resource IDs with the official Notion API.
+
+## Hosted Backend
+
+The default backend is `https://labbook.superplanner.net`. It is privacy-friendly: it handles OAuth and token refresh without keeping your project tokens or Notion content in server-side storage. Long-lived tokens and bindings stay local in `.labbook/`.
+
+If you want to self-host it, see [`docs/self-host.md`](./docs/self-host.md).
+
+## Notes
+
+- `.labbook/` should never be committed
+- this repo handles auth and project binding, not general Notion API wrapping

agent_labbook-0.13.0/README.md

@@ -0,0 +1,49 @@
+# agent-labbook
+
+Agent Labbook is the Notion connection layer for Codex, Claude Code, and other MCP clients. It starts Notion auth, lets you choose which pages or data sources belong to a project, stores tokens and bindings locally in `.labbook/`, and returns the API context your agent needs to call Notion directly.
+
+Use it when you want to:
+
+- connect a repo to specific Notion pages or data sources for an agent
+- let an agent read or update project docs and data sources through the official Notion API
+- avoid building your own Notion auth wrapper for coding agents
+
+It is not a full Notion SDK. After setup, your agent should use the official Notion API directly.
+
+## Install
+
+Use Agent Labbook as a local MCP server for the current project.
+
+Requirements:
+
+- Python 3.10 or newer
+- `uv`
+- a Codex, Claude Code, or other MCP-capable client that can run a local MCP server
+
+Recommended setup:
+
+```bash
+codex mcp add labbook -- uvx agent-labbook mcp
+claude mcp add --scope project labbook -- uvx agent-labbook mcp
+```
+
+- or use the checked-in [`.mcp.json`](./.mcp.json) when the repository itself is the MCP source
+
+## Typical Flow
+
+1. Run `notion_status`.
+2. Run `notion_auth_browser`, or `notion_start_headless_auth` if connecting through SSH or another headless environment.
+3. Choose the Notion pages or data sources for this project.
+4. Run `notion_get_api_context`.
+5. Use the returned token, headers, and resource IDs with the official Notion API.
+
+## Hosted Backend
+
+The default backend is `https://labbook.superplanner.net`. It is privacy-friendly: it handles OAuth and token refresh without keeping your project tokens or Notion content in server-side storage. Long-lived tokens and bindings stay local in `.labbook/`.
+
+If you want to self-host it, see [`docs/self-host.md`](./docs/self-host.md).
+
+## Notes
+
+- `.labbook/` should never be committed
+- this repo handles auth and project binding, not general Notion API wrapping

agent_labbook-0.13.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-labbook"
+version = "0.13.0"
+description = "Notion auth and project binding for Codex, Claude Code, and other MCP clients."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Binbin Shen", email = "binbinsh@gmail.com" }
+]
+keywords = ["codex", "claude-code", "mcp", "notion", "oauth"]
+dependencies = [
+  "mcp>=1.26.0,<2",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/binbinsh/agent-labbook"
+Repository = "https://github.com/binbinsh/agent-labbook"
+
+[project.scripts]
+agent-labbook = "labbook.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_labbook-0.13.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_labbook-0.13.0/src/agent_labbook.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: agent-labbook
+Version: 0.13.0
+Summary: Notion auth and project binding for Codex, Claude Code, and other MCP clients.
+Author-email: Binbin Shen <binbinsh@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/binbinsh/agent-labbook
+Project-URL: Repository, https://github.com/binbinsh/agent-labbook
+Keywords: codex,claude-code,mcp,notion,oauth
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.26.0
+Dynamic: license-file
+
+# agent-labbook
+
+Agent Labbook is the Notion connection layer for Codex, Claude Code, and other MCP clients. It starts Notion auth, lets you choose which pages or data sources belong to a project, stores tokens and bindings locally in `.labbook/`, and returns the API context your agent needs to call Notion directly.
+
+Use it when you want to:
+
+- connect a repo to specific Notion pages or data sources for an agent
+- let an agent read or update project docs and data sources through the official Notion API
+- avoid building your own Notion auth wrapper for coding agents
+
+It is not a full Notion SDK. After setup, your agent should use the official Notion API directly.
+
+## Install
+
+Use Agent Labbook as a local MCP server for the current project.
+
+Requirements:
+
+- Python 3.10 or newer
+- `uv`
+- a Codex, Claude Code, or other MCP-capable client that can run a local MCP server
+
+Recommended setup:
+
+```bash
+codex mcp add labbook -- uvx agent-labbook mcp
+claude mcp add --scope project labbook -- uvx agent-labbook mcp
+```
+
+- or use the checked-in [`.mcp.json`](./.mcp.json) when the repository itself is the MCP source
+
+## Typical Flow
+
+1. Run `notion_status`.
+2. Run `notion_auth_browser`, or `notion_start_headless_auth` if connecting through SSH or another headless environment.
+3. Choose the Notion pages or data sources for this project.
+4. Run `notion_get_api_context`.
+5. Use the returned token, headers, and resource IDs with the official Notion API.
+
+## Hosted Backend
+
+The default backend is `https://labbook.superplanner.net`. It is privacy-friendly: it handles OAuth and token refresh without keeping your project tokens or Notion content in server-side storage. Long-lived tokens and bindings stay local in `.labbook/`.
+
+If you want to self-host it, see [`docs/self-host.md`](./docs/self-host.md).
+
+## Notes
+
+- `.labbook/` should never be committed
+- this repo handles auth and project binding, not general Notion API wrapping

agent_labbook-0.13.0/src/agent_labbook.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/agent_labbook.egg-info/PKG-INFO
+src/agent_labbook.egg-info/SOURCES.txt
+src/agent_labbook.egg-info/dependency_links.txt
+src/agent_labbook.egg-info/entry_points.txt
+src/agent_labbook.egg-info/requires.txt
+src/agent_labbook.egg-info/top_level.txt
+src/labbook/__init__.py
+src/labbook/__main__.py
+src/labbook/cli.py
+src/labbook/mcp_server.py
+src/labbook/notion_api.py
+src/labbook/service.py
+src/labbook/state.py
+tests/test_cli.py
+tests/test_mcp_server.py

agent_labbook-0.13.0/src/agent_labbook.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_labbook-0.13.0/src/agent_labbook.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-labbook = labbook.cli:main

agent_labbook-0.13.0/src/agent_labbook.egg-info/requires.txt

@@ -0,0 +1 @@
+mcp<2,>=1.26.0

agent_labbook-0.13.0/src/agent_labbook.egg-info/top_level.txt

@@ -0,0 +1 @@
+labbook

agent_labbook-0.13.0/src/labbook/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.13.0"

agent_labbook-0.13.0/src/labbook/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_labbook-0.13.0/src/labbook/cli.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import sys
+from importlib.metadata import PackageNotFoundError, version as package_version
+from typing import Any
+from urllib import error, request
+
+from . import __version__
+from .service import status
+from .state import (
+    DEFAULT_BACKEND_URL,
+    bindings_path,
+    effective_backend_url,
+    load_project_bindings,
+    load_project_session,
+    pending_auth_path,
+    resolve_project_root,
+    session_path,
+)
+
+
+def _json_dump(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n")
+
+
+def _installed_mcp_sdk_version() -> str | None:
+    try:
+        return package_version("mcp")
+    except PackageNotFoundError:
+        return None
+
+
+def _probe_backend_health(backend_url: str) -> dict[str, Any]:
+    req = request.Request(
+        f"{backend_url}/health",
+        headers={"Accept": "application/json"},
+        method="GET",
+    )
+    try:
+        with request.urlopen(req, timeout=10) as response:
+            raw = response.read().decode("utf-8")
+            status_code = response.status
+    except error.HTTPError as exc:
+        raw = exc.read().decode("utf-8", errors="replace")
+        return {
+            "ok": False,
+            "status_code": exc.code,
+            "error": raw or exc.reason,
+        }
+    except error.URLError as exc:
+        return {
+            "ok": False,
+            "error": str(exc.reason),
+        }
+
+    try:
+        decoded = json.loads(raw)
+    except json.JSONDecodeError:
+        decoded = {"raw": raw}
+    return {
+        "ok": True,
+        "status_code": status_code,
+        "payload": decoded,
+    }
+
+
+def _mcp_server_config(*, server_name: str) -> dict[str, Any]:
+    return {
+        "mcpServers": {
+            server_name: {
+                "command": "uvx",
+                "args": ["agent-labbook", "mcp"],
+            }
+        }
+    }
+
+
+def _doctor_command(args: argparse.Namespace) -> int:
+    project_root = resolve_project_root(args.project_root)
+    backend_url = effective_backend_url()
+    pending_path = pending_auth_path(project_root)
+    payload: dict[str, Any] = {
+        "version": __version__,
+        "python": {
+            "executable": sys.executable,
+            "implementation": platform.python_implementation(),
+            "version": platform.python_version(),
+        },
+        "project_root": str(project_root),
+        "backend_url": backend_url,
+        "backend_url_overridden": backend_url != DEFAULT_BACKEND_URL,
+        "state": {
+            "session_path": str(session_path(project_root)),
+            "session_exists": load_project_session(project_root) is not None,
+            "bindings_path": str(bindings_path(project_root)),
+            "bindings_exists": load_project_bindings(project_root) is not None,
+            "pending_auth_path": str(pending_path),
+            "pending_auth_exists": pending_path.exists(),
+        },
+        "notion_status": status(project_root),
+        "mcp": {
+            "install_surface": "uvx agent-labbook mcp",
+            "sdk": "modelcontextprotocol/python-sdk",
+            "sdk_version": _installed_mcp_sdk_version(),
+            "transport": "stdio",
+            "wire_protocol": "content-length",
+        },
+    }
+    if args.probe_backend:
+        payload["backend_probe"] = _probe_backend_health(backend_url)
+    _json_dump(payload)
+    return 0
+
+
+def _print_mcp_config_command(args: argparse.Namespace) -> int:
+    payload = _mcp_server_config(server_name=args.server_name)
+    _json_dump(payload)
+    return 0
+
+
+def _run_mcp_command() -> int:
+    try:
+        from .mcp_server import main as mcp_main
+    except ModuleNotFoundError as exc:
+        if exc.name == "mcp":
+            raise RuntimeError(
+                "The Python 'mcp' package is not installed. "
+                "Use 'uvx agent-labbook mcp'."
+            ) from exc
+        raise
+
+    mcp_main()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-labbook",
+        description="Agent Labbook CLI and MCP launcher.",
+    )
+    parser.set_defaults(func=None)
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    mcp_parser = subparsers.add_parser("mcp", help="Run the MCP stdio server.")
+    mcp_parser.set_defaults(func=lambda _args: _run_mcp_command())
+
+    doctor_parser = subparsers.add_parser("doctor", help="Inspect local Agent Labbook state.")
+    doctor_parser.add_argument("--project-root", default=".", help="Project root to inspect. Defaults to the current directory.")
+    doctor_parser.add_argument(
+        "--probe-backend",
+        action="store_true",
+        help="Also query the configured backend /health endpoint.",
+    )
+    doctor_parser.set_defaults(func=_doctor_command)
+
+    config_parser = subparsers.add_parser(
+        "print-mcp-config",
+        help="Print a reusable uvx-based MCP server config snippet.",
+    )
+    config_parser.add_argument(
+        "--server-name",
+        default="labbook",
+        help="Name to use under mcpServers.",
+    )
+    config_parser.set_defaults(func=_print_mcp_config_command)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.func is None:
+        parser.print_help(sys.stderr)
+        return 1
+    try:
+        return int(args.func(args) or 0)
+    except RuntimeError as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())