JinDaGe - open-notebook-mcp MCP Details

article

README

🚀 Open Notebook MCP 服务器

Open Notebook MCP 服务器是一个基于 MCP（模型上下文协议）的服务器，它提供了与 Open Notebook API 进行交互的工具。借助该服务器，像 Claude 这样的 AI 助手能够管理笔记本、来源、笔记，搜索内容，并通过 Open Notebook 与 AI 模型进行交互。

🚀 快速开始

安装

使用 uv（推荐）

# 克隆仓库
git clone https://github.com/PiotrAleksander/open-notebook-mcp.git
cd open-notebook-mcp

# 使用 uv 安装
uv sync

使用 pip

pip install -e .

配置

服务器需要进行配置才能连接到你的 Open Notebook 实例：

环境变量

创建一个 .env 文件或设置以下环境变量：

# 必需：你的 Open Notebook 实例的 URL
OPEN_NOTEBOOK_URL=http://localhost:5055

# 可选：认证密码（如果 Open Notebook 中设置了 APP_PASSWORD）
OPEN_NOTEBOOK_PASSWORD=your_password_here

# 可选：传输配置（默认：stdio）
MCP_TRANSPORT=stdio  # 或 streamable-http 用于远程部署

配置示例

对于使用默认 Open Notebook 设置的本地开发：

# .env
OPEN_NOTEBOOK_URL=http://localhost:5055

如果你在 Open Notebook 中配置了认证：

# .env
OPEN_NOTEBOOK_URL=http://localhost:5055
OPEN_NOTEBOOK_PASSWORD=my_secure_password

运行服务器

开发模式（STDIO）

供本地与 AI 助手一起使用：

uv run open-notebook-mcp

或者使用 MCP CLI：

mcp dev src/open_notebook_mcp/server.py

生产模式（Streamable HTTP）

用于远程部署：

MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uv run open-notebook-mcp

与 Claude Desktop 一起使用

将以下内容添加到你的 Claude Desktop 配置中（在 macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "open-notebook": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/open-notebook-mcp",
        "open-notebook-mcp"
      ],
      "env": {
        "OPEN_NOTEBOOK_URL": "http://localhost:5055",
        "OPEN_NOTEBOOK_PASSWORD": "your_password_if_needed"
      }
    }
  }
}

✨ 主要特性

笔记本管理：创建、读取、更新和删除笔记本。
来源管理：添加和管理内容来源（链接、上传文件、文本）。
笔记管理：在笔记本中创建和组织笔记。
搜索与 AI：使用向量/文本搜索功能搜索内容并提问。
模型管理：配置和管理 AI 模型。
聊天会话：创建和管理聊天对话。
设置：访问和更新应用程序设置。
渐进式展示：使用 search_capabilities 高效发现工具。

💻 使用示例

基础用法

# 发现可用工具
# 获取所有工具的摘要
search_capabilities(query="", detail="summary", limit=50)

# 搜索特定功能
search_capabilities(query="notebook", detail="summary", limit=10)

# 获取特定工具的完整详细信息
search_capabilities(query="create_notebook", detail="full", limit=1)

高级用法

创建和管理笔记本

# 创建一个新笔记本
result = create_notebook(
    name="AI Research",
    description="Research on AI applications"
)
notebook_id = result["notebook"]["id"]

# 列出所有笔记本
notebooks = list_notebooks(archived=False, limit=20)

# 更新一个笔记本
update_notebook(
    notebook_id=notebook_id,
    name="AI Research (Updated)"
)

# 获取一个特定的笔记本
notebook = get_notebook(notebook_id=notebook_id)

添加来源

# 添加一个网页来源
source = create_source(
    notebook_id=notebook_id,
    type="link",
    url="https://example.com/ai-article",
    title="AI Research Article",
    embed=True  # 生成嵌入内容
)

# 列出笔记本中的来源
sources = list_sources(notebook_id=notebook_id, limit=20)

创建笔记

# 创建一个笔记
note = create_note(
    notebook_id=notebook_id,
    title="Key Findings",
    content="Important insights about AI applications...",
    topics=["AI", "Research"]
)

# 更新一个笔记
update_note(
    note_id=note["note"]["id"],
    content="Updated insights..."
)

搜索和提问

# 搜索内容
results = search(
    query="artificial intelligence",
    type="vector",
    notebook_id=notebook_id,
    limit=10
)

# 先列出可用的模型
models = list_models(limit=50)
model_id = models["models"][0]["id"]

# 提问
answer = ask_simple(
    question="What are the main AI applications mentioned?",
    strategy_model=model_id,
    answer_model=model_id,
    final_answer_model=model_id,
    notebook_id=notebook_id
)

聊天会话

# 创建一个聊天会话
session = create_chat_session(
    notebook_id=notebook_id,
    title="Research Discussion"
)
session_id = session["session"]["id"]

# 构建上下文
context = get_chat_context(notebook_id=notebook_id)

# 发送一条消息
response = execute_chat(
    session_id=session_id,
    message="What are the key insights from my research?",
    context=context["context"]
)

# 获取会话历史记录
history = get_chat_session(session_id=session_id)

📚 详细文档

可用工具

服务器提供了 39 个工具，分为多个类别： | 类别 | 工具 | | ---- | ---- | | 元工具 | search_capabilities - 渐进式工具发现 | | 笔记本（5 个工具） | list_notebooks, get_notebook, create_notebook, update_notebook, delete_notebook | | 来源（5 个工具） | list_sources, get_source, create_source, update_source, delete_source | | 笔记（5 个工具） | list_notes, get_note, create_note, update_note, delete_note | | 搜索（3 个工具） | search, ask_question, ask_simple | | 模型（5 个工具） | list_models, get_model, create_model, delete_model, get_default_models | | 聊天（7 个工具） | list_chat_sessions, create_chat_session, get_chat_session, update_chat_session, delete_chat_session, execute_chat, get_chat_context | | 设置（2 个工具） | get_settings, update_settings |

架构

此服务器遵循 MCP 最佳实践：

渐进式展示：使用 search_capabilities 最小化上下文使用。
上下文效率：默认输出较小，带有限制参数。
双传输：支持 STDIO（本地）和 Streamable HTTP（远程）。
错误处理：带有可操作提示的结构化错误消息。
超时：所有 API 请求的默认超时时间为 30 秒。
认证：可选的 Bearer 令牌认证。

开发

项目结构

open-notebook-mcp/
├── src/
│   └── open_notebook_mcp/
│       ├── __init__.py
│       └── server.py          # 主要的 MCP 服务器实现
├── tests/                      # （待添加）
├── pyproject.toml
├── README.md
└── .env.example

测试

使用 MCP Inspector 测试服务器：

mcp dev src/open_notebook_mcp/server.py

或者

npx @modelcontextprotocol/inspector uv --directory ./src/open_notebook_mcp "run" "server.py"

这将打开一个交互式检查器，你可以在其中：

浏览可用工具。
测试工具调用。
检查响应。
调试错误。

添加新工具

要添加新工具，请执行以下步骤：

向 CAPABILITIES 元组中添加一个 Capability 条目。
使用 @mcp.tool() 装饰器实现工具函数。
遵循命名约定：动词_名词（例如，list_notebooks）。
包含适当的文档字符串和类型提示。
返回带有 request_id 的结构化响应。

要求

Python 3.12+
Open Notebook 实例（本地或远程）
依赖项：mcp[cli]>=1.23.2，httpx>=0.28.1

贡献

欢迎贡献代码！请确保：

遵循现有的代码结构和模式。
将工具添加到 CAPABILITIES 索引中。
包含适当的类型提示和文档字符串。
在提交之前使用 MCP Inspector 进行测试。

📄 许可证

有关详细信息，请参阅 LICENSE 文件。

🔗 链接

🛠️ 支持

对于以下相关问题：

此 MCP 服务器：在此仓库中创建一个问题。
Open Notebook 本身：访问 Open Notebook 仓库。
MCP 协议：查看 MCP 文档。

open-notebook-mcp