@instavar/mcp-server 0.3.0 → 0.5.0

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 (3) hide show
  1. package/README.md +107 -15
  2. package/dist/index.js +1390 -120
  3. package/package.json +10 -3
package/README.md CHANGED
@@ -4,19 +4,62 @@
4
4
  [![npm](https://img.shields.io/npm/v/%40instavar%2Fmcp-server)](https://www.npmjs.com/package/@instavar/mcp-server)
5
5
  [![Glama score](https://glama.ai/mcp/servers/instavar/mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/instavar/mcp-server)
6
6
 
7
- Drive the full [Instavar Studio](https://instavar.com) video workflow —
8
- **create → render → approve → publish → metrics** — from Claude Code or Codex,
9
- without leaving your terminal.
7
+ One MCP package starts free and grows with the work. Make local videos with
8
+ Instavar's independent, open-source templates for Remotion from Claude Code or
9
+ Codex without an account or API key.
10
10
 
11
- The server is a thin HTTP client: it authenticates with a per-user API key and
12
- talks to the hosted Instavar API. It holds **no database connection** and stores
13
- no data of its own.
11
+ Instavar is an independent project and is not affiliated with, sponsored by, or
12
+ endorsed by Remotion AG. Remotion is a trademark of Remotion AG.
13
+
14
+ Add an Instavar API key when you want the hosted workflow:
15
+ **create → render → approve → publish → metrics**. The authenticated tools are
16
+ thin HTTP clients to the hosted Instavar API. The package holds **no database
17
+ connection** and stores no data of its own. You keep the free tools and do not
18
+ install a second server.
19
+
20
+ ## Which model runs?
21
+
22
+ The MCP host supplies the general-purpose LLM.
23
+
24
+ - In Claude Code, the selected Claude model interprets the request and calls
25
+ Instavar tools.
26
+ - In Codex, the selected OpenAI model interprets the request and calls the same
27
+ tools.
28
+ - Other compatible hosts use their own selected model and authentication.
29
+
30
+ The MCP server does not provide Sonnet, GPT, or another general-purpose model.
31
+ It exposes typed Instavar capabilities to the model already running in the
32
+ user's host. Depending on the host and sign-in method, that model usage may draw
33
+ from a personal or workspace subscription, separate usage credits, or API
34
+ billing. Those provider rules can change.
35
+
36
+ Local Remotion rendering uses your own machine. Instavar meters or charges its
37
+ hosted services, including rendering,
38
+ storage, specialist media generation, QA, publishing, and other declared job
39
+ costs. Using a subscription-backed agent does not make those services free.
40
+
41
+ For the full architecture, see
42
+ [`docs/architecture/studio-agent-workflow-architecture.md`](../../docs/architecture/studio-agent-workflow-architecture.md).
43
+ For dated provider evidence, see
44
+ [`reports/research/subscription-backed-agent-runtime-2026-07-10.md`](../../reports/research/subscription-backed-agent-runtime-2026-07-10.md).
14
45
 
15
46
  ## Setup
16
47
 
17
- 1. Create an API key at **https://instavar.com/studio/settings** (shown once —
18
- copy it).
19
- 2. Add the server to your MCP client config:
48
+ Add the server to your MCP client config:
49
+
50
+ ```json
51
+ {
52
+ "mcpServers": {
53
+ "instavar": {
54
+ "command": "npx",
55
+ "args": ["-y", "@instavar/mcp-server"]
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ This starts with the free local template tools. To unlock hosted Studio tools,
62
+ create an API key at **https://instavar.com/studio/settings**, then add it:
20
63
 
21
64
  ```json
22
65
  {
@@ -30,32 +73,66 @@ no data of its own.
30
73
  }
31
74
  ```
32
75
 
33
- 3. Restart the client. The `instavar` tools appear.
76
+ Restart the client. The free tools appear in both modes. Hosted tools appear
77
+ when the key is configured.
34
78
 
35
79
  ### Environment
36
80
 
37
- | Var | Required | Default | Purpose |
38
- | ------------------- | -------- | ---------------------- | ---------------------------------------------------------------- |
39
- | `INSTAVAR_API_KEY` | yes | — | Your key from `/studio/settings`. Scoped to your org; revocable. |
40
- | `INSTAVAR_BASE_URL` | no | `https://instavar.com` | Override the API host. |
81
+ | Var | Required | Default | Purpose |
82
+ | ------------------- | -------- | ---------------------- | ----------------------------------------------------------- |
83
+ | `INSTAVAR_API_KEY` | no | — | Unlocks hosted Studio tools. Scoped to your org; revocable. |
84
+ | `INSTAVAR_BASE_URL` | no | `https://instavar.com` | Override the API host. |
41
85
 
42
86
  ## Tools
43
87
 
88
+ Free local tools:
89
+
90
+ | Tool | What it does |
91
+ | ------------------------- | ------------------------------------------------- |
92
+ | `get_capabilities` | Reports free and optional account features. |
93
+ | `list_templates` | Lists published Remotion template families. |
94
+ | `get_template` | Returns one template contract. |
95
+ | `get_video_schema` | Returns the public VideoSpec JSON Schema. |
96
+ | `get_example` | Returns a starter VideoSpec. |
97
+ | `scaffold_video_spec` | Creates a deterministic VideoSpec skeleton. |
98
+ | `get_render_instructions` | Returns the local validation and render workflow. |
99
+ | `diagnose_render_error` | Classifies common local render failures. |
100
+
101
+ Hosted tools, available when `INSTAVAR_API_KEY` is configured:
102
+
44
103
  | Tool | What it does |
45
104
  | ------------------------ | ---------------------------------------------------------------------------------------------- |
46
105
  | `list_jobs` | List recent jobs (newest first). |
47
106
  | `get_job_status` | Runs, artifacts, verifications, current video + thumbnail URLs. |
48
107
  | `get_video_state` | Materialized composition state for a job. |
108
+ | `diagnose_render` | Read-only joined render diagnosis with evidence limits and retry recommendations. |
49
109
  | `get_job_metrics` | Platform engagement snapshots for a published job. |
50
110
  | `get_cost_summary` | Infra cost summary (Lambda / RunPod / R2 / WaveSpeed / PoYo). |
111
+ | `inspect_workflow` | Read the current workflow and its version history. |
51
112
  | `create_video_brief` | Create a job from a structured brief and start rendering. |
52
113
  | `edit_video_brief` | Patch a brief (incl. objective / publishTarget); re-renders unless only publishTarget changed. |
114
+ | `retry_video_qa` | Retry degraded or unavailable QA against the same current frozen video artifact. |
115
+ | `audit_video_qa` | Run an advisory Qwen3.6-Plus second opinion against the same frozen video. |
116
+ | `regenerate_narration` | Regenerate narration and its dependent video from the unchanged durable brief. |
117
+ | `draft_workflow` | Store a complete workflow using the inspected `expectedVersion` (`0` only when none exists). |
118
+ | `patch_workflow` | Create a conflict-aware workflow version from a recursive patch. |
119
+ | `validate_workflow` | Validate and compile the inspected workflow version without rendering. |
120
+ | `preview_workflow` | Read the compiled UniversalVideo brief without rendering. |
121
+ | `compare_workflows` | Compare two durable workflow versions field by field. |
122
+ | `approve_workflow` | Approve the inspected valid version without approving or publishing the video job. |
53
123
  | `approve_job` | Approve a rendered job so it can be published. |
54
124
  | `publish_job` | Publish an approved job to its connected social destination. |
55
125
  | `connect_account` | Start connecting a social account (headless OAuth pairing). |
56
126
  | `connect_account_status` | Poll a pending account connection until it is connected. |
57
127
 
58
- Writes require a key with the `write` scope; `publish_job` requires `publish`.
128
+ Workflow inspection, preview, and comparison require `read`. Workflow draft,
129
+ patch, validation, and approval require `write`. `publish_job` requires
130
+ `publish`.
131
+
132
+ Workflow tools reject unknown arguments instead of silently discarding them.
133
+ API calls time out after 15 seconds. A stale-version `409` tells the caller to
134
+ inspect the latest version, while an unavailable upload or other dependency
135
+ conflict tells the caller to resolve that dependency before retrying.
59
136
 
60
137
  ### Connecting a social account from the terminal
61
138
 
@@ -76,3 +153,18 @@ npx @instavar/mcp-server --help
76
153
  ## License
77
154
 
78
155
  MIT
156
+
157
+ ## Creative guidance
158
+
159
+ `get_creative_guide` works without a key. Omit `guideId` to discover the four
160
+ guides, or choose `visual-copy`, `carousel-stories`, `visual-design` or
161
+ `human-review`. The same text is available as Markdown resources at
162
+ `instavar://creative-guides/<guideId>`. The calling assistant applies the guidance
163
+ to the user's brief; this tool does not generate copy, render, save feedback or
164
+ publish media. Carousel recipes are planning guidance, not additional npm renderers.
165
+
166
+ The monorepo sources live in `docs/guides/creative/`. After an edit, run
167
+ `node scripts/build-creative-guides.mjs`; `--check` rejects a stale bundle.
168
+ The generated TypeScript is bundled into the package, so installed clients need
169
+ no checkout files or access to private knowledge stores. Source changes require
170
+ a normal npm release before installed clients receive them.