# Notion Personal MCP

把你自己的 **Notion 个人 AI 对话**接入 Codex 等支持本地 STDIO MCP 的客户端。支持新建任务、断线后按编号取回结果、同一对话追问，以及完整保存长文和源码。

**当前版本：0.4.0b1，公开测试版。** 基于已实际使用的 0.3.1 适配器整理。每位使用者配置自己的 Notion 账号与登录会话；项目不提供共享账号、Cookie 或模型额度。

这是非官方的本地适配器，使用 Notion 网页私有接口。不是 Notion 官方 MCP，也不是 Anthropic API。模型由你在 Notion 里明确选择后捕获的请求决定；账号需能正常使用该模型。Opus 5.5 是已有使用场景，不承诺所有账号都有此模型，也不保证未来计费或接口不变。

## 能做什么

| 工具 | 作用 |
| --- | --- |
| `notion_personal_submit` | 新建个人对话，先保存任务编号，再发送一次请求 |
| `notion_personal_read` | 按任务编号或请求键续读，不生成新内容 |
| `notion_personal_reply` | 在空闲的原对话中发送下一轮修正要求 |
| `notion_personal_ask` | 兼容一次提交并等待的入口 |

- 同一个 `request_key` 防止本机意外重复提交；超时后继续 `read`。
- 自动分页，超过 100 条事件仍能读回；中断后从保存的游标恢复。
- 完整正文、代码文件和 SHA-256 保存到本机。工具中的短预览不是最终交付文件。
- 输入支持 `prompt_file`，最多 50,000 个字符，不改写源码空白。
- HTTP 错误分别保留提交和读取诊断，400 不被随后出现的 404 覆盖。

## 快速开始

需要 **Python 3.11+、curl、macOS 或 Linux**。Windows 请在 WSL2 内安装和运行；原生 Windows 暂不支持。只需要 Python 标准库，运行时没有第三方 Python 依赖。

下载本仓库源码或 Release 源码包，进入项目目录：

```sh
python3 -m venv .venv
.venv/bin/python -m pip install .
```

1. 按 [账号配置教程](docs/SETUP.md) 在正常浏览器中捕获**你自己的**一条成功个人对话请求。
2. 把请求存为本机私有的 UTF-8 文件，然后导入：

```sh
.venv/bin/notion-personal-setup import-auth /absolute/path/to/capture.txt
.venv/bin/notion-personal-setup doctor
.venv/bin/notion-personal-setup install-codex
```

安装器只追加 MCP 配置；已有同名配置时会停止，不覆盖你的设置。重新连接 Codex 中的 `notion_personal_http`，即可看到四个工具。保留这个虚拟环境，配置会引用其中的 Python 路径。

也可以从 [Releases](../../releases) 下载 wheel，再运行 `.venv/bin/python -m pip install /path/to/notion_personal_mcp-0.4.0b1-py3-none-any.whl`。

`doctor`、导入认证和安装配置都在本地完成，不调用 Notion、不生成内容。首次实际生成会按你的 Notion 账号规则使用额度。

## 推荐用法

要求客户端提交已授权的任务：

```json
{"prompt":"写一个返回 x * 7 的 Python 函数，只输出源码。","request_key":"demo/function-v1"}
```

保存返回的 `job_id`，再调用 `notion_personal_read`：

```json
{"request_key":"demo/function-v1","wait_seconds":20}
```

读取成功时检查 `result=success`、`transcript_complete=true`、`turn_complete=true`、`answer_saved=true`。完整输出在 `answer_path`，代码文件在 `code_artifacts` 或其完整清单 `code_artifacts_path`。

若要修订，调用 `notion_personal_reply`，传原 `thread_id`、新的 `request_key` 和修订指令；随后读取新返回的 `job_id`。详见 [工具与恢复说明](docs/TOOLS.md)。

## 数据与使用边界

- 默认认证、任务和诊断存于 `~/.config/notion-personal-mcp/private/`，不在源码仓库内。目录权限 0700，私有文件 0600。
- 认证材料仅发送到 `https://app.notion.com`；任务文本会发给你自己的 Notion 账号。项目没有共享服务、遥测或账号转发。
- 捕获请求只是数据，程序不会执行其中的 shell 命令。导入会移除原始提示词、原对话编号及非必要上下文。
- `prompt_file` 会读取并发送所指定的本机文件内容。请只在可信本地 MCP 客户端里启用，不把服务暴露给其他人。
- 不自动重发未知任务、不代替你批准 Notion 工具操作、不切换模型、不回退到 Custom Agent。
- 默认沿用所捕获个人聊天的记忆和审批设置，关闭浏览器工具。模型仍可能请求其他工具；待输入或待批准时会返回相应状态。
- 本地锁只能协调本机进程；不要让网页和 MCP 同时向一个运行中的会话发消息。
- 暂不提供附件、远程取消、浏览器自动登录或自动更新 Cookie。完整传输不等于模型保证输出完整，仍需检查内容。

## 问题反馈与开发

遇到 400、401、403、404 或断线，先看 [故障排查](docs/TROUBLESHOOTING.md)。报告问题时提供版本、状态码、接口名及去除隐私后的描述；**不要上传认证文件、HAR、任务目录或原始诊断文件**。见 [安全说明](SECURITY.md)。

```sh
python3 -B -m unittest discover -s . -p 'test_*.py' -v
python3 scripts/check_release.py
```

测试使用虚构账号和模拟响应，无需真实 Notion 登录。GitHub Actions 会执行 macOS/Linux 回归与构建检查。

MIT License。非 Notion、Anthropic 或 OpenAI 官方项目。