@hadialmarzooq/agent-media-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hadi Almarzooq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+declare function createMcpServer(): McpServer;
+declare function startMcpServer(): Promise<void>;
+
+export { createMcpServer, startMcpServer };

package/dist/index.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createRequire } from "module";
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  MediaError,
+  mediaPlanSchema,
+  parsePlan,
+  planMedia,
+  validatePlan,
+  verifyMedia
+} from "@hadialmarzooq/agent-media-core";
+import {
+  executePlan,
+  getCapabilities,
+  inspectMedia,
+  makeVertical,
+  optimizeForWeb,
+  normalize,
+  extractAudio,
+  extractFrame
+} from "@hadialmarzooq/agent-media-ffmpeg";
+import { z } from "zod";
+var packageVersion = createRequire(import.meta.url)("../package.json").version;
+var goalSchema = z.object({
+  trimStartSeconds: z.number().nonnegative().optional(),
+  durationSeconds: z.number().positive().optional(),
+  aspectRatio: z.string().optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  maxSizeMB: z.number().positive().optional(),
+  compatibility: z.enum(["high", "balanced"]).optional(),
+  quality: z.enum(["high", "balanced", "small"]).optional(),
+  audio: z.enum(["preserve", "remove"]).optional()
+});
+function createMcpServer() {
+  const server = new McpServer({ name: "agent-media", version: packageVersion });
+  server.registerTool(
+    "inspect_media",
+    {
+      description: "Inspect normalized media metadata.",
+      inputSchema: { input: z.string().min(1) }
+    },
+    async ({ input }) => safely(async () => inspectMedia(input))
+  );
+  server.registerTool(
+    "get_media_capabilities",
+    { description: "Detect local FFmpeg capabilities." },
+    async () => safely(getCapabilities)
+  );
+  server.registerTool(
+    "plan_media",
+    {
+      description: "Create an inspectable versioned semantic Media IR plan.",
+      inputSchema: { input: z.string().min(1), goals: goalSchema }
+    },
+    async ({ input, goals }) => safely(async () => ({
+      plan: planMedia({
+        source: await inspectMedia(input),
+        goals: cleanGoals(goals),
+        capabilities: await getCapabilities()
+      })
+    }))
+  );
+  server.registerTool(
+    "make_vertical",
+    {
+      description: "Inspect, plan, execute, and verify a high-compatibility 9:16 video. Reports MCP progress when requested.",
+      inputSchema: {
+        input: z.string().min(1),
+        output: z.string().min(1),
+        width: z.number().int().positive().optional(),
+        height: z.number().int().positive().optional(),
+        trimStartSeconds: z.number().nonnegative().optional(),
+        durationSeconds: z.number().positive().optional(),
+        maxSizeMB: z.number().positive().optional(),
+        audio: z.enum(["preserve", "remove"]).optional(),
+        overwrite: z.boolean().optional()
+      }
+    },
+    async (options, extra) => {
+      const notifications = mcpProgress(extra);
+      const response = await safely(
+        async () => makeVertical({
+          input: options.input,
+          output: options.output,
+          ...options.width === void 0 ? {} : { width: options.width },
+          ...options.height === void 0 ? {} : { height: options.height },
+          ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+          ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds },
+          ...options.maxSizeMB === void 0 ? {} : { maxSizeMB: options.maxSizeMB },
+          ...options.audio === void 0 ? {} : { audio: options.audio },
+          ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
+          signal: extra.signal,
+          onProgress: notifications.notify
+        })
+      );
+      await notifications.drain();
+      return response;
+    }
+  );
+  server.registerTool(
+    "optimize_for_web",
+    {
+      description: "Inspect, plan, execute, and verify a web-optimized high-compatibility video. Reports MCP progress when requested.",
+      inputSchema: {
+        input: z.string().min(1),
+        output: z.string().min(1),
+        trimStartSeconds: z.number().nonnegative().optional(),
+        durationSeconds: z.number().positive().optional(),
+        maxSizeMB: z.number().positive().optional(),
+        quality: z.enum(["high", "balanced", "small"]).optional(),
+        audio: z.enum(["preserve", "remove"]).optional(),
+        overwrite: z.boolean().optional()
+      }
+    },
+    async (options, extra) => {
+      const notifications = mcpProgress(extra);
+      const response = await safely(
+        async () => optimizeForWeb({
+          input: options.input,
+          output: options.output,
+          ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+          ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds },
+          ...options.maxSizeMB === void 0 ? {} : { maxSizeMB: options.maxSizeMB },
+          ...options.quality === void 0 ? {} : { quality: options.quality },
+          ...options.audio === void 0 ? {} : { audio: options.audio },
+          ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
+          signal: extra.signal,
+          onProgress: notifications.notify
+        })
+      );
+      await notifications.drain();
+      return response;
+    }
+  );
+  server.registerTool(
+    "normalize_media",
+    {
+      description: "Inspect, plan, execute, and verify a normalized high-compatibility copy (H.264, yuv420p, faststart). Reports MCP progress when requested.",
+      inputSchema: {
+        input: z.string().min(1),
+        output: z.string().min(1),
+        trimStartSeconds: z.number().nonnegative().optional(),
+        durationSeconds: z.number().positive().optional(),
+        audio: z.enum(["preserve", "remove"]).optional(),
+        overwrite: z.boolean().optional()
+      }
+    },
+    async (options, extra) => {
+      const notifications = mcpProgress(extra);
+      const response = await safely(
+        async () => normalize({
+          input: options.input,
+          output: options.output,
+          ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+          ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds },
+          ...options.audio === void 0 ? {} : { audio: options.audio },
+          ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
+          signal: extra.signal,
+          onProgress: notifications.notify
+        })
+      );
+      await notifications.drain();
+      return response;
+    }
+  );
+  server.registerTool(
+    "extract_audio",
+    {
+      description: "Extract and verify audio from any media source. Reports MCP progress when requested.",
+      inputSchema: {
+        input: z.string().min(1),
+        output: z.string().min(1),
+        format: z.enum(["m4a", "mp3", "wav"]).optional(),
+        trimStartSeconds: z.number().nonnegative().optional(),
+        durationSeconds: z.number().positive().optional(),
+        overwrite: z.boolean().optional()
+      }
+    },
+    async (options, extra) => {
+      const notifications = mcpProgress(extra);
+      const response = await safely(
+        async () => extractAudio({
+          input: options.input,
+          output: options.output,
+          ...options.format === void 0 ? {} : { format: options.format },
+          ...options.trimStartSeconds === void 0 ? {} : { trimStartSeconds: options.trimStartSeconds },
+          ...options.durationSeconds === void 0 ? {} : { durationSeconds: options.durationSeconds },
+          ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
+          signal: extra.signal,
+          onProgress: notifications.notify
+        })
+      );
+      await notifications.drain();
+      return response;
+    }
+  );
+  server.registerTool(
+    "extract_frame",
+    {
+      description: "Extract and verify a still frame from a video source. Reports MCP progress when requested.",
+      inputSchema: {
+        input: z.string().min(1),
+        output: z.string().min(1),
+        atSeconds: z.number().nonnegative().optional(),
+        format: z.enum(["jpg", "png"]).optional(),
+        overwrite: z.boolean().optional()
+      }
+    },
+    async (options, extra) => {
+      const notifications = mcpProgress(extra);
+      const response = await safely(
+        async () => extractFrame({
+          input: options.input,
+          output: options.output,
+          ...options.atSeconds === void 0 ? {} : { atSeconds: options.atSeconds },
+          ...options.format === void 0 ? {} : { format: options.format },
+          ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
+          signal: extra.signal,
+          onProgress: notifications.notify
+        })
+      );
+      await notifications.drain();
+      return response;
+    }
+  );
+  server.registerTool(
+    "execute_media_plan",
+    {
+      description: "Execute a serialized semantic Media IR plan.",
+      inputSchema: {
+        plan: z.union([z.string().min(1), mediaPlanSchema]),
+        output: z.string().min(1),
+        overwrite: z.boolean().optional()
+      }
+    },
+    async ({ plan: input, output, overwrite }, extra) => {
+      const notifications = mcpProgress(extra);
+      const response = await safely(async () => {
+        const plan = normalizePlan(input);
+        const execution = await executePlan(plan, {
+          output,
+          ...overwrite === void 0 ? {} : { overwrite },
+          signal: extra.signal,
+          onProgress: notifications.notify
+        });
+        return {
+          output: execution.output,
+          verification: verifyMedia(await inspectMedia(execution.output), plan.expectations)
+        };
+      });
+      await notifications.drain();
+      return response;
+    }
+  );
+  server.registerTool(
+    "verify_media",
+    {
+      description: "Verify output media against a serialized semantic Media IR plan.",
+      inputSchema: {
+        output: z.string().min(1),
+        plan: z.union([z.string().min(1), mediaPlanSchema])
+      }
+    },
+    async ({ output, plan: input }) => safely(async () => {
+      const plan = normalizePlan(input);
+      return verifyMedia(await inspectMedia(output), plan.expectations);
+    })
+  );
+  return server;
+}
+function result(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+async function safely(operation) {
+  try {
+    return result(await operation());
+  } catch (error) {
+    const structured = error instanceof MediaError ? error.toJSON() : {
+      code: "UNEXPECTED_ERROR",
+      message: error instanceof Error ? error.message : String(error)
+    };
+    return { ...result(structured), isError: true };
+  }
+}
+function normalizePlan(input) {
+  return typeof input === "string" ? parsePlan(input) : validatePlan(input);
+}
+function cleanGoals(goals) {
+  return cleanObject(goals);
+}
+function cleanObject(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
+function mcpProgress(extra) {
+  const progressToken = extra._meta?.progressToken;
+  let pending = Promise.resolve();
+  return {
+    notify: (progress) => {
+      if (progressToken === void 0) return;
+      pending = pending.then(
+        () => extra.sendNotification({
+          method: "notifications/progress",
+          params: {
+            progressToken,
+            progress: progress.percent,
+            total: 100,
+            message: `${progress.phase}: ${progress.message}`
+          }
+        })
+      ).catch(() => void 0);
+    },
+    drain: () => pending
+  };
+}
+async function startMcpServer() {
+  await createMcpServer().connect(new StdioServerTransport());
+}
+if (isMainModule()) {
+  startMcpServer().catch((error) => {
+    const output = error instanceof MediaError ? error.toJSON() : {
+      code: "UNEXPECTED_ERROR",
+      message: error instanceof Error ? error.message : String(error)
+    };
+    process.stderr.write(`${JSON.stringify(output)}
+`);
+    process.exitCode = 1;
+  });
+}
+function isMainModule() {
+  if (process.argv[1] === void 0) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+export {
+  createMcpServer,
+  startMcpServer
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hadialmarzooq/agent-media-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for semantic, replayable, and verified media transformations.",
+  "keywords": [
+    "media",
+    "agents",
+    "ffmpeg",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "homepage": "https://github.com/HadiAlMarzooq/agent-media#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HadiAlMarzooq/agent-media.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/HadiAlMarzooq/agent-media/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "type": "module",
+  "bin": {
+    "agent-media-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "^4.5.4",
+    "@hadialmarzooq/agent-media-ffmpeg": "0.1.0",
+    "@hadialmarzooq/agent-media-core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit"
+  }
+}