@hadialmarzooq/agent-media-mcp 0.3.0 → 0.4.1

package/README.md

@@ -4,7 +4,7 @@ MCP server for semantic, replayable, and verified media transformations.
 
 ## What it does
 
-A [Model Context Protocol](https://modelcontextprotocol.io) stdio server that exposes [Agent Media](https://github.com/HadiAlMarzooq/agent-media) to AI agents. Ten semantic tools covering the full inspect → plan → execute → verify contract.
+A [Model Context Protocol](https://modelcontextprotocol.io) stdio server that exposes [Agent Media](https://github.com/HadiAlMarzooq/agent-media) to AI agents. Sixteen semantic tools covering the full inspect → plan → execute → verify contract, plus plan repair, durable receipts, and content checks.
 
 ## Install
 
@@ -21,14 +21,23 @@ Prerequisites: Node.js 22+, `ffmpeg` and `ffprobe` on `PATH`.
 | `inspect_media`          | Inspect normalized media metadata                       |
 | `get_media_capabilities` | Detect local FFmpeg capabilities                        |
 | `plan_media`             | Create an inspectable versioned Media IR plan           |
+| `validate_plan`          | Report mechanical plan issues without executing         |
+| `repair_plan`            | Repair a plan and report every change made              |
+| `get_media_plan_schema`  | The canonical Media IR JSON Schema                      |
 | `make_vertical`          | Verified 9:16 vertical workflow with progress           |
 | `optimize_for_web`       | Verified web optimization workflow with progress        |
 | `normalize_media`        | Verified high-compatibility normalization with progress |
 | `extract_audio`          | Verified audio extraction with progress                 |
 | `extract_frame`          | Verified still frame extraction with progress           |
+| `concatenate_media`      | Verified concatenation of two or more clips             |
 | `execute_media_plan`     | Execute a serialized or object Media IR plan            |
+| `resume_execution`       | Continue from a saved execution receipt                 |
+| `inspect_receipt`        | Validate and read a saved receipt                       |
 | `verify_media`           | Verify output against plan expectations                 |
 
+Every tool declares an `outputSchema` and returns `structuredContent`. Read-only tools carry
+`readOnlyHint`; writer tools carry `destructiveHint`.
+
 ## Usage
 
 ### Claude Desktop
@@ -39,29 +48,56 @@ Add to `claude_desktop_config.json`:
 {
   "mcpServers": {
     "agent-media": {
-      "command": "agent-media-mcp"
+      "command": "agent-media-mcp",
+      "env": { "AGENT_MEDIA_ALLOWED_OUTPUT_DIR": "/Users/you/Movies/agent-output" }
     }
   }
 }
 ```
 
+### Claude Code
+
+```bash
+claude mcp add agent-media -- agent-media-mcp
+```
+
 ### Any MCP client
 
 ```bash
 agent-media-mcp
 ```
 
-The server runs over stdio. Workflows send standard MCP `notifications/progress` when the client supplies a progress token. Plan execution and verification accept either a plan object or serialized plan JSON. Tool failures set `isError: true` and carry the same structured error body as the SDK and CLI.
+The server runs over stdio. Workflows send standard MCP `notifications/progress` when the client
+supplies a progress token, and honour client cancellation. Plan execution and verification accept
+either a plan object or serialized plan JSON. Tool failures set `isError: true` and carry the same
+structured error body as the SDK and CLI.
+
+## Limits the operator sets
+
+Limits come from the environment, so they belong to whoever runs the server rather than to the model
+calling it. No tool accepts them as an argument, so nothing the model sends can widen them.
+
+| Variable                         | Effect                                                    |
+| -------------------------------- | --------------------------------------------------------- |
+| `AGENT_MEDIA_ALLOWED_OUTPUT_DIR` | writes outside this tree fail with `PATH_NOT_ALLOWED`     |
+| `AGENT_MEDIA_TIMEOUT_MS`         | any FFmpeg run beyond this fails with `OPERATION_TIMEOUT` |
+| `AGENT_MEDIA_FFMPEG_PATH`        | an `ffmpeg` that is not on `PATH`                         |
+| `AGENT_MEDIA_FFPROBE_PATH`       | an `ffprobe` that is not on `PATH`                        |
+
+Without a timeout override, probes get 30 seconds and encodes get 30 minutes.
 
 ## Why this instead of raw FFmpeg MCP wrappers
 
-- **5 semantic workflows** instead of 40+ FFmpeg-shaped tools
-- **Verification** — outputs are inspected and checked against plan expectations, not just "exit code 0"
-- **Portable plans** — serialize, persist, replay, audit
+- **Semantic workflows** instead of an FFmpeg-shaped tool per flag
+- **Verification** — outputs are re-inspected and checked against plan expectations, not just "exit code 0"
+- **Content checks** — black frames, silence, frozen video, and whether every stream decodes
+- **Portable plans** — serialize, persist, replay, audit; each step records why it exists
+- **Receipts** — a durable record of every run, so a retry skips work that is already correct
 - **Structured errors** — stable codes with recovery suggestions, not stderr noise
 
 ## Documentation
 
+- [Usage guide](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/usage.md)
 - [Full docs](https://github.com/HadiAlMarzooq/agent-media/tree/main/docs)
 - [Workflows](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/workflows.md)
 - [API reference](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/api.md)

package/dist/index.js

@@ -28,6 +28,7 @@ import {
   inspectMedia,
   makeVertical,
   normalize,
+  operatorLimits,
   optimizeForWeb
 } from "@hadialmarzooq/agent-media-ffmpeg";
 import { z } from "zod";
@@ -140,6 +141,11 @@ var readOnlyHint = { readOnlyHint: true };
 var destructiveHint = { destructiveHint: true };
 function createMcpServer() {
   const server = new McpServer({ name: "agent-media", version: packageVersion });
+  const limits = operatorLimits();
+  const probeOptions = {
+    ...limits.ffprobePath === void 0 ? {} : { ffprobePath: limits.ffprobePath },
+    ...limits.timeoutMs === void 0 ? {} : { timeoutMs: limits.timeoutMs }
+  };
   server.registerTool(
     "inspect_media",
     {
@@ -148,7 +154,7 @@ function createMcpServer() {
       outputSchema: mediaMetadataShape,
       annotations: readOnlyHint
     },
-    async ({ input }) => safely(async () => inspectMedia(input))
+    async ({ input }) => safely(async () => inspectMedia(input, probeOptions))
   );
   server.registerTool(
     "get_media_capabilities",
@@ -184,9 +190,9 @@ function createMcpServer() {
     },
     async ({ input, goals }) => safely(async () => ({
       plan: planMedia({
-        source: await inspectMedia(input),
+        source: await inspectMedia(input, probeOptions),
         goals: cleanGoals(validateGoalSchema(goals)),
-        capabilities: await getCapabilities()
+        capabilities: await getCapabilities(probeOptions)
       })
     }))
   );
@@ -217,8 +223,8 @@ function createMcpServer() {
     },
     async ({ plan: input }) => safely(async () => {
       const plan = normalizePlan(input);
-      const source = await inspectMedia(plan.source.path);
-      const concatenationSources = await inspectConcatenationSources(plan, source);
+      const source = await inspectMedia(plan.source.path, probeOptions);
+      const concatenationSources = await inspectConcatenationSources(plan, source, probeOptions);
       return {
         issues: inspectPlanIssues(plan, source, {
           ...concatenationSources === void 0 ? {} : { concatenationSources }
@@ -248,7 +254,10 @@ function createMcpServer() {
     },
     async ({ plan: input }) => safely(async () => {
       const plan = normalizePlan(input);
-      const { plan: repaired, repairs } = repairPlan(plan, await inspectMedia(plan.source.path));
+      const { plan: repaired, repairs } = repairPlan(
+        plan,
+        await inspectMedia(plan.source.path, probeOptions)
+      );
       return { repairs, repairedPlan: repaired };
     })
   );
@@ -299,6 +308,7 @@ function createMcpServer() {
             ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
             ...contentCheckOptions(options.contentChecks),
             ...options.warnOnly === void 0 ? {} : { warnOnly: options.warnOnly },
+            ...limits,
             signal: extra.signal,
             onProgress: notifications.notify
           })
@@ -341,6 +351,7 @@ function createMcpServer() {
             ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
             ...contentCheckOptions(options.contentChecks),
             ...options.warnOnly === void 0 ? {} : { warnOnly: options.warnOnly },
+            ...limits,
             signal: extra.signal,
             onProgress: notifications.notify
           })
@@ -379,6 +390,7 @@ function createMcpServer() {
             ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
             ...contentCheckOptions(options.contentChecks),
             ...options.warnOnly === void 0 ? {} : { warnOnly: options.warnOnly },
+            ...limits,
             signal: extra.signal,
             onProgress: notifications.notify
           })
@@ -417,6 +429,7 @@ function createMcpServer() {
             ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
             ...contentCheckOptions(options.contentChecks),
             ...options.warnOnly === void 0 ? {} : { warnOnly: options.warnOnly },
+            ...limits,
             signal: extra.signal,
             onProgress: notifications.notify
           })
@@ -453,6 +466,7 @@ function createMcpServer() {
             ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
             ...contentCheckOptions(options.contentChecks),
             ...options.warnOnly === void 0 ? {} : { warnOnly: options.warnOnly },
+            ...limits,
             signal: extra.signal,
             onProgress: notifications.notify
           })
@@ -485,6 +499,7 @@ function createMcpServer() {
             ...options.overwrite === void 0 ? {} : { overwrite: options.overwrite },
             ...contentCheckOptions(options.contentChecks),
             ...options.warnOnly === void 0 ? {} : { warnOnly: options.warnOnly },
+            ...limits,
             signal: extra.signal,
             onProgress: notifications.notify
           })
@@ -519,6 +534,7 @@ function createMcpServer() {
       const response = await safely(async () => {
         const plan = normalizePlan(input);
         const execution = await executePlan(plan, {
+          ...limits,
           output,
           ...overwrite === void 0 ? {} : { overwrite },
           ...writeReceipt === void 0 ? {} : { writeReceipt },
@@ -528,7 +544,7 @@ function createMcpServer() {
           signal: extra.signal,
           onProgress: notifications.notify
         });
-        const verification = execution.verification ?? execution.receipt?.verification ?? verifyMedia(await inspectMedia(execution.output), plan.expectations);
+        const verification = execution.verification ?? execution.receipt?.verification ?? verifyMedia(await inspectMedia(execution.output, probeOptions), plan.expectations);
         if (!verification.passed) {
           throw new MediaError({
             code: "VERIFICATION_FAILED",
@@ -568,6 +584,7 @@ function createMcpServer() {
       const notifications = mcpProgress(extra);
       const response = await safely(async () => {
         const execution = await resumeFromReceipt(parseReceipt(receipt), {
+          ...limits,
           ...output === void 0 ? {} : { output },
           ...overwrite === void 0 ? {} : { overwrite },
           signal: extra.signal,
@@ -606,7 +623,7 @@ function createMcpServer() {
     },
     async ({ output, plan: input }) => safely(async () => {
       const plan = normalizePlan(input);
-      return verifyMedia(await inspectMedia(output), plan.expectations);
+      return verifyMedia(await inspectMedia(output, probeOptions), plan.expectations);
     })
   );
   return server;
@@ -637,12 +654,12 @@ async function safely(operation) {
     };
   }
 }
-async function inspectConcatenationSources(plan, source) {
+async function inspectConcatenationSources(plan, source, probeOptions) {
   const concatenate2 = plan.steps.find((step) => step.operation === "concatenate");
   if (concatenate2?.operation !== "concatenate") return void 0;
   const sources = [];
   for (const [index, input] of concatenate2.inputs.entries()) {
-    sources.push(index === 0 ? source : await inspectMedia(input));
+    sources.push(index === 0 ? source : await inspectMedia(input, probeOptions));
   }
   return sources;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadialmarzooq/agent-media-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "MCP server for semantic, replayable, and verified media transformations.",
   "keywords": [
     "media",
@@ -39,8 +39,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "zod": "^4.5.4",
-    "@hadialmarzooq/agent-media-core": "0.3.0",
-    "@hadialmarzooq/agent-media-ffmpeg": "0.3.0"
+    "@hadialmarzooq/agent-media-ffmpeg": "0.4.1",
+    "@hadialmarzooq/agent-media-core": "0.3.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",