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。