Onenotemcp

🚀 OneNote MCP 服務器

OneNote MCP 服務器是一個強大的模型上下文協議（MCP）服務器，它使 Claude 等人工智能語言模型（LLMs）以及其他 AI 助手能夠安全地與你的 Microsoft OneNote 數據進行交互。通過 AI 界面，你可以直接對 OneNote 筆記本、分區和頁面進行讀取、寫入、搜索和全面編輯操作。

該服務器為高級 OneNote 管理提供了豐富的工具，包括強大的文本提取、HTML 內容處理和精細的頁面操作。

🚀 快速開始

你可以按照以下步驟快速啟動 OneNote MCP 服務器並與 AI 助手集成：

1. 安裝依賴：確保你已經安裝了 Node.js（推薦版本 18.x 或更高）、npm 和 Git。克隆倉庫並安裝依賴項。
2. 配置 Azure 客戶端 ID：為了安全訪問 Microsoft Graph API，你需要配置 Azure 客戶端 ID。可以通過環境變量或直接修改代碼文件來設置。
3. 啟動服務器：在項目根目錄下運行 node onenote-mcp.mjs 啟動服務器。
4. 連接到 MCP 客戶端：將服務器連接到任何 MCP 兼容的客戶端，如 Claude Desktop 或 Cursor，並進行相應配置。
5. 進行身份驗證：首次使用時，按照身份驗證流程完成登錄和權限授予。

✨ 主要特性

• 身份驗證：使用安全的設備代碼流程訪問 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”。

安裝步驟

1. 克隆倉庫：

   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。
2. 安裝依賴：

   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 示例

1. 打開你的 MCP 客戶端的配置文件：
   • Claude Desktop（macOS）：~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop（Windows）：%APPDATA%\Claude\claude_desktop_config.json
   • Cursor：偏好設置 -> MCP 選項卡。
2. 添加或更新 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，特別是如果你沒有將其設置為系統範圍的環境變量。
3. 重啟你的 MCP 客戶端（Claude Desktop/Cursor）。

身份驗證流程

首次嘗試通過 AI 助手使用 OneNote 工具，或顯式調用 authenticate 工具時：

1. 調用 authenticate 工具：你的 AI 助手將在服務器上調用 authenticate 工具。
2. 設備代碼提示：服務器將在其 stderr 輸出一個 URL（通常為 https://microsoft.com/devicelogin）和一個用戶代碼。你的 MCP 客戶端（如 Claude Desktop）應向你顯示此信息。
3. 瀏覽器身份驗證：在網頁瀏覽器中打開提供的 URL，並輸入用戶代碼。
4. 登錄並授予權限：使用具有 OneNote 訪問權限的 Microsoft 賬戶登錄，並授予請求的權限。
5. 保存令牌：瀏覽器身份驗證成功後，服務器將自動接收並將訪問令牌保存到其目錄中的 .access-token.txt 文件中。
6. 驗證（可選但推薦）：通過你的 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 文件。