MetaTag Genie

简介

MetaTag Genie 是一个 macOS Stdio MCP 服务，专为写入图片元数据以增强 Spotlight 搜索而设计。该服务可被 AI 代理或其他需要本地管理图片元数据的应用程序调用，通过标准输入输出（Stdio）与客户端通信，提供符合 MCP (Machine Comprehension Protocol) 规范的接口。

功能特性

• 通过 Stdio 暴露符合 MCP 规范的服务
• 提供 writeImageMetadata MCP Tool
• 支持向 JPG, PNG, HEIC 图片写入元数据
• 支持的元数据类型：
  • 标签 (Tags)
  • 描述 (Description)
  • 人物 (People - 作为关键词)
  • 地点 (Location - 文本)
• 写入的元数据可被 macOS Spotlight 搜索

系统要求

• Node.js 版本：Node.js 22.x LTS 或更高版本
• 隐含依赖：本项目使用 exiftool-vendored，它会自动管理 ExifTool 的依赖

安装

安装 Smithery

要自动将 MetaTag Genie 安装到 Claude Desktop，请使用 Smithery：

npx -y @smithery/cli install @terryso/metatag_genie --client claude

通过NPM安装（推荐）

# 全局安装
npm install -g metatag-genie

使用全局安装后，可以通过以下命令直接运行：

metatag-genie

或者，您可以不安装直接使用npx运行：

npx metatag-genie

这种方式不需要全局安装，也是AI代理等客户端调用的推荐方式。

通过源码安装

# 1. 克隆仓库
git clone <repository-url>
cd metatag-genie

# 2. 安装依赖
npm install
# 或者: yarn install

# 3. 编译 TypeScript 代码
npm run build
# 或者: yarn build

# 4. 本地链接（可选，用于测试npx和命令行调用）
npm link

运行服务

通过NPX运行（推荐）

安装包后，可以直接通过npx运行：

npx metatag-genie

这种方式不需要全局安装包，适合作为AI代理或其他客户端的调用方式。

开发模式

开发过程中，可以直接使用TypeScript源码运行服务：

npm run start:dev

此命令使用ts-node直接运行TypeScript代码，无需预先编译，适合快速开发和调试。

生产模式

构建后，可以通过以下命令运行编译好的JavaScript代码：

npm start
# 或者直接: node dist/main.js

服务启动后会监听标准输入输出（Stdio），等待MCP客户端连接并发送JSON-RPC消息。

与MCP客户端集成

AI代理（如Cursor）或其他客户端需要在其配置中指定命令的完整路径：

• 基于Node.js：/usr/local/bin/node /path/to/metatag-genie/dist/main.js
• 使用npx：/usr/local/bin/npx metatag-genie

注意：本服务不监听网络端口，仅通过标准输入输出通信。

Cursor MCP集成

在Cursor编辑器中，可以通过以下步骤集成MetaTag Genie：

1. 在项目根目录创建.cursor/mcp.json文件
2. 添加以下配置内容：

{
  "mcpServers": {
    "MetaTagGenie": {
      "command": "npx",
      "args": [
        "-y",
        "metatag-genie"
      ]
    }
  }
}

配置完成后，Cursor中的AI助手将能够使用MetaTag Genie提供的writeImageMetadata工具，直接为图片添加元数据，增强Spotlight搜索体验。

MCP 交互协议

基础

通信基于 Stdio 上的 JSON-RPC 2.0 协议。

初始化流程

客户端需要先发送 initialize 请求，服务器响应 InitializeResult，然后客户端发送 initialized 通知完成握手。

Tool 调用

示例：writeImageMetadata 调用

JSON-RPC 请求示例:

{
  "jsonrpc": "2.0",
  "id": "request-id-123",
  "method": "writeImageMetadata",
  "params": {
    "filePath": "/Users/username/Pictures/photo.jpg",
    "metadata": {
      "tags": ["Vacation", "Beach"],
      "description": "Sunset view from the hotel.",
      "people": ["Alice", "Bob"],
      "location": "Hawaii, USA"
    },
    "overwrite": true
  }
}

JSON-RPC 成功响应示例:

{
  "jsonrpc": "2.0",
  "id": "request-id-123",
  "result": {
    "success": true,
    "filePath": "/Users/username/Pictures/photo.jpg",
    "message": "Metadata successfully written."
  }
}

注意：实际使用时 filePath 需要是有效的绝对路径。

完整的 Tool 参数、返回值和错误代码定义，请参阅 MCP Tools 定义文档。

运行测试

# 运行所有单元测试和集成测试
npm test
# 或者: yarn test

# 在监视模式下运行测试
npm run test:watch
# 或者: yarn test:watch

# 运行测试并生成覆盖率报告 (输出到 coverage/ 目录)
npm run test:cov
# 或者: yarn test:cov

关于不同测试层级的更多信息，请参阅 测试策略文档。

开发与贡献

代码风格

项目使用 ESLint 和 Prettier 强制代码风格，详细规范请参阅 编码规范文档。

请在提交代码前运行以下命令：

# 检查代码风格
npm run lint

# 自动格式化代码
npm run format

分支策略

• master 分支用于发布稳定版本
• 开发新功能或修复 Bug 时，从 master 创建特性分支（例如 feature/add-png-support 或 fix/handle-exiftool-error）
• 完成后提交 Pull Request (PR) 到 master 分支

Pull Request (PR) 流程

• PR 应包含清晰的描述，说明变更内容和原因
• PR 需要通过所有 CI 检查 (Linting, Tests, Build)
• 鼓励进行代码审查

报告问题

如需报告 Bug 或提出功能建议，请在项目的 Issue Tracker 中创建新的 Issue，并提供尽可能详细的信息。

持续集成与自动发布

本项目使用GitHub Actions进行持续集成和自动发布：

• 每次Push和PR会自动运行测试和构建
• 创建Release后会自动发布到NPM

提交PR时请确保通过所有CI检查。如需发布新版本：

1. 更新package.json中的版本号
2. 创建一个新的GitHub Release
3. GitHub Actions会自动将包发布到NPM

文档链接

• 架构文档
• 技术栈
• 项目结构
• MCP Tool 定义
• 测试策略
• 编码规范
• 元数据字段映射
• 手动 Spotlight 测试计划

许可证

本项目采用 MIT 许可证。详情请参阅项目根目录下的 LICENSE 文件。