Ulysses MCP

🚀 Ulysses MCP Server

Ulysses MCP Server 是一個 MCP（模型上下文協議）服務器，可讓 AI 助手與 macOS 上的 Ulysses 寫作應用程序進行交互，為寫作流程帶來自動化和智能化的提升。

🚀 快速開始

Ulysses MCP Server 提供了一系列工具，可通過 Ulysses 的 x-callback-url API 實現自動化操作。藉助該服務器，像 Claude、Cline 等 AI 助手和其他 MCP 兼容客戶端能夠：

• 📝 創建和管理文檔 - 創建包含內容的新文檔。
• 📁 使用分組進行組織 - 創建和管理文件夾結構。
• ✏️ 添加內容 - 向現有文檔中插入或追加文本。
• 🏷️ 附加元數據 - 為文檔添加註釋、關鍵詞和圖像。
• 📖 讀取內容 - 提取文檔內容和元數據（需要授權）。
• 🧭 導航 - 打開特定的文檔、分組或特殊部分。
• 🔧 修改 - 移動、複製、重命名和刪除項目（需要授權）。

✨ 主要特性

• 全面的自動化工具：提供 23 種工具，涵蓋內容創建、修改、導航、信息獲取和授權等多個方面。
• 多客戶端支持：與 Claude Desktop、Cline 等 MCP 兼容客戶端集成。
• 嚴格的安全機制：包括輸入驗證、訪問令牌處理和速率限制等。
• 本地運行：服務器完全本地運行，保護用戶隱私。

📦 安裝指南

使用 npm

npm install ulysses-mcp

從源代碼安裝

git clone https://github.com/sonofagl1tch/ulysses-mcp.git
cd ulysses-mcp
npm install
npm run build

構建輔助應用程序

⚠️ 重要提示

出於安全原因，此倉庫中不包含輔助應用程序的二進制文件。安裝後，您必須在本地進行構建。

安裝完成後，您需要構建輔助應用程序（回調操作所需）：

npm run build-helper

此命令將創建一個小型的 macOS 應用程序，用於處理來自 Ulysses 的回調。該輔助應用程序：

• 在需要時自動運行（無需手動啟動）。
• 註冊一個自定義 URL 方案 (ulysses-mcp-callback://)。
• 啟用需要回調的操作（授權、讀取內容等）。
• 切勿將其提交到版本控制（已包含在 .gitignore 中）。

更多詳細信息，請參閱 輔助應用程序文檔。

💻 使用示例

基礎用法

創建新文檔

// 創建每日日記條目
{
  "tool": "ulysses_new_sheet",
  "arguments": {
    "text": "# Journal Entry - October 23, 2025\n\nToday I...",
    "group": "/Journal",
    "format": "markdown"
  }
}

添加關鍵詞

// 為文檔添加標籤以便組織
{
  "tool": "ulysses_attach_keywords",
  "arguments": {
    "id": "sheet-identifier-here",
    "keywords": "Draft,Blog,Technical"
  }
}

高級用法

讀取內容（需要授權）

// 首先，進行授權
{
  "tool": "ulysses_authorize",
  "arguments": {
    "appname": "My AI Assistant"
  }
}
// 在 Ulysses 中批准授權後，使用令牌讀取內容
{
  "tool": "ulysses_read_sheet",
  "arguments": {
    "id": "sheet-identifier-here",
    "text": "YES",
    "access_token": "your-access-token"
  }
}

📚 詳細文檔

如需瞭解有關架構、安全、隱私和身份驗證的詳細信息，請參閱 docs/ 目錄中的綜合文檔：

• 架構 - 系統架構、數據流和技術細節。
• 身份驗證 - 授權模型、訪問令牌和安全性。
• 隱私與安全 - 隱私保證、安全功能和驗證。
• 文檔索引 - 完整的文檔概述。

🔧 技術細節

獲取文檔標識符

許多操作都需要文檔和分組的標識符。以下是獲取它們的方法：

在 Mac 上

1. 在文檔列表中選擇一個文檔。
2. 按 ⌘C（Command-C）複製其標識符。
3. 或者：按住 ⌥（Option/Alt）鍵並右鍵單擊 → “複製回調標識符”。

在 iOS/iPadOS 上

1. 長按一個文檔。
2. 選擇 “共享” → “共享快捷方式標識符” → “複製”。
3. 對於分組：點擊 … 按鈕 → 共享 → 共享快捷方式標識符。

標識符類似於：H8zLAmc1I0njH-0Ql-3YGQ。

授權

某些操作（讀取內容、進行破壞性更改）需要授權：

1. 使用 ulysses_authorize 工具並提供您的應用程序名稱。
2. 在 Ulysses 中批准授權請求。
3. 複製提供的訪問令牌。
4. 在後續需要授權的操作中使用該令牌。

訪問令牌在 Ulysses 偏好設置中被撤銷之前一直有效。

安全

⚠️ 重要提示

雖然此 MCP 服務器完全在本地運行且私密，但根據您的配置，您的 AI 助手可能會將數據發送到雲服務：

• 雲 AI（Claude Desktop、ChatGPT 等）：您的寫作內容可能會被髮送到他們的服務器。
• 本地 AI（Ollama、LM Studio）：完全保持本地運行 ✅。

對於敏感內容，請使用僅本地的 AI 模型。詳細信息請參閱 隱私文檔。

訪問令牌處理

⚠️ 重要安全警告：

• 訪問令牌可完全訪問您的 Ulysses 庫。請像對待密碼一樣對待它們。
• 切勿將令牌提交到版本控制 或公開共享。
• 如果需要在會話之間保留令牌，請安全存儲。
• 通過 Ulysses → 偏好設置 → 隱私撤銷不再需要的令牌。
• 速率限制：破壞性操作限制為每分鐘 10 次，以防止意外損壞。

輸入驗證

此服務器實現了全面的輸入驗證：

• 驗證必需參數的存在和非空值。
• 文本輸入有合理的長度限制（內容為 1MB，註釋為 100KB）。
• 枚舉值根據允許的選項進行驗證。
• 所有操作都根據白名單進行驗證。
• 通過安全的命令執行防止命令注入。

安全功能

• ✅ 使用 execFile 而非 exec 防止命令注入。
• ✅ 對所有參數進行輸入驗證。
• ✅ 操作白名單驗證。
• ✅ 對破壞性操作進行速率限制。
• ✅ 清理錯誤消息。
• ✅ 日誌中不暴露敏感數據。

報告安全問題

如果您發現安全漏洞，請發送電子郵件至 sonofagl1tch@pebcakconsulting.com 或在 GitHub 上開啟安全諮詢。請勿公開報告安全漏洞。

用例

內容創建工作流程

• 博客寫作：使用 AI 生成文章並保存到 Ulysses。
• 每日日記：自動創建帶日期的條目。
• 筆記記錄：在 AI 輔助下快速捕獲信息。
• 研究組織：在 AI 幫助下整理研究內容。

內容管理

• 批量標記：使用關鍵詞組織內容。
• 內容審核：以編程方式分析文檔。
• 庫組織：自動管理結構和歸檔。
• 備份與存檔：系統地導出內容。

AI 輔助寫作

• 內容生成：AI 寫作並保存到 Ulysses。
• 編輯輔助：讀取、建議和更新內容。
• 研究整合：獲取並整合研究內容。
• 大綱擴展：將簡報擴展為完整文章。

限制與未來增強

當前限制

MCP 服務器受 Ulysses x-callback-url API 功能的限制。Ulysses GUI 中可用的某些功能目前無法通過 API 實現：

• ❌ 搜索功能 - 無法按內容或元數據搜索文檔。
• ❌ 統計信息 - 無法檢索字數、字符數或閱讀時間。
• ❌ 導出操作 - 無法將文檔導出為 PDF、DOCX 或其他格式。
• ❌ 發佈 - 無法直接發佈到 WordPress、Medium 或其他平臺。
• ❌ 目標和指標 - 無法設置或檢索寫作目標。
• ❌ 文檔歷史 - 無法訪問修訂歷史或版本控制。
• ❌ 過濾器 - 無法按日期、關鍵詞或其他標準過濾文檔。
• ❌ 收藏管理 - 無法通過 API 將文檔標記/取消標記為收藏。
• ❌ 主題/外觀 - 無法控制 Ulysses 的外觀或編輯器設置。

已提交的功能請求

已向 Ulysses 提交了擴展 x-callback-url API 功能的請求。如果您希望看到更多功能，可以考慮：

1. 對功能請求進行投票（鏈接待定）。
2. 聯繫 Ulysses 支持 表達對 API 擴展的興趣。
3. 分享用例 說明增強 API 訪問的好處。

解決方法

對於某些限制，存在部分解決方法：

• 統計信息：讀取文檔內容並在本地計算。
• 搜索：使用 get-root-items 並設置 recursive=YES 進行本地過濾。
• 導出：讀取內容並使用外部工具進行導出。

潛在的未來增強

如果 Ulysses 擴展其 x-callback-url API，此 MCP 服務器可能支持：

• 🔮 跨庫全文搜索。
• 🔮 將文檔導出為各種格式。
• 🔮 檢索寫作統計信息和分析。
• 🔮 管理寫作目標和指標。
• 🔮 訪問修訂歷史。
• 🔮 高級過濾和排序。
• 🔮 發佈集成。

注意：這些增強取決於 Ulysses 擴展其 x-callback-url API。MCP 服務器設計為在新 API 功能可用時易於更新。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

開發

構建

npm run build

監聽更改

npm run watch

使用 MCP Inspector 進行測試

npm run inspector

項目結構

ulysses-mcp/
├── src/
│   └── index.ts          # 主服務器實現
├── build/                # 編譯後的 JavaScript 輸出
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

API 參考

此服務器實現了 Ulysses x-callback-url API 版本 3。

詳細的 API 文檔請參閱：

• Ulysses x-callback-url 文檔
• 模型上下文協議

故障排除

服務器無法連接

• 驗證 Ulysses 是否安裝在您的 Mac 上。
• 檢查 MCP 配置中的構建路徑。
• 重新構建服務器：npm run build。
• 重啟 MCP 客戶端。

授權問題

• 運行 ulysses_authorize 獲取新的令牌。
• 在 Ulysses 提示時批准授權請求。
• 複製並保存訪問令牌。
• 檢查令牌是否在 Ulysses 偏好設置中被撤銷。

文檔標識符無效

• 驗證 22 字符的標識符格式。
• 確保文檔仍存在於 Ulysses 中。
• 注意：如果項目移動，外部文件夾標識符可能會更改。

貢獻

歡迎貢獻！請隨時提交拉取請求。

1. 分叉倉庫。
2. 創建您的功能分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m 'Add amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打開拉取請求。

支持

• 問題反饋：GitHub 問題
• Ulysses 支持：ulysses.app/support
• MCP 文檔：modelcontextprotocol.io

為 Ulysses 和 AI 社區用心打造 ❤️