JinDaGe - onenotemcp MCP Details

article

README

🚀 OneNote MCP 服务器

OneNote MCP 服务器是一个强大的模型上下文协议（MCP）服务器，它使 Claude 等人工智能语言模型（LLMs）以及其他 AI 助手能够安全地与你的 Microsoft OneNote 数据进行交互。通过 AI 界面，你可以直接对 OneNote 笔记本、分区和页面进行读取、写入、搜索和全面编辑操作。

该服务器为高级 OneNote 管理提供了丰富的工具，包括强大的文本提取、HTML 内容处理和精细的页面操作。

🚀 快速开始

你可以按照以下步骤快速启动 OneNote MCP 服务器并与 AI 助手集成：

安装依赖：确保你已经安装了 Node.js（推荐版本 18.x 或更高）、npm 和 Git。克隆仓库并安装依赖项。
配置 Azure 客户端 ID：为了安全访问 Microsoft Graph API，你需要配置 Azure 客户端 ID。可以通过环境变量或直接修改代码文件来设置。
启动服务器：在项目根目录下运行 node onenote-mcp.mjs 启动服务器。
连接到 MCP 客户端：将服务器连接到任何 MCP 兼容的客户端，如 Claude Desktop 或 Cursor，并进行相应配置。
进行身份验证：首次使用时，按照身份验证流程完成登录和权限授予。

✨ 主要特性

身份验证：使用安全的设备代码流程访问 Microsoft Graph API。
读取操作：
- 列出笔记本、分区和页面。
- 按标题搜索页面。
- 以各种格式（完整 HTML、可读文本、摘要）获取页面内容。
写入和编辑操作：
- 使用自定义 HTML 或 Markdown 内容创建新的 OneNote 页面。
- 更新整个页面内容，可选择保留或替换标题。
- 向现有页面追加内容，可选择添加时间戳和分隔符。
- 更新页面标题。
- 在页面内查找并替换文本（区分大小写或不区分）。
- 向页面添加格式化笔记（如标注或待办事项）。
- 从 CSV 数据向页面插入结构化表格。
高级内容处理：
- 复杂的 HTML 到可读文本提取。
- 页面内容的 Markdown 到 HTML 转换。
强大的输入验证：使用 Zod 定义和验证工具输入模式。

📦 安装指南

前提条件

Node.js：推荐版本 18.x 或更高。可从 nodejs.org 安装。
npm：通常随 Node.js 一起安装。
Git：用于克隆仓库。可从 git-scm.com 安装。
Microsoft 账户：具有 OneNote 访问权限的活跃 Microsoft 账户。
Azure 应用注册（生产/共享使用推荐）：
- 虽然服务器默认使用 Microsoft Graph Explorer 的公共客户端 ID 进行快速测试，但对于常规或共享使用，强烈建议创建自己的 Azure 应用注册。
- 确保你的应用注册具有以下委托的 Microsoft Graph API 权限：Notes.Read、Notes.ReadWrite、Notes.Create、User.Read。
- 你需要应用注册中的“应用程序（客户端）ID”。

安装步骤

克隆仓库：

git clone https://github.com/[your-github-username]/onenote-ultimate-mcp-server.git
cd onenote-ultimate-mcp-server

请将 [your-github-username]/onenote-ultimate-mcp-server 替换为你实际的仓库 URL。

安装依赖：
```
npm install
```

💻 使用示例

基础用法

以下是通过 AI 助手调用 listNotebooks 工具列出所有 OneNote 笔记本的示例：

# 假设这是在 AI 助手的交互环境中
# 调用 listNotebooks 工具
result = ai_assistant.call_tool('listNotebooks')
print(result)

高级用法

以下是使用 createPage 工具创建一个新的 OneNote 页面，并使用自定义 HTML 内容的示例：

# 假设这是在 AI 助手的交互环境中
# 定义页面标题和内容
title = "New Page Title"
content = "<p>This is a new page created with custom HTML content.</p>"
# 调用 createPage 工具
result = ai_assistant.call_tool('createPage', {'title': title, 'content': content})
print(result)

📚 详细文档

配置

Azure 客户端 ID

此服务器需要 Azure 应用客户端 ID 才能与 Microsoft Graph 进行身份验证。

生产/共享使用推荐：将 AZURE_CLIENT_ID 环境变量设置为你自己的 Azure 应用的“应用程序（客户端）ID”。
```
export AZURE_CLIENT_ID="your-actual-azure-app-client-id" 
```
在 Windows 系统中，使用 set AZURE_CLIENT_ID=your-actual-azure-app-client-id。
快速测试：如果未设置 AZURE_CLIENT_ID 环境变量，服务器将默认使用 Microsoft Graph Explorer 的公共客户端 ID。这适用于初始测试，但不建议长期或共享使用。
你也可以直接在 onenote-mcp.mjs 中修改 clientId 变量，但建议使用环境变量。

`.gitignore`

项目包含一个 .gitignore 文件。请确保它至少包含以下内容，以防止提交敏感文件：

node_modules/
.DS_Store
*.log
.access-token.txt
.env

.access-token.txt 文件将由服务器创建，用于存储你的身份验证令牌。

运行 MCP 服务器

配置完成后，在项目根目录下启动服务器：

node onenote-mcp.mjs

你应该会看到控制台输出，表明服务器已启动并列出可用的工具类别。

连接到 MCP 客户端

你可以将此服务器连接到任何 MCP 兼容的客户端，如 Claude Desktop 或 Cursor。

Claude Desktop 或 Cursor 示例

打开你的 MCP 客户端的配置文件：
- Claude Desktop（macOS）：~/Library/Application Support/Claude/claude_desktop_config.json
- Claude Desktop（Windows）：%APPDATA%\Claude\claude_desktop_config.json
- Cursor：偏好设置 -> MCP 选项卡。

添加或更新 mcpServers 配置：

{
  "mcpServers": {
    "onenote": {
      "command": "node",
      "args": ["/full/path/to/your/onenote-ultimate-mcp-server/onenote-mcp.mjs"],
      "env": {
        // 推荐：如果未全局设置，在此处设置 AZURE_CLIENT_ID
        "AZURE_CLIENT_ID": "YOUR_AZURE_APP_CLIENT_ID_HERE" 
      }
    }
  }
}

将 /full/path/to/your/onenote-ultimate-mcp-server/ 替换为你克隆仓库的绝对路径。
将 YOUR_AZURE_APP_CLIENT_ID_HERE 替换为你的 Azure 应用的客户端 ID，特别是如果你没有将其设置为系统范围的环境变量。

重启你的 MCP 客户端（Claude Desktop/Cursor）。

身份验证流程

首次尝试通过 AI 助手使用 OneNote 工具，或显式调用 authenticate 工具时：

调用 authenticate 工具：你的 AI 助手将在服务器上调用 authenticate 工具。
设备代码提示：服务器将在其 stderr 输出一个 URL（通常为 https://microsoft.com/devicelogin）和一个用户代码。你的 MCP 客户端（如 Claude Desktop）应向你显示此信息。
浏览器身份验证：在网页浏览器中打开提供的 URL，并输入用户代码。
登录并授予权限：使用具有 OneNote 访问权限的 Microsoft 账户登录，并授予请求的权限。
保存令牌：浏览器身份验证成功后，服务器将自动接收并将访问令牌保存到其目录中的 .access-token.txt 文件中。
验证（可选但推荐）：通过你的 AI 助手调用 saveAccessToken 工具。此工具实际上并不保存（因为后台进程已经保存），而是加载并验证令牌，确认身份验证成功并显示你的账户信息。

保存的令牌将用于后续会话，直到过期，届时你可能需要重新进行身份验证。

可用的 MCP 工具

此服务器向你的 AI 助手公开以下工具：

身份验证

authenticate：启动与 Microsoft Graph 的设备代码身份验证流程。
saveAccessToken：加载并验证本地保存的访问令牌。

读取 OneNote 数据

listNotebooks：列出你所有的 OneNote 笔记本。
searchPages：在所有笔记本中按标题搜索页面。（参数：query（可选字符串））
getPageContent：检索特定 OneNote 页面的内容。（参数：pageId（字符串），format（枚举："text"，"html"，"summary"，可选，默认："text"））
getPageByTitle：按标题查找页面并检索其内容。（参数：title（字符串），format（枚举："text"，"html"，"summary"，可选，默认："text"））

编辑和创建 OneNote 页面

createPage：在第一个可用分区中创建一个新的 OneNote 页面。（参数：title（字符串），content（字符串 - HTML 或 Markdown））
updatePageContent：替换现有页面的整个内容。（参数：pageId（字符串），content（字符串），preserveTitle（布尔值，可选，默认：true））
appendToPage：向现有页面的末尾添加新内容。（参数：pageId（字符串），content（字符串），addTimestamp（布尔值，可选，默认：true），addSeparator（布尔值，可选，默认：true））
updatePageTitle：更改现有页面的标题。（参数：pageId（字符串），newTitle（字符串））
replaceTextInPage：在页面内查找并替换文本。（参数：pageId（字符串），findText（字符串），replaceText（字符串），caseSensitive（布尔值，可选，默认：false））
addNoteToPage：向页面添加格式化、带时间戳的笔记/评论。（参数：pageId（字符串），note（字符串），noteType（枚举："note"，"todo"，"important"，"question"，可选，默认："note"），position（枚举："top"，"bottom"，可选，默认："bottom"））
addTableToPage：从 CSV 数据向页面添加格式化表格。（参数：pageId（字符串），tableData（字符串 - CSV），title（字符串，可选），position（枚举："top"，"bottom"，可选，默认："bottom"））

与 AI 的交互示例

连接并进行身份验证后，你可以要求你的 AI 助手执行以下任务：

"列出我的 OneNote 笔记本。"
"创建一个名为 '会议想法' 的新 OneNote 页面，内容为 '头脑风暴新的营销策略'。"
"你能找到我关于 '凤凰项目' 的 OneNote 页面并告诉我其摘要吗？"
"将 '跟进 John Doe' 追加到 ID 为 'your-page-id-here' 的 OneNote 页面。"
"在我的 OneNote 页面 '食谱想法' 中，将所有 '糖' 替换为 '甜味剂'。"

故障排除

身份验证问题

确保你的 AZURE_CLIENT_ID（如果已设置）正确，并且具有所需的 API 权限。
如果设备代码流程失败，请尝试在不同的浏览器或隐身/私密窗口中进行。
令牌过期：如果工具停止工作，你可能需要重新运行 authenticate 工具。

服务器无法启动

检查 Node.js 版本（node -v）。
确保所有依赖项都已安装（npm install）。

MCP 客户端问题（如 Claude Desktop、Cursor）

验证客户端的 MCP 服务器配置中的 command 和 args（特别是 onenote-mcp.mjs 的绝对路径）是否正确。
进行配置更改后，重启 MCP 客户端。
检查 MCP 客户端的日志和服务器的控制台输出，查找错误信息。

安全注意事项

访问令牌安全：.access-token.txt 文件包含一个令牌，根据定义的范围授予对 OneNote 数据的访问权限。请像保护任何敏感凭证一样保护此文件。确保它包含在你的 .gitignore 文件中。
Azure 客户端 ID：如果你创建了自己的 Azure 应用注册，请确保其客户端密钥（如果为其他流程生成）安全。对于此设备代码流程，此脚本不使用客户端密钥。
权限：此服务器请求 Notes.ReadWrite 和 Notes.Create 权限。请注意你授予的访问权限。

致谢

本项目的开发受到了以下开源项目的启发并借鉴了其模式：

onenote-mcp 作者 danosb：该项目是早期的灵感来源，为 OneNote MCP 服务器的结构提供了参考，特别是在身份验证和基本 OneNote 操作的初始概念方面。
azure-onenote-mcp-server 作者 Zubeid Hendricks：使用设备代码凭证的核心身份验证流程、令牌存储/检索策略以及将 Microsoft Graph API 调用包装为 OneNote MCP 工具（如列出实体和创建页面）的基础模式，在很大程度上受到了该项目的启发或进行了改编。该项目遵循 MIT 许可证。

此服务器的大量编辑工具、高级文本提取和 HTML 处理实用程序、Zod 模式集成以及整体优化的结构是原创贡献。

此服务器的开发还得到了 AI 语言模型的协助，包括 Anthropic 的 Claude 和 Google 的 Gemini，用于代码生成、重构、调试和文档编写等任务。

我们感谢参考项目的作者和 AI 工具的开发者对开源和开发社区的贡献。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

onenotemcp