Affinitymcp

🚀 AffinityMCP

AffinityMCP是一款通用的MCP服務器（基於Rust），它為Canva工作流程提供了實用工具，並且支持對Affinity Photo/Designer/Publisher進行自動化操作。該項目專為在兼容MCP的客戶端中使用自然語言而設計。

🚀 快速開始

對於初學者，請參考SETUP_GUIDE.md獲取詳細的分步說明。

快速安裝：

# 構建
cargo build --release
cp target/release/affinity-mcp dist/

# 在Cursor中使用
# 添加到Cursor MCP設置：
{
  "mcpServers": {
    "affinity-mcp": {
      "command": "npx",
      "args": ["affinity-mcp"],
      "autoStart": true
    }
  }
}

✨ 主要特性

• 🎨 自然語言控制：使用自然語言命令控制Affinity應用程序。
• 🖼️ 文件操作：打開文件、創建新文檔，並以各種格式導出。
• ⚡ 16路並行處理：最多可同時處理16個文件，以實現最高效率。
• 🔧 高級工具：應用濾鏡、獲取文檔信息等。
• 🚀 易於設置：為初學者提供簡單的設置步驟，並配有全面的文檔。
• 🌐 跨平臺支持：目前支持macOS（通過AppleScript），計劃支持Windows。

📦 安裝指南

前提條件

• Node.js 18+（用於輕量級npx包裝器）
• Rust 1.76+ / Cargo（用於本地構建）
• 如果使用Canva Connect/MCP端點，請設置AFFINITY_MCP_API_KEY。

獲取API密鑰

• 如果你的工具需要Canva API，請從Canva開發者控制檯或MCP服務器指南中獲取憑據。否則，你可以跳過此步驟。

本地構建

cd /path/to/affinity-mcp
cargo build --release
# 將target/release/affinity-mcp複製到./dist/
cp target/release/affinity-mcp dist/

💻 使用示例

自然語言命令

在Cursor或其他兼容MCP的客戶端中，你可以使用自然語言：

示例1：打開文件

用戶："在Affinity Photo中打開/Users/john/Desktop/image.jpg文件"
AI：[調用affinity.open_file，路徑="/Users/john/Desktop/image.jpg"，應用程序="Photo"]

示例2：創建並導出

用戶："創建一個尺寸為1920x1080的新Affinity Photo文檔，然後將其作為PDF導出到桌面"
AI：[先調用affinity.create_new，然後調用affinity.export]

示例3：獲取文檔信息

用戶："當前打開的是哪個文檔？"
AI：[調用affinity.get_active_document]

示例4：批量操作（16路並行）

用戶："同時打開這5張圖片：/path/to/img1.jpg, /path/to/img2.jpg, /path/to/img3.jpg, /path/to/img4.jpg, /path/to/img5.jpg"
AI：[調用affinity.batch_open_files並傳入路徑數組]

示例5：批量導出（16路並行）

用戶："將所有打開的文檔作為PDF文件導出到桌面"
AI：[調用affinity.batch_export並傳入多個導出配置]

直接工具調用（MCP工具調用）

{
  "type": "tool",
  "name": "affinity.open_file",
  "arguments": {
    "path": "/path/to/image.jpg",
    "app": "Photo"
  }
}

📚 詳細文檔

• SETUP_GUIDE.md：適合初學者的設置指南，包含詳細的步驟說明。
• SPEC.md：技術規範（日文）。
• README.md：本文檔（英文文檔）。

對於複雜的架構，請查看src/tools/*.rs。

🔧 技術細節

可用工具

Affinity工具（支持自然語言）

所有Affinity工具都支持自然語言命令。示例如下：

• "在Affinity Photo中打開文件/path/to/image.jpg"
• "創建一個寬度為1920、高度為1080的新文檔"
• "將當前文檔作為PDF導出到/path/to/output.pdf"

affinity.open_file

在Affinity應用程序中打開文件（根據文件擴展名自動檢測應用程序）。

• 輸入：{ "path": 字符串, "app"?: "Photo"|"Designer"|"Publisher" }
• 輸出：{ "opened": 布爾值, "app": 字符串, "path": 字符串 }

affinity.create_new

創建一個新的Affinity文檔。

• 輸入：{ "app": "Photo"|"Designer"|"Publisher", "width"?: 數字, "height"?: 數字 }
• 輸出：{ "created": 布爾值, "app": 字符串 }

affinity.export

導出當前打開的文檔。

• 輸入：{ "path": 字符串, "format": "pdf"|"png"|"jpg"|"tiff"|"svg", "quality"?: 數字 }
• 輸出：{ "exported": 布爾值, "path": 字符串 }

affinity.apply_filter

對當前文檔應用濾鏡。

• 輸入：{ "filter_name": 字符串, "intensity"?: 數字 }
• 輸出：{ "applied": 布爾值, "filter_name": 字符串 }

affinity.get_active_document

獲取當前活動文檔的信息。

• 輸入：{}
• 輸出：{ "is_open": 布爾值, "name"?: 字符串, "path"?: 字符串 }

affinity.close_document

關閉當前打開的文檔。

• 輸入：{}
• 輸出：{ "closed": 布爾值 }

affinity.batch_open_files ⚡ 16路並行

同時打開多個文件（最多並行打開16個文件）。

• 輸入：{ "paths": 字符串數組, "app"?: "Photo"|"Designer"|"Publisher" }
• 輸出：{ "success_count": 數字, "failure_count": 數字, "results": OpenFileResult數組 }

自然語言示例："同時打開多個文件：/path/to/image1.jpg, /path/to/image2.jpg, /path/to/image3.jpg"

affinity.batch_export ⚡ 16路並行

同時導出多個文檔（最多並行導出16個文檔）。

• 輸入：{ "exports": ExportParams數組 }
• 輸出：{ "success_count": 數字, "failure_count": 數字, "results": ExportResult數組 }

自然語言示例："將所有打開的文檔作為PDF文件導出"

Canva工具

canva.create_design

• 輸入：{ "title": 字符串, "template_id"?: 字符串, "width"?: 數字, "height"?: 數字 }
• 輸出：{ "design_id": 字符串, "url"?: 字符串 }

名稱一致性與故障排除

始終使用規範ID (affinity-mcp) 作為標識符和密鑰。 僅在UI標籤中使用規範顯示名稱 (AffinityMCP)。 註冊後不要混用舊密鑰。

一致性矩陣

• npm包名稱 → affinity-mcp
• 二進制文件名稱 → affinity-mcp
• MCP服務器名稱 → affinity-mcp
• 環境默認MCP_NAME → affinity-mcp
• 客戶端註冊表鍵 → affinity-mcp
• UI標籤 → AffinityMCP

衝突清理

僅刪除過時的密鑰，並重新添加affinity-mcp。 Cursor僅通過UI進行配置；本倉庫有意省略了.cursor/mcp.json。