MetaTag Genie

简介

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

Related MCP server: Google Toolbox

功能特性

• 通过 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：

通过NPM安装（推荐）

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

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

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

通过源码安装

运行服务

通过NPX运行（推荐）

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

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

开发模式

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

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

生产模式

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

服务启动后会监听标准输入输出（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. 添加以下配置内容：

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

MCP 交互协议

基础

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

初始化流程

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

Tool 调用

示例：writeImageMetadata 调用

JSON-RPC 请求示例:

JSON-RPC 成功响应示例:

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

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

运行测试

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

开发与贡献

代码风格

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

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

分支策略

• 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 文件。