Metadata-Version: 2.4
Name: agent-labbook
Version: 0.14.7
Summary: Notion auth and project binding for Codex, Claude Code, and other MCP clients.
Author-email: Binbin Shen <binbinsh@gmail.com>
License-Expression: 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: 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: keyring<26,>=25.6.0
Requires-Dist: mcp<2,>=1.26.0
Requires-Dist: notion-access-broker<0.2,>=0.1.1
Dynamic: license-file

# Agent Labbook

Agent Labbook is the Notion connection layer for Codex, Claude Code, and other MCP clients. It handles Notion auth for a project, lets you choose which pages or data sources belong to that project, stores bindings in `.labbook/`, keeps long-lived tokens in a shared credential provider, and returns the API context your agent needs to call Notion directly.

It is not a full Notion SDK. After setup, your agent should use the official Notion API directly.

## Main Features

- Connect a repo to specific Notion pages or data sources for an agent.
- Reuse saved Notion credentials across projects.
- Bind only the pages or data sources a project should use.
- Return access tokens, headers, and bound resource IDs for the official Notion API.
- Work with Codex, Claude Code, and other MCP-capable clients.

## Install

Requirements:
- Python 3.10 or newer
- `uv`
- a Codex, Claude Code, or another MCP-capable client

Recommended:

```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 this repo is the MCP source.

## Use

1. Read `labbook://agent-labbook/project/status` or run `notion_status`.
2. Reuse a saved credential when available, or start auth with `notion_auth_browser` or `notion_start_headless_auth`.
3. Choose the pages or data sources that belong to the project, then finish the handoff with `notion_status` and `notion_finalize_pending_auth` when needed.
4. Read `labbook://agent-labbook/project/bindings` or run `notion_list_bindings` to inspect the bound roots.
5. Run `notion_get_api_context` and use the returned token, headers, and resource IDs with the official Notion API.

If your content already exists as markdown, prefer Notion's markdown content APIs:

- `POST /v1/pages` with `markdown`
- `GET /v1/pages/{page_id}/markdown`
- `PATCH /v1/pages/{page_id}/markdown`

Reference: `https://developers.notion.com/guides/data-apis/working-with-markdown-content`

## Notes

- `.labbook/` should never be committed.
- This repo handles auth and project binding, not general Notion API wrapping.
- For self-hosting, see [`docs/self-host.md`](./docs/self-host.md).
- For versioning details, see [`docs/versioning.md`](./docs/versioning.md).
