media-meta-mcp
EXIF/XMP reader for HEIC/HEIF/AVIF/WebP images via pure local byte parsing
التثبيت
أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: .cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).
@nopilot/media-meta-mcpclaude mcp add media-meta-mcp -- npx -y @nopilot/media-meta-mcp@1.0.1
{
"mcpServers": {
"media-meta-mcp": {
"command": "npx",
"args": [
"-y",
"@nopilot/media-meta-mcp@1.0.1"
]
}
}
}
التوثيق
مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.
المحتويات
media-meta
Deterministic modern-image metadata reader: EXIF + XMP from HEIC / HEIF / AVIF / WebP, as a zero-dependency npm engine (@nopilot/media-meta-engine) plus a local-first MCP server (@nopilot/media-meta-mcp).
Why this exists: the JS ecosystem's EXIF workhorses are frozen in the JPEG/TIFF era — exif-parser (~4.7M weekly downloads) last shipped in 2017, and the actively maintained exif-reader (~500k weekly) still takes a raw TIFF buffer and leaves container decoding (where modern formats actually keep their metadata) to someone else. Phones default to HEIC; the modern web runs on WebP/AVIF. Reading their metadata in Node today means gluing together container parsers and EXIF decoders yourself — this package is that, done once, tested, and MIT.
Verified gap (2026-11-15): exif-reader@2.0.3 (latest) source declares a single exif(buffer) entry that parses a TIFF header at offset 0 (index.js; types Exif = { bigEndian, Image?, Photo?, Iop?, GPSInfo?, Thumbnail? }); its README documents JPEG usage via the separate jpg-stream package. There is no HEIC/HEIF/AVIF/WebP container support — no ISOBMFF box walking, no RIFF chunk parsing, zero occurrences of heic|heif|avif|webp|ftyp in the package. The differentiation stands.
The local-first difference
Online EXIF viewers and hosted metadata APIs want your photos uploaded. Location history, device fingerprints, timestamps — exactly the metadata you should not paste into a web form.
media-meta runs entirely on your machine:
| hosted EXIF websites / APIs | media-meta | |
|---|---|---|
| Where your photos go | uploaded to their server | never leave the process |
| Works offline | no | yes |
| HEIC / AVIF / WebP | rarely (JPEG-era mostly) | first-class |
| Dependencies | — | engine has zero runtime deps |
| Source available | mostly closed | MIT, full tests |
Three hard guarantees (enforced by design and tests):
- Deterministic action tools, not AI wrappers — no LLM calls anywhere; identical input produces identical output.
- Pure local computation — zero network requests; even the test fixtures are programmatically generated minimal HEIC/AVIF/WebP files (no downloaded binaries — the fixture builders ship in the package).
- Runs locally, no hosted gateway — stdio or localhost HTTP, bind 127.0.0.1 by default.
What it reads
- HEIC / HEIF / AVIF: ISOBMFF
metabox →iinfitem info +ilocitem locations →Exifitem (TIFF payload, incl. the 4-byte offset prefix per ISO 23008-12) and XMP (mimeitem). Both endian-ness TIFF. - WebP: RIFF container →
EXIFchunk (with or without the 4-byte TIFF-offset prefix) andXMPchunk. - EXIF groups: IFD0 (Make, Model, Orientation, DateTime, ...), Exif sub-IFD (ExposureTime, FNumber, ISO, PixelXDimension, ...), GPS sub-IFD (lat/lon refs + rationals, altitude, ...).
- Container box/chunk listing, brand detection (
heic/heix/mif1/msf1/avif/avis/...), structured warnings for truncated/dangling payloads (reported, never thrown mid-parse).
Not covered (by design): pixel decoding, ICC profiles, thumbnail bitmaps. This is a metadata reader.
Tools (MCP)
image_metadata_read
One local file in → { container, brand, exif: { bigEndian, IFD0, Exif?, GPS? }, xmp?, boxes?, warnings } out. Options to trim xmp/boxes from the response.
Install & run
npm install -g @nopilot/media-meta-mcp
media-meta-mcp # stdio (default)
media-meta-mcp --transport http --port 9440 # stateless Streamable HTTP on 127.0.0.1
MCP client config (stdio):
{
"mcpServers": {
"media-meta": { "command": "media-meta-mcp" }
}
}
Engine usage (npm)
import { readMetaFile, readMetaBuffer } from '@nopilot/media-meta-engine';
const meta = await readMetaFile('IMG_0001.heic');
// → { container: 'heic', brand: 'heic',
// exif: { bigEndian: true, IFD0: { Make: 'Apple', Model: 'iPhone 15 Pro', Orientation: 6, ... },
// Exif: { ISOSpeedRatings: 200, ... }, GPS: { GPSLatitude: [37, 30, 0], ... } },
// xmp: '<?xpacket ...', boxes: [...], warnings: [] }
Fixture builders (also exported — generate legal minimal files with zero network):
import { buildHeicFixture, buildWebp, buildExifPayload } from '@nopilot/media-meta-engine';
const bytes = buildHeicFixture(); // ftyp+meta(iinf/iloc)+mdat with EXIF+XMP items
Development
npm install
npm test # build + typecheck + 16 vitest tests + determinism harness
npm run determinism # byte-equality spot checks only
npm run publish:dry # npm publish --dry-run for both packages
Dependencies & licenses
Runtime dependencies:
| package | version | license | role |
|---|---|---|---|
| (engine) | — | — | zero runtime dependencies — pure first-party byte parsing |
| @modelcontextprotocol/sdk | ^1.32.2 | MIT | official MCP TypeScript SDK (server package only) |
| zod | ^4.6.7 | MIT | tool input schema |
| express | ^5.2.1 | MIT | HTTP transport host |
All transitive runtime dependencies (server package) are MIT/Apache-2.0/BSD/ISC — no GPL/AGPL anywhere in the tree. No image decoders (libheif/mozjpeg/etc.) are used or bundled: metadata boxes are parsed directly, which is exactly why the engine can stay dependency-free.
License of this project: MIT (see LICENSE).
Publishing
This repo ships to zero registries by itself. See PUBLISH.md for the manual npm publish + MCP registry submission steps.
الأسئلة الشائعة
ما هو media-meta-mcp؟
EXIF/XMP reader for HEIC/HEIF/AVIF/WebP images via pure local byte parsing
كيف أثبّت media-meta-mcp؟
يعمل على جهازك. في Claude Code: claude mcp add media-meta-mcp -- npx -y @nopilot/media-meta-mcp@1.0.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.
هل يحتاج media-meta-mcp إلى مفتاح API؟
لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.
هل media-meta-mcp مفتوح المصدر؟
نعم. شيفرته متاحة على GitHub بترخيص MIT.
من يصون media-meta-mcp؟
ينشره latbert. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.
من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.