@mrfentmen/aaf-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# AAF MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AAF MCP: parse AAF-XML content storage, mobs and tagged values.
+
+No network calls. Files are parsed locally and nothing leaves the machine.
+
+## Install
+
+```bash
+npx -y @mrfentmen/aaf-mcp
+```
+
+Or in an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "aaf-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mrfentmen/aaf-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `detect_files` | Find AAF files in a directory tree. |
+| `read_file` | Read a file or line range. |
+| `write_file` | Write a file, with overwrite protection. |
+| `parse` | Parse into records, fields and metadata. |
+| `validate` | Check structural rules and report issues by line. |
+| `summarize` | Record counts, kinds and document metadata. |
+| `list_records` | List record ids and kinds. |
+| `get_record` | Full fields for one record. |
+| `search` | Plain text or regex search across records. |
+| `stats` | Numeric min/max/mean per field. |
+| `format_reference` | Compact spec reference. |
+| `sample` | A small valid example document. |
+| `diff` | *(premium)* Compare two documents. |
+| `to_json` | *(premium)* Export every record as JSON. |
+
+<!-- paywall -->
+## Premium tools
+
+`diff` and `to_json` need a licence key. Their bodies run on our gateway, not
+inside this package, so the key is what buys access. Buy one at
+https://buy.polar.sh/polar_cl_mrO7rS5LZxpqM7oAFFEA10i9121J240U40IIj4JRZO4
+and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "polar_..." }
+```
+
+Every other tool on this server stays free.
+<!-- /paywall -->
+
+## Safety
+
+This server reads and writes local files. Treat file paths as trusted input.
+Invalid documents are reported, never silently repaired.
+
+## Run locally
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```

package/dist/_xml.d.ts

@@ -0,0 +1,11 @@
+import type { Issue } from "./types.js";
+export interface XmlTag {
+    name: string;
+    attrs: Record<string, string>;
+    close: boolean;
+    selfClose: boolean;
+    line: number;
+}
+export declare function scanTags(text: string): XmlTag[];
+export declare function readRoot(text: string): string;
+export declare function validateXml(text: string, root: string, displayName: string, issues: Issue[]): void;

package/dist/_xml.js

@@ -0,0 +1,62 @@
+export function scanTags(text) {
+    const tags = [];
+    const re = /<(\/?)([A-Za-z_][\w.:-]*)([^>]*?)(\/?)>/g;
+    let match;
+    let cursor = 0;
+    let line = 1;
+    while ((match = re.exec(text)) !== null) {
+        line += (text.slice(cursor, match.index).match(/\n/g) ?? []).length;
+        cursor = match.index;
+        const attrs = {};
+        for (const attr of match[3].matchAll(/([\w.:-]+)\s*=\s*"([^"]*)"/g))
+            attrs[attr[1]] = attr[2];
+        tags.push({ name: match[2], attrs, close: match[1] === "/", selfClose: match[4] === "/", line });
+    }
+    return tags;
+}
+export function readRoot(text) {
+    const declaration = text.replace(/^\s*<\?xml[^>]*\?>/, "");
+    const match = /<\s*([A-Za-z_][\w.:-]*)/.exec(declaration);
+    return match ? match[1] : "";
+}
+export function validateXml(text, root, displayName, issues) {
+    if (text.trim().length === 0) {
+        issues.push({ code: "empty", severity: "error", message: "Document is empty" });
+        return;
+    }
+    const tags = scanTags(text);
+    if (tags.length === 0) {
+        issues.push({ code: "no-tags", severity: "error", message: "No XML elements found" });
+        return;
+    }
+    const found = readRoot(text);
+    if (found !== root) {
+        issues.push({ code: "bad-root", severity: "error", message: `Root element must be ${root}, found ${found || "nothing"}` });
+    }
+    const stack = [];
+    for (const tag of tags) {
+        if (tag.selfClose)
+            continue;
+        if (tag.close) {
+            const open = stack.pop();
+            if (!open) {
+                issues.push({ code: "unmatched-close", severity: "error", message: `Closing </${tag.name}> has no opening tag`, line: tag.line });
+            }
+            else if (open.name !== tag.name) {
+                issues.push({
+                    code: "mismatched-tag",
+                    severity: "error",
+                    message: `</${tag.name}> closes <${open.name}> from line ${open.line}`,
+                    line: tag.line,
+                });
+            }
+            continue;
+        }
+        stack.push(tag);
+    }
+    for (const open of stack.slice(-3)) {
+        issues.push({ code: "unclosed-tag", severity: "error", message: `<${open.name}> is never closed`, line: open.line });
+    }
+    if (!root)
+        issues.push({ code: "no-root", severity: "error", message: `${displayName} has no root element` });
+}

package/dist/core.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { FormatModule } from "./types.js";
+export declare function registerFormatTools(server: McpServer, format: FormatModule): void;

package/dist/core.js

@@ -0,0 +1,334 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { errorMessage, fail, text, ToolError } from "./run.js";
+import { GatewayError, premiumTool } from "./gateway.js";
+const MAX_INPUT = 4_000_000;
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".mcp-build"]);
+const PREMIUM = new Set(["to_json", "diff"]);
+async function readInput(input) {
+    if (input.path && input.content !== undefined)
+        throw new ToolError("Use path or content, not both");
+    if (input.content !== undefined) {
+        if (input.content.length > MAX_INPUT)
+            throw new ToolError(`Input is larger than ${MAX_INPUT} characters`);
+        return { body: input.content };
+    }
+    if (!input.path)
+        throw new ToolError("Provide a path or content");
+    if (input.path.includes("\0"))
+        throw new ToolError("Path contains a null byte");
+    const file = path.isAbsolute(input.path) ? input.path : path.resolve(input.cwd ? path.resolve(input.cwd) : process.cwd(), input.path);
+    const stat = await fs.stat(file);
+    if (!stat.isFile())
+        throw new ToolError(`Not a file: ${file}`);
+    if (stat.size > MAX_INPUT)
+        throw new ToolError(`File is larger than ${MAX_INPUT} bytes`);
+    return { body: await fs.readFile(file, "utf8"), file };
+}
+function parseOrThrow(format, body) {
+    const parsed = format.parse(body);
+    const errors = parsed.issues.filter((issue) => issue.severity === "error");
+    if (errors.length > 0) {
+        const first = errors.slice(0, 5).map((issue) => (issue.line ? `line ${issue.line}: ${issue.message}` : issue.message));
+        throw new ToolError(`${format.displayName} could not be parsed:\n${first.join("\n")}`);
+    }
+    return parsed;
+}
+function numericStats(records) {
+    const out = {};
+    for (const record of records) {
+        for (const [key, value] of Object.entries(record.fields)) {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                continue;
+            const current = out[key];
+            if (!current) {
+                out[key] = { count: 1, min: value, max: value, mean: value, sum: value };
+            }
+            else {
+                current.count += 1;
+                current.sum += value;
+                current.min = Math.min(current.min, value);
+                current.max = Math.max(current.max, value);
+                current.mean = current.sum / current.count;
+            }
+        }
+    }
+    return out;
+}
+function round(value) {
+    return Number.isFinite(value) ? Math.round(value * 1000) / 1000 : value;
+}
+export function registerFormatTools(server, format) {
+    const sourceArgs = {
+        path: z.string().min(1).max(2_000).optional(),
+        content: z.string().max(MAX_INPUT).optional(),
+        cwd: z.string().min(1).max(2_000).optional(),
+    };
+    server.tool("detect_files", `Find ${format.displayName} files (${format.extensions.join(", ")}) in a directory tree.`, {
+        path: z.string().min(1).max(2_000).default("."),
+        maxDepth: z.number().int().min(0).max(8).default(4),
+    }, async (a) => {
+        try {
+            const root = path.resolve(a.path);
+            const stat = await fs.stat(root);
+            if (!stat.isDirectory())
+                throw new ToolError(`Not a directory: ${root}`);
+            const found = [];
+            let scanned = 0;
+            async function walk(dir, depth) {
+                if (depth > a.maxDepth || found.length >= 500)
+                    return;
+                let entries;
+                try {
+                    entries = await fs.readdir(dir, { withFileTypes: true });
+                }
+                catch {
+                    return;
+                }
+                for (const entry of entries) {
+                    if (entry.name.startsWith("."))
+                        continue;
+                    const full = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        if (SKIP_DIRS.has(entry.name))
+                            continue;
+                        await walk(full, depth + 1);
+                        continue;
+                    }
+                    if (!entry.isFile())
+                        continue;
+                    scanned += 1;
+                    if (!format.extensions.includes(path.extname(entry.name).toLowerCase()))
+                        continue;
+                    found.push(path.relative(root, full));
+                    if (found.length >= 500)
+                        return;
+                }
+            }
+            await walk(root, 0);
+            return text(JSON.stringify({ format: format.displayName, root, filesScanned: scanned, matches: found.length, files: found }, null, 2));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("read_file", `Read a ${format.displayName} file, optionally a line range.`, {
+        path: z.string().min(1).max(2_000),
+        startLine: z.number().int().min(1).default(1),
+        endLine: z.number().int().min(1).optional(),
+        cwd: z.string().min(1).max(2_000).optional(),
+    }, async (a) => {
+        try {
+            const { body } = await readInput({ path: a.path, cwd: a.cwd });
+            const lines = body.split(/\r?\n/);
+            const end = Math.min(a.endLine ?? lines.length, lines.length);
+            return text(lines.slice(a.startLine - 1, end).join("\n"));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("write_file", `Write a ${format.displayName} file. Refuses to overwrite unless overwrite is true.`, {
+        path: z.string().min(1).max(2_000),
+        content: z.string().max(MAX_INPUT),
+        overwrite: z.boolean().default(false),
+        cwd: z.string().min(1).max(2_000).optional(),
+    }, async (a) => {
+        try {
+            const file = path.isAbsolute(a.path) ? a.path : path.resolve(a.cwd ? path.resolve(a.cwd) : process.cwd(), a.path);
+            if (!a.overwrite) {
+                const exists = await fs.stat(file).then(() => true).catch(() => false);
+                if (exists)
+                    throw new ToolError(`File already exists: ${file}. Set overwrite=true to replace it.`);
+            }
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            await fs.writeFile(file, a.content, "utf8");
+            return text(`Wrote ${Buffer.byteLength(a.content)} bytes to ${file}`);
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("parse", `Parse ${format.displayName} into records, fields and document metadata.`, { ...sourceArgs }, async (a) => {
+        try {
+            const { body, file } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            return text(JSON.stringify({
+                file: file ?? null,
+                format: parsed.format,
+                meta: parsed.meta,
+                records: parsed.records.length,
+                kinds: parsed.records.reduce((acc, record) => {
+                    acc[record.kind] = (acc[record.kind] ?? 0) + 1;
+                    return acc;
+                }, {}),
+                issues: parsed.issues,
+            }, null, 2));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("validate", `Validate ${format.displayName} against its structural rules and report every issue with a line number.`, { ...sourceArgs }, async (a) => {
+        try {
+            const { body } = await readInput(a);
+            const parsed = format.parse(body);
+            const errors = parsed.issues.filter((issue) => issue.severity === "error").length;
+            const warnings = parsed.issues.length - errors;
+            return text(JSON.stringify({
+                format: parsed.format,
+                valid: errors === 0,
+                errors,
+                warnings,
+                issues: parsed.issues,
+            }, null, 2));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("summarize", `Summarize a ${format.displayName} document: metadata, record counts and per-kind totals.`, { ...sourceArgs }, async (a) => {
+        try {
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const kinds = parsed.records.reduce((acc, record) => {
+                acc[record.kind] = (acc[record.kind] ?? 0) + 1;
+                return acc;
+            }, {});
+            const lines = [
+                `${format.displayName} document`,
+                `records: ${parsed.records.length}`,
+                ...Object.entries(kinds).map(([kind, count]) => `  ${kind}: ${count}`),
+                ...Object.entries(parsed.meta).map(([key, value]) => `${key}: ${String(value)}`),
+                `issues: ${parsed.issues.length}`,
+            ];
+            return text(lines.join("\n"));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("list_records", `List ${format.displayName} record ids and kinds, with a limit.`, {
+        ...sourceArgs,
+        limit: z.number().int().min(1).max(1_000).default(50),
+    }, async (a) => {
+        try {
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const rows = parsed.records.slice(0, a.limit).map((record) => `${record.kind}\t${record.id}`);
+            const rest = parsed.records.length - rows.length;
+            return text(rows.join("\n") + (rest > 0 ? `\n... ${rest} more` : ""));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("get_record", `Return one ${format.displayName} record by id, with all parsed fields.`, {
+        ...sourceArgs,
+        id: z.string().min(1).max(300),
+    }, async (a) => {
+        try {
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const record = parsed.records.find((item) => item.id === a.id);
+            if (!record)
+                throw new ToolError(`No record with id ${a.id}. Use list_records to see available ids.`);
+            return text(JSON.stringify(record, null, 2));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("search", `Search ${format.displayName} records by plain text or regular expression.`, {
+        ...sourceArgs,
+        query: z.string().min(1).max(500),
+        regex: z.boolean().default(false),
+        limit: z.number().int().min(1).max(500).default(50),
+    }, async (a) => {
+        try {
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            let test;
+            if (a.regex) {
+                let pattern;
+                try {
+                    pattern = new RegExp(a.query, "i");
+                }
+                catch {
+                    throw new ToolError(`Invalid regular expression: ${a.query}`);
+                }
+                test = (value) => pattern.test(value);
+            }
+            else {
+                const needle = a.query.toLowerCase();
+                test = (value) => value.toLowerCase().includes(needle);
+            }
+            const matches = parsed.records.filter((record) => test(`${record.id} ${record.kind} ${JSON.stringify(record.fields)}`));
+            const rows = matches.slice(0, a.limit).map((record) => `${record.kind}\t${record.id}`);
+            return text(`${matches.length} match(es)\n${rows.join("\n")}`.trim());
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("stats", `Numeric statistics for ${format.displayName} fields across all records.`, {
+        ...sourceArgs,
+        field: z.string().min(1).max(120).optional(),
+    }, async (a) => {
+        try {
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const stats = numericStats(parsed.records);
+            if (a.field) {
+                const one = stats[a.field];
+                if (!one)
+                    throw new ToolError(`Field ${a.field} has no numeric values. Numeric fields: ${Object.keys(stats).join(", ") || "none"}`);
+                return text(JSON.stringify({ [a.field]: { ...one, mean: round(one.mean) } }, null, 2));
+            }
+            const rounded = Object.fromEntries(Object.entries(stats).map(([key, value]) => [key, { ...value, mean: round(value.mean) }]));
+            return text(JSON.stringify(rounded, null, 2));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("to_json", `Export every parsed ${format.displayName} record as JSON. Premium: needs MCP_LICENSE_KEY.`, { ...sourceArgs }, async (a) => {
+        try {
+            if (PREMIUM.has("to_json")) {
+                const { body, file } = await readInput(a);
+                return text(await premiumTool("to_json", { format: format.slug, file: file ?? null, content: body }));
+            }
+            return fail("to_json is not configured");
+        }
+        catch (error) {
+            if (error instanceof GatewayError)
+                return fail(error.message);
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("diff", `Compare two ${format.displayName} documents: added, removed and changed records. Premium: needs MCP_LICENSE_KEY.`, {
+        leftPath: z.string().min(1).max(2_000).optional(),
+        leftContent: z.string().max(MAX_INPUT).optional(),
+        rightPath: z.string().min(1).max(2_000).optional(),
+        rightContent: z.string().max(MAX_INPUT).optional(),
+        cwd: z.string().min(1).max(2_000).optional(),
+    }, async (a) => {
+        try {
+            const left = await readInput({ path: a.leftPath, content: a.leftContent, cwd: a.cwd });
+            const right = await readInput({ path: a.rightPath, content: a.rightContent, cwd: a.cwd });
+            return text(await premiumTool("diff", {
+                format: format.slug,
+                left: left.body,
+                right: right.body,
+            }));
+        }
+        catch (error) {
+            if (error instanceof GatewayError)
+                return fail(error.message);
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("format_reference", `Return a compact ${format.displayName} reference: structure, required fields and common pitfalls.`, {}, async () => text(format.reference));
+    server.tool("sample", `Return a small but valid ${format.displayName} example document.`, {}, async () => text(format.sample()));
+}

package/dist/format.d.ts

@@ -0,0 +1,2 @@
+import type { FormatModule } from "./types.js";
+export declare const format: FormatModule;

package/dist/format.js

@@ -0,0 +1,95 @@
+import { scanTags, validateXml } from "./_xml.js";
+const INTERESTING = new Set([
+    "ContentStorage", "MasterMob", "SourceMob", "CompositionMob", "EssenceDescriptor",
+    "Identification", "TaggedValue", "Dictionary", "NetworkLocator", "Timecode", "Track",
+]);
+function parse(text) {
+    const issues = [];
+    validateXml(text, "AAF", "AAF", issues);
+    const tags = scanTags(text);
+    const records = [];
+    const mobIds = new Set();
+    let mobs = 0;
+    for (const tag of tags) {
+        if (tag.close)
+            continue;
+        if (tag.name.endsWith("Mob")) {
+            mobs += 1;
+            const mobId = tag.attrs.MobID ?? "";
+            if (!mobId) {
+                issues.push({ code: "mob-without-id", severity: "error", message: `${tag.name} has no MobID attribute`, line: tag.line });
+            }
+            else if (mobIds.has(mobId)) {
+                issues.push({ code: "duplicate-mob", severity: "error", message: `MobID ${mobId} is used twice`, line: tag.line });
+            }
+            mobIds.add(mobId);
+        }
+        if (!INTERESTING.has(tag.name))
+            continue;
+        records.push({
+            id: `${tag.name}:${tag.attrs.MobID ?? tag.attrs.Name ?? records.length + 1}`,
+            kind: tag.name,
+            fields: {
+                mobId: tag.attrs.MobID ?? "",
+                name: tag.attrs.Name ?? "",
+                value: tag.attrs.Value ?? "",
+                line: tag.line,
+            },
+        });
+    }
+    if (mobs === 0) {
+        issues.push({ code: "no-mobs", severity: "warning", message: "Document contains no Mob" });
+    }
+    if (!tags.some((tag) => tag.name === "ContentStorage")) {
+        issues.push({ code: "no-content-storage", severity: "warning", message: "Document has no ContentStorage element" });
+    }
+    return {
+        format: "AAF",
+        records,
+        meta: {
+            mobs,
+            taggedValues: records.filter((record) => record.kind === "TaggedValue").length,
+            essenceDescriptors: records.filter((record) => record.kind === "EssenceDescriptor").length,
+            elements: tags.filter((tag) => !tag.close).length,
+        },
+        issues,
+    };
+}
+const reference = [
+    "AAF-XML (Advanced Authoring Format, XML form)",
+    "",
+    "<?xml version=\"1.0\"?>",
+    "<AAF>",
+    "  <ContentStorage>",
+    "    <MasterMob MobID=\"060a2b34.01010101.01010f00.13000000\">",
+    "      <Identification>",
+    "        <TaggedValue Name=\"Title\" Value=\"Demo\"/>",
+    "      </Identification>",
+    "    </MasterMob>",
+    "  </ContentStorage>",
+    "</AAF>",
+    "",
+    "Mob elements (MasterMob, SourceMob, CompositionMob) need a unique MobID.",
+    "TaggedValue carries Name and Value pairs.",
+    "The binary AAF container is not text; this server reads the AAF-XML form.",
+].join("\n");
+export const format = {
+    slug: "aaf",
+    displayName: "AAF",
+    extensions: [".aafxml", ".xml"],
+    description: "Parse AAF-XML content storage, mobs and tagged values.",
+    reference,
+    parse,
+    sample: () => [
+        '<?xml version="1.0"?>',
+        "<AAF>",
+        "  <ContentStorage>",
+        '    <MasterMob MobID="060a2b34.01010101.01010f00.13000000">',
+        "      <Identification>",
+        '        <TaggedValue Name="Title" Value="Demo"/>',
+        "      </Identification>",
+        "    </MasterMob>",
+        "  </ContentStorage>",
+        "</AAF>",
+    ].join("\n") + "\n",
+};

package/dist/gateway.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * Premium tool bodies run on the gateway, which checks a Polar licence key
+ * before it does any work, so removing anything here buys nothing.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+export declare class GatewayError extends Error {
+    readonly refused: boolean;
+    constructor(message: string, refused: boolean);
+}
+export declare function premiumTool(tool: string, args: Record<string, unknown>): Promise<string>;

package/dist/gateway.js

@@ -0,0 +1,78 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * Premium tool bodies run on the gateway, which checks a Polar licence key
+ * before it does any work, so removing anything here buys nothing.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+const DEFAULT_GATEWAY_URL = "https://mcp-gateway.contactae2000.workers.dev/mcp";
+const DEFAULT_TIMEOUT_MS = 25000;
+const USER_AGENT = "mrfentmen-mcp/1.0";
+export class GatewayError extends Error {
+    refused;
+    constructor(message, refused) {
+        super(message);
+        this.refused = refused;
+        this.name = "GatewayError";
+    }
+}
+export async function premiumTool(tool, args) {
+    const key = (process.env.MCP_LICENSE_KEY ?? "").trim();
+    if (!key) {
+        throw new GatewayError(`"${tool}" is a premium tool and no licence key is set. Set MCP_LICENSE_KEY in your MCP client config.`, true);
+    }
+    const url = (process.env.MCP_GATEWAY_URL ?? DEFAULT_GATEWAY_URL).trim();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+                "user-agent": USER_AGENT,
+                authorization: `Bearer ${key}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "tools/call",
+                params: { name: tool, arguments: args },
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway. Check your connection and try again.`, false);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway (HTTP ${response.status}).`, false);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        throw new GatewayError(`"${tool}" got an unreadable answer from the licence gateway.`, false);
+    }
+    if (body.error) {
+        throw new GatewayError(`"${tool}" was refused by the licence gateway: ${body.error.message ?? "unknown error"}`, false);
+    }
+    const result = body.result ?? {};
+    const text = (result.content ?? []).map((part) => part.text ?? "").join("\n").trim();
+    if (result.isError) {
+        if (result.structuredContent?.licenceRefusal) {
+            throw new GatewayError(text || `"${tool}" needs a valid licence key.`, true);
+        }
+        throw new GatewayError(text || `"${tool}" failed on the licence gateway.`, false);
+    }
+    if (!text)
+        throw new GatewayError(`"${tool}" returned no data.`, false);
+    return text;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+});

package/dist/run.d.ts

@@ -0,0 +1,17 @@
+export declare class ToolError extends Error {
+    constructor(message: string);
+}
+export declare function errorMessage(error: unknown): string;
+export declare function text(value: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function fail(message: string): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/run.js

@@ -0,0 +1,15 @@
+export class ToolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolError";
+    }
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function text(value) {
+    return { content: [{ type: "text", text: value }] };
+}
+export function fail(message) {
+    return { isError: true, content: [{ type: "text", text: message }] };
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const VERSION = "1.0.0";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { format } from "./format.js";
+import { registerFormatTools } from "./core.js";
+export const VERSION = "1.0.0";
+export function createServer() {
+    const server = new McpServer({ name: `${format.slug}-mcp`, version: VERSION });
+    registerFormatTools(server, format);
+    return server;
+}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+export type Severity = "error" | "warning";
+export interface Issue {
+    code: string;
+    severity: Severity;
+    message: string;
+    line?: number;
+}
+export interface ParsedRecord {
+    id: string;
+    kind: string;
+    fields: Record<string, string | number | boolean | null>;
+}
+export interface Parsed {
+    format: string;
+    records: ParsedRecord[];
+    meta: Record<string, string | number | boolean | null>;
+    issues: Issue[];
+}
+export interface FormatModule {
+    slug: string;
+    displayName: string;
+    extensions: string[];
+    description: string;
+    reference: string;
+    parse(text: string): Parsed;
+    sample(): string;
+    regressions?: Array<{
+        doc: string;
+        expectError: string;
+    }>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@mrfentmen/aaf-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "AAF MCP: parse AAF-XML content storage, mobs and tagged values.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/aaf-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "aaf-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test tests/tools.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "aaf",
+    "media",
+    "post-production",
+    "interchange",
+    "mob"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mrfentmen/aaf-mcp",
+  "description": "AAF MCP: parse AAF-XML content storage, mobs and tagged values.",
+  "repository": {
+    "url": "https://github.com/mrfentmen/awesome-servers",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@mrfentmen/aaf-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}