notioncode_mcp

# notioncode_mcp 本地代理桥接器，连接 **Notion AI** 模型与流行的编码环境：OpenCode、Claude Code 和 Codex CLI。允许在这些工具中使用 Notion AI 模型，而不是标准的 OpenAI/Anthropic 模型，无需 OpenAI 或 Anthropic 订阅。 **支持的模型：** - `notion-fable/fable-5`（Fable 5，默认） - `notion-fable/gpt-5.6-sol`（GPT-5.6 Sol） 代理可以读取、创建和编辑 `/root` 目录下的文件，执行 shell 命令并运行检查。 ## 工作原理 ### 架构 ``` OpenCode / Claude Code / Codex CLI │ │ HTTP（OpenAI 或 Anthropic API 格式） ▼ notion-fable-proxy （127.0.0.1:8765） │ │ 代理循环 - 请求到 Notion AI ▼ Notion AI Models （fable-5 / gpt-5.6-sol） │ │ MCP 工具调用 ▼ notion-code-mcp （127.0.0.1:8787） list_files · read_file · write_file · edit_file · run_shell ``` 1. **`notion-fable-proxy`** - API 代理，监听端口 `8765`。接受 OpenAI（适用于 OpenCode、Codex CLI）或 Anthropic Messages API（适用于 Claude Code）格式的请求，并将它们转发到 Notion AI 模型，执行代理循环。 2. **`notion-code-mcp`** - 本地 MCP 服务器，监听端口 `8787`。为代理提供文件系统和 shell 命令执行工具。 3. **`notion-private-api-mcp`** - 可选的 MCP，用于直接通过 `token_v2` 读取和编辑 Notion 页面。 ### 项目结构 ``` notioncode_mcp/ ├── bridge/ # API 代理和代理循环 ├── runtime/ # 本地 MCP 服务器（list_files, read_file, ...） ├── notion-private-api-mcp/ # MCP，用于 Notion Private API（token_v2） ├── config/ # OpenCode、Claude Code、VS Code、Codex CLI 配置 ├── browser/ # 启动 Chrome + Xvfb + noVNC 进行 Notion 授权 ├── deploy/systemd/ # systemd 服务，用于自动启动 ├── scripts/install-local.sh # 安装脚本 ├── bin/codex # Codex CLI 包装器，带有隔离的 CODEX_HOME └── requirements.txt # bridge 的 Python 依赖项 ``` `.runtime/`、 `state/`、 `node_modules/` 和 `runtime/.env` 目录不公开。 它们存储了 Python 虚拟环境、Notion 浏览器配置文件、`token_v2`、会话历史记录、Codex CLI SQLite 数据库和本地 MCP 机密。 ## 要求 - Ubuntu 服务器（已在 Ubuntu 22.04/24.04 上测试） - Python 3.10+ - Node.js 18+ - npm - `openssl`（用于生成 MCP 机密） - 具有 Fable 5 / GPT-5.6 Sol 模型访问权限的 Notion 账户 - 已安装 OpenCode (`opencode`)、Claude Code (`claude`) 或 Codex CLI - 取决于所需的客户端 ## 安装 ### 1. 克隆仓库 ```bash git clone <repo-url> /root/notioncode_mcp cd /root/notioncode_mcp ``` ### 2. 运行安装脚本 ```bash chmod +x scripts/install-local.sh sudo scripts/install-local.sh ``` 安装脚本执行以下操作： - 在 `.runtime/notion-agent-cli-venv` 中创建 Python 虚拟环境并安装 `requirements.txt` 中的依赖项 - 为 `runtime/` 和 `notion-private-api-mcp/` 安装 npm 依赖项 - 生成 `runtime/.env` 文件，包含 `MCP_PATH_SECRET`（随机十六进制机密）、 `CODE_ROOT=/root` 和 `PORT=8787` - 创建符号链接： `.notionagents`、`notion-gui-profile`、虚拟环境、OpenCode 配置文件、Claude Code 配置文件和 VS Code Remote 配置文件 - 安装并启用 `notion-code-mcp` 和 `notion-fable-proxy` systemd 服务 - 创建 `/usr/local/bin/codex` → `bin/codex` 符号链接 ### 3. 授权 Notion 安装后，您需要传递来自 Notion 账户的 `token_v2`。 **方法 A - 手动：** 复制浏览器 cookie（DevTools → Application → Cookies → `token_v2`）中的 `token_v2`，并将其写入 `state/notionagents/` 账户文件，遵循 `notion-agent-cli` 期望的格式。 **方法 B - 通过浏览器（noVNC）：** ```bash # 启动带有 noVNC 的 Chrome 进行视觉授权 bash browser/start.sh # 在浏览器中打开：http://<server-ip>:6080 # 登录 Notion，`token_v2` 将自动保存 ``` ## 安装验证 ```bash # 服务状态 systemctl status notion-code-mcp notion-fable-proxy # API 代理检查 curl http://127.0.0.1:8765/healthz # Codex CLI 检查 codex --version codex mcp list ``` ## 使用 ### OpenCode ```bash cd /root/your-project opencode ``` Fable 5 为默认模型。要使用 GPT-5.6 Sol： ```bash opencode run --model notion-fable/gpt-5.6-sol "执行任务" ``` OpenCode 以 OpenAI 兼容的 API 形式访问 `http://127.0.0.1:8765`。配置文件位于 `config/opencode.jsonc`，符号链接设置为 `~/.config/opencode/opencode.jsonc`。 ### Claude Code（VS Code） 1. 在 VS Code 中安装 `anthropic.claude-code` 扩展。 2. 执行 `Developer: Reload Window` 命令。 3. 扩展程序自动使用 `ANTHROPIC_BASE_URL=http://127.0.0.1:8765`，无需 Anthropic 登录。 Fable 5 为默认模型。要切换模型： - 在 Claude Code 聊天中输入 `/model` 并选择 `GPT-5.6 Sol (Notion)` - 或在终端中运行： ```bash claude --model fable-5 claude --model gpt-5.6-sol ``` 默认权限模式为 `acceptEdits`：允许编辑文件而无需确认，可能需要确认危险命令。 扩展程序配置：`config/claude-settings.json` → 符号链接 `~/.claude/settings.json`。 ### Codex CLI `codex` 命令通过 `bin/codex` 启动，带有隔离的 `CODEX_HOME` 在 `state/codex-cli/`。 ```bash # 使用 Fable 5（默认） codex # 使用 GPT-5.6 Sol codex -m gpt-5.6-sol # 一次性任务 codex run "执行任务" # 连接的 MCP 列表 codex mcp list ``` 在此配置文件中，启用了原生 `/goal` Codex 和 `notion-private` MCP 以处理 Notion 页面。 > **隔离：** 此配置文件中的 Codex CLI 与 VS Code 扩展程序（`openai.chatgpt`）完全隔离。VS Code 扩展程序使用 `/root/.codex` 和原始 OpenAI 模型 - 包装器不会影响它。 配置文件：`config/codex-cli-config.toml` → 在首次安装时复制到 `state/codex-cli/config.toml`。 ## 系统服务 两个 systemd 服务在系统启动时自动启动： | 服务 | 描述 | 端口 | |---|---|---| | `notion-code-mcp` | 本地 MCP 运行时（文件系统和 shell 工具） | `8787` | | `notion-fable-proxy` | Notion AI API 代理（OpenAI/Anthropic 兼容） | `8765` | ```bash # 重启服务 systemctl restart notion-code-mcp notion-fable-proxy # 查看日志 journalctl -u notion-fable-proxy -f journalctl -u notion-code-mcp -f ``` ## 模型管理 可用模型列表及其映射在 `config/codex-models.json` 中定义。要添加新模型： 1. 在 `config/codex-models.json` 中添加记录。 2. 重启 `notion-fable-proxy`。 ## 与 Notion AI 集成的工作原理 该项目使用 **普通 Notion AI** - 不是自定义代理，而是任何 Notion 工作区中可用的标准 AI 聊天。通过 Python 库与内部 Notion AI API 进行交互，该库使用会话 cookie 授权并向 Notion AI 发出请求。 ### 工作原理 **Planner 模式（适用于 OpenCode 和 Codex CLI，无 ）：** - 向模型发送特殊的系统提示：它作为“编码规划器”，一次建议一个操作，以 JSON 格式输出。 - 示例： - 桥接器通过 MCP 运行时执行操作，将结果返回给模型在同一线程中。 - 循环重复，直到模型返回 （最多 20 步）。 **工作流模式（使用指定的 ）：** - 模型像具有工作流的原生 Notion 代理一样工作，直接发出工具调用，格式为 。 - 桥接器拦截这些调用，通过 MCP 执行它们并继续线程（ 和 ）。 **流媒体模式（无工具，例如在聊天中）：** - 模型直接响应，通过 SSE 将文本增量流式传输到客户端。 ### 身份验证和会话 - 通过 **浏览器会话 cookie** 进行身份验证。 - 读取账户信息并保存在 中（符号链接到 ）。 - 在步骤循环中 保存，因此模型“记住”一个任务内的先前操作上下文。 - 客户端的每个新请求都会启动一个新线程。 ### 重要限制 - 使用 **非官方的内部 Notion API** - 可能会在没有通知的情况下更改。 - 在计划程序模式下， 和 禁用，以使模型专注于本地文件。 - 工具循环的最大深度：20 步（计划程序模式）/ 12 步（工作流模式）。 ## 安全 编码运行时仅监听 `127.0.0.1`。请勿公开 `runtime/.env`、`state/`、浏览器配置文件和 Notion cookie。 ## 故障排除 **服务不启动：** ```bash journalctl -u notion-fable-proxy --no-pager -n 50 ``` 确保 Python 虚拟环境存在：`.runtime/notion-agent-cli-venv/bin/python`。 **Notion 身份验证错误：** 使用 `browser/start.sh` 启动浏览器流并在 Notion 上重新授权。 **`codex` 未找到：** ```bash ls -la /usr/local/bin/codex # 应该是一个到 /root/notioncode_mcp/bin/codex 的符号链接 sudo ln -sfn /root/notioncode_mcp/bin/codex /usr/local/bin/codex ``` **MCP 未连接：** ```bash curl http://127.0.0.1:8787/ # notion-code-mcp codex mcp list # 检查服务器列表 ``` ## 在 Windows 上使用 OpenCode 安装 注册 https://app.notion.com/ 并订阅后，下载 `notioncode_mcp_v2.tar.gz` 到单独的文件夹。 如果您无权访问 AI，请安装 OpenCode：其中包含免费的几乎无限的 DeepSeek V4 Flash。重要：请通过命令行安装，而不是 VS Code 扩展。如果您不知道如何操作，请询问任何 AI：“如何在 Windows 上安装 opencode”。 对于俄罗斯联邦：所有操作仅通过 VPN 完成。可以使用的 `@sonnetvpn_bot` 或 https://sonnet.website/ ### MCP 服务器安装 1. 在命令行中打开 OpenCode。可以从 VS Code 打开文件夹 `/root/notioncode_mcp_v2.tar.gz`，但建议使用 cmd 进入项目文件夹。截图 1。 2. 通过 `/models` 选择 DeepSeek V4 Flash Free。如果询问思考，请选择 Max。截图 2。 3. 通过 `@` 选择 `notioncode_mcp_v2.tar.gz` 并发送： ```text @notioncode_mcp_v2.tar.gz 解压此存档到此文件夹 ``` 存档将解压到当前文件夹。截图 3。 4. 发送： ```text 仔细研究这个 mcp 服务器，进行详细的分析，不要更改文件。了解其工作原理，它不能更改！此 mcp 是为 linux 制作的 ``` 等待完成。结果应该如截图 4 所示。 5. 安装 Codex CLI： ```text 安装 codex cli。暂时不要安装 mcp 服务器 ``` 如果 OpenCode 请求许可，请始终允许。截图 5。 6. 检查 Codex CLI：在单独的终端中输入 `codex` 然后回车。Codex 界面应该会打开，带有登录选项。截图 6。请立即通过 Ctrl+C 或 Ctrl+Z 关闭。 7. 返回 OpenCode 并发送： ```text 现在安装此 mcp 服务器，但暂时不要连接到 codex ``` 等待安装。截图 7 中应该有相应的结果。 8. 发送： ```text 现在研究需要哪些数据来自会话（例如 token_v2）才能使此 mcp 服务器正常工作。在此之后，请启动浏览器页面 https://app.notion.com/，我将登录，然后请您复制 cookie 并将其放入 mcp 服务器 ``` OpenCode 将自动打开 https://app.notion.com/。使用上一篇文章中的链接登录到具有订阅的帐户。 9. 登录后发送： ```text 我已经登录，请复制必要的 cookie 并将其放入 mcp 服务器。安装完成后，请连接 codex 到此 mcp 服务器，不断连接，而不是仅限于一次会话 ``` 等待完成。截图 8 中应该有相应的结果。如果它写的是“要正常工作，请先启动服务…” - 发送： ```text 启动它吧 ``` 10. 在另一个终端中使用 `codex` 命令启动 Codex。可以使用 VS Code 中的 Codex 扩展程序；我没有检查单独的应用程序是否有效，但我想它应该有效。如果它请求许可或询问沙盒，请始终允许。 如果出现类似的错误： ```text ⚠ MCP client for `notion-private` failed to start: MCP startup failed: 文件名、文件夹名或卷标的语法错误。 （os error 123） ⚠ MCP startup incomplete（failed: notion-private） ``` 或类似的错误，请忽略它们，这是“正常”的。 启动后，请输入 Codex: `hello`。如果收到回复，则一切正常。然后发送： ```text 在此文件夹中创建 .py 计算器 ``` 如果设置正确，将出现 `calculator.py`。截图 9。 11. 完成！现在您可以在任何项目/文件夹中使用 Codex。它是一个完整的 Codex，就像您拥有最大化订阅一样。OpenCode 和额外的窗口可以关闭 - 一切都将继续工作。 ### 如何使用 - 模型通过 `/model` 在 Codex CLI 或扩展程序中切换，也可以在按钮旁边进行调节。 - 不建议同时运行多个聊天，尤其是通过 `/goal` 启动 - 可能会出现错误 502。 没有限制、配额或限制 - 一切都是完全无限制的。 使用愉快！如果有问题，请在评论中提问。