@hadialmarzooq/agent-media-mcp 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +42 -6
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -4,7 +4,7 @@ MCP server for semantic, replayable, and verified media transformations.
4
4
 
5
5
  ## What it does
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  ## Install
10
10
 
@@ -21,14 +21,23 @@ Prerequisites: Node.js 22+, `ffmpeg` and `ffprobe` on `PATH`.
21
21
  | `inspect_media` | Inspect normalized media metadata |
22
22
  | `get_media_capabilities` | Detect local FFmpeg capabilities |
23
23
  | `plan_media` | Create an inspectable versioned Media IR plan |
24
+ | `validate_plan` | Report mechanical plan issues without executing |
25
+ | `repair_plan` | Repair a plan and report every change made |
26
+ | `get_media_plan_schema` | The canonical Media IR JSON Schema |
24
27
  | `make_vertical` | Verified 9:16 vertical workflow with progress |
25
28
  | `optimize_for_web` | Verified web optimization workflow with progress |
26
29
  | `normalize_media` | Verified high-compatibility normalization with progress |
27
30
  | `extract_audio` | Verified audio extraction with progress |
28
31
  | `extract_frame` | Verified still frame extraction with progress |
32
+ | `concatenate_media` | Verified concatenation of two or more clips |
29
33
  | `execute_media_plan` | Execute a serialized or object Media IR plan |
34
+ | `resume_execution` | Continue from a saved execution receipt |
35
+ | `inspect_receipt` | Validate and read a saved receipt |
30
36
  | `verify_media` | Verify output against plan expectations |
31
37
 
38
+ Every tool declares an `outputSchema` and returns `structuredContent`. Read-only tools carry
39
+ `readOnlyHint`; writer tools carry `destructiveHint`.
40
+
32
41
  ## Usage
33
42
 
34
43
  ### Claude Desktop
@@ -39,29 +48,56 @@ Add to `claude_desktop_config.json`:
39
48
  {
40
49
  "mcpServers": {
41
50
  "agent-media": {
42
- "command": "agent-media-mcp"
51
+ "command": "agent-media-mcp",
52
+ "env": { "AGENT_MEDIA_ALLOWED_OUTPUT_DIR": "/Users/you/Movies/agent-output" }
43
53
  }
44
54
  }
45
55
  }
46
56
  ```
47
57
 
58
+ ### Claude Code
59
+
60
+ ```bash
61
+ claude mcp add agent-media -- agent-media-mcp
62
+ ```
63
+
48
64
  ### Any MCP client
49
65
 
50
66
  ```bash
51
67
  agent-media-mcp
52
68
  ```
53
69
 
54
- 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.
70
+ The server runs over stdio. Workflows send standard MCP `notifications/progress` when the client
71
+ supplies a progress token, and honour client cancellation. Plan execution and verification accept
72
+ either a plan object or serialized plan JSON. Tool failures set `isError: true` and carry the same
73
+ structured error body as the SDK and CLI.
74
+
75
+ ## Limits the operator sets
76
+
77
+ Limits come from the environment, so they belong to whoever runs the server rather than to the model
78
+ calling it. No tool accepts them as an argument, so nothing the model sends can widen them.
79
+
80
+ | Variable | Effect |
81
+ | -------------------------------- | --------------------------------------------------------- |
82
+ | `AGENT_MEDIA_ALLOWED_OUTPUT_DIR` | writes outside this tree fail with `PATH_NOT_ALLOWED` |
83
+ | `AGENT_MEDIA_TIMEOUT_MS` | any FFmpeg run beyond this fails with `OPERATION_TIMEOUT` |
84
+ | `AGENT_MEDIA_FFMPEG_PATH` | an `ffmpeg` that is not on `PATH` |
85
+ | `AGENT_MEDIA_FFPROBE_PATH` | an `ffprobe` that is not on `PATH` |
86
+
87
+ Without a timeout override, probes get 30 seconds and encodes get 30 minutes.
55
88
 
56
89
  ## Why this instead of raw FFmpeg MCP wrappers
57
90
 
58
- - **5 semantic workflows** instead of 40+ FFmpeg-shaped tools
59
- - **Verification** — outputs are inspected and checked against plan expectations, not just "exit code 0"
60
- - **Portable plans** — serialize, persist, replay, audit
91
+ - **Semantic workflows** instead of an FFmpeg-shaped tool per flag
92
+ - **Verification** — outputs are re-inspected and checked against plan expectations, not just "exit code 0"
93
+ - **Content checks** — black frames, silence, frozen video, and whether every stream decodes
94
+ - **Portable plans** — serialize, persist, replay, audit; each step records why it exists
95
+ - **Receipts** — a durable record of every run, so a retry skips work that is already correct
61
96
  - **Structured errors** — stable codes with recovery suggestions, not stderr noise
62
97
 
63
98
  ## Documentation
64
99
 
100
+ - [Usage guide](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/usage.md)
65
101
  - [Full docs](https://github.com/HadiAlMarzooq/agent-media/tree/main/docs)
66
102
  - [Workflows](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/workflows.md)
67
103
  - [API reference](https://github.com/HadiAlMarzooq/agent-media/blob/main/docs/api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hadialmarzooq/agent-media-mcp",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "MCP server for semantic, replayable, and verified media transformations.",
5
5
  "keywords": [
6
6
  "media",
@@ -39,8 +39,8 @@
39
39
  "dependencies": {
40
40
  "@modelcontextprotocol/sdk": "1.30.0",
41
41
  "zod": "^4.5.4",
42
- "@hadialmarzooq/agent-media-core": "0.3.0",
43
- "@hadialmarzooq/agent-media-ffmpeg": "0.4.0"
42
+ "@hadialmarzooq/agent-media-ffmpeg": "0.4.1",
43
+ "@hadialmarzooq/agent-media-core": "0.3.1"
44
44
  },
45
45
  "scripts": {
46
46
  "build": "tsup src/index.ts --format esm --dts",