简介

语言类型：英语
翻译结果：元标签精灵

简介

语言类型：英语
翻译结果：元标签精灵

MetaTag Genie

Introduction

MetaTag Genie is a macOS Stdio MCP service designed to write image metadata to enhance Spotlight search. This service can be invoked by AI agents or other applications that need to manage image metadata locally, communicating with the client via standard input and output (Stdio) and providing an interface that conforms to the MCP (Machine Comprehension Protocol) specification.

Features

• Exposes a service conforming to the MCP specification through Stdio
• Provides the writeImageMetadata MCP Tool
• Supports writing metadata to JPG, PNG, HEIC images
• Supported metadata types:
  • Tags
  • Description
  • People (as keywords)
  • Location (text)
• The written metadata can be searched by macOS Spotlight

System Requirements

• Node.js Version: Node.js 22.x LTS or higher
• Implicit Dependencies: This project uses exiftool-vendored, which automatically manages the dependencies for ExifTool

Installation

Install Smithery

To automatically install MetaTag Genie into Claude Desktop, use Smithery:

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

Install via NPM (Recommended)

bash

Global installation

npm install -g metatag-genie

After global installation, you can run it directly using the following command:

bash metatag-genie

Alternatively, you can run it without installation using npx:

bash npx metatag-genie

This method does not require global installation and is recommended for calls from AI agents and other clients.

Install from Source Code

bash

1. Clone the repository

git clone cd metatag-genie

2. Install dependencies

npm install

Or: yarn install

3. Compile TypeScript code

npm run build

Or: yarn build

4. Local link (optional, for testing with npx and command-line invocation)

npm link

Running the Service

Run via NPX (Recommended)

After installing the package, you can run it directly using npx:

bash npx metatag-genie

This method does not require a global installation and is suitable for calling from AI agents or other clients.

Development Mode

During development, you can run the service directly from the TypeScript source code:

bash npm run start:dev

This command runs the TypeScript code directly using ts-node without pre-compilation, making it suitable for rapid development and debugging.

Production Mode

After building, you can run the compiled JavaScript code using the following command:

bash npm start

Or directly: node dist/main.js

Once the service is started, it will listen on standard input and output (Stdio), waiting for MCP clients to connect and send JSON-RPC messages.

Integration with MCP Clients

AI agents (such as Cursor) or other clients need to specify the full path of the command in their configuration:

• For Node.js: /usr/local/bin/node /path/to/metatag-genie/dist/main.js
• Using npx: /usr/local/bin/npx metatag-genie

Note: This service does not listen on network ports; it communicates only through standard input and output.

Cursor MCP Integration

In the Cursor editor, you can integrate MetaTag Genie by following these steps:

1. Create a .cursor/mcp.json file in the root directory of your project.
2. Add the following configuration content:

json { "mcpServers": { "MetaTagGenie": { "command": "npx", "args": [ "-y", "metatag-genie" ] } } }After the configuration is complete, the AI assistant in Cursor will be able to use the writeImageMetadata tool provided by MetaTag Genie to directly add metadata to images, enhancing the Spotlight search experience.

MCP Interaction Protocol

Basics

Communication is based on the JSON-RPC 2.0 protocol over Stdio.

Initialization Process

The client needs to first send an initialize request, the server responds with InitializeResult, and then the client sends an initialized notification to complete the handshake.

Tool Invocation

Example: writeImageMetadata Call

JSON-RPC Request Example:

json { "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 Successful Response Example:

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

Note: In actual use, filePath must be a valid absolute path.

For full definitions of Tool parameters, return values, and error codes, please refer to the MCP Tools Definition Document.

Running Tests

bash

Run all unit and integration tests

npm test

Or: yarn test

Run tests in watch mode

npm run test:watch

Or: yarn test:watch

Run tests and generate a coverage report (output to the coverage/ directory)

npm run test:cov

Or: yarn test:cov

For more information on different testing levels, please refer to the Testing Strategy Document.

Development and Contribution

Code Style

The project enforces code style using ESLint and Prettier. For detailed specifications, please refer to the Coding Standards Document.

Please run the following commands before committing your code:

bash

Check code style

npm run lint

Automatically format code

npm run format

Branching Strategy

• The master branch is used for releasing stable versions.
• When developing new features or fixing bugs, create a feature branch from master (e.g., feature/add-png-support or fix/handle-exiftool-error).
• After completion, submit a Pull Request (PR) to the master branch.

Pull Request (PR) Process

• PRs should include a clear description of the changes and the reasons for them.
• PRs need to pass all CI checks (Linting, Tests, Build).
• Code reviews are encouraged.

Reporting Issues

To report a bug or suggest a feature, please create a new Issue in the project's Issue Tracker and provide as much detail as possible.

Continuous Integration and Automatic Release

This project uses GitHub Actions for continuous integration and automatic releases:

• Tests and builds are automatically run on every push and PR.
• A new release is automatically published to NPM after creating a GitHub Release.

Ensure that all CI checks pass when submitting a PR. To release a new version:

1. Update the version number in package.json.
2. Create a new GitHub Release.
3. GitHub Actions will automatically publish the package to NPM.

Documentation Links

• Architecture Document
• Tech Stack
• Project Structure
• MCP Tool Definitions
• Testing Strategy
• Coding Standards
• Metadata Field Mapping
• Manual Spotlight Test Plan

License

This project is licensed under the MIT License. For details, see the LICENSE file in the root directory of the project.

工具列表

• writeImageMetadata: Writes metadata (tags, description, people, location) to an image file.

服务配置

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

来源

• 来源：github
• 链接：https://github.com/terryso/meta_tag_genie