@instavar/mcp-server 0.4.1 → 0.6.0

package/README.md

@@ -4,14 +4,39 @@
 [![npm](https://img.shields.io/npm/v/%40instavar%2Fmcp-server)](https://www.npmjs.com/package/@instavar/mcp-server)
 [![Glama score](https://glama.ai/mcp/servers/instavar/mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/instavar/mcp-server)
 
-Make local videos with Instavar's open-source Remotion templates from Claude
-Code or Codex. The public template, schema, scaffold, and troubleshooting tools
-work without an account or API key.
+One MCP package starts free and grows with the work. Make local videos with
+Instavar's independent, open-source templates for Remotion from Claude Code or
+Codex without an account or API key.
+
+Instavar is an independent project and is not affiliated with, sponsored by, or
+endorsed by Remotion AG. Remotion is a trademark of Remotion AG.
 
 Add an Instavar API key when you want the hosted workflow:
 **create → render → approve → publish → metrics**. The authenticated tools are
 thin HTTP clients to the hosted Instavar API. The package holds **no database
-connection** and stores no data of its own.
+connection** and stores no data of its own. You keep the free tools and do not
+install a second server.
+
+## Start with the right capability
+
+Use Instavar when an agent needs reusable Remotion video templates, creative
+guidance, a VideoSpec example, or help with a local render error. Call
+`get_capabilities` first, then `get_creative_guide` before drafting copy or design.
+Use `list_templates` and `get_template` to choose a supported structure, and
+`get_example` or `scaffold_video_spec` to prepare its specification.
+`get_render_instructions` supplies the separate local validation, preview and
+render workflow. Planning and scaffolding do not render, upload or publish media.
+
+Prefer a hosted HTTP connection for browser-based agents? Use
+`https://instavar.com/api/mcp/templates`, also listed as
+[Instavar Video Templates on Smithery](https://smithery.ai/servers/cheeweijie/instavar-video-templates).
+That related endpoint adds storyboard and editorial-carousel planning. Its
+optional OAuth tools list and review private projects only. It is not identical
+to this npm package or the full protected Studio endpoint. Public planning does
+not require an Instavar account; a directory or gateway may require its own login.
+
+Hosted Studio production is optional and may incur costs. Never treat a request
+to plan a video as permission to render a paid job or publish a social post.
 
 ## Which model runs?
 
@@ -34,10 +59,7 @@ hosted services, including rendering,
 storage, specialist media generation, QA, publishing, and other declared job
 costs. Using a subscription-backed agent does not make those services free.
 
-For the full architecture, see
-[`docs/architecture/studio-agent-workflow-architecture.md`](../../docs/architecture/studio-agent-workflow-architecture.md).
-For dated provider evidence, see
-[`reports/research/subscription-backed-agent-runtime-2026-07-10.md`](../../reports/research/subscription-backed-agent-runtime-2026-07-10.md).
+For public setup guidance and examples, see [Instavar video templates](https://instavar.com/remotion).
 
 ## Setup
 
@@ -81,18 +103,25 @@ when the key is configured.
 
 ## Tools
 
+From npm 0.6.0 the package also includes `prepare_announcement`: one paired
+announcement card for Remotion and HyperFrames. It returns local source and a
+portable copy document, not a saved hosted project or rendered video. Ask for a
+framework when it is unspecified; continue with the latest returned project and
+matching expectedRevision. Only title, body and action survive a framework switch.
+
 Free local tools:
 
-| Tool                      | What it does                                      |
-| ------------------------- | ------------------------------------------------- |
-| `get_capabilities`        | Reports free and optional account features.       |
-| `list_templates`          | Lists published Remotion template families.       |
-| `get_template`            | Returns one template contract.                    |
-| `get_video_schema`        | Returns the public VideoSpec JSON Schema.         |
-| `get_example`             | Returns a starter VideoSpec.                      |
-| `scaffold_video_spec`     | Creates a deterministic VideoSpec skeleton.       |
-| `get_render_instructions` | Returns the local validation and render workflow. |
-| `diagnose_render_error`   | Classifies common local render failures.          |
+| Tool                      | What it does                                           |
+| ------------------------- | ------------------------------------------------------ |
+| `get_capabilities`        | Reports free and optional account features.            |
+| `get_creative_guide`      | Reads concise copy, story, design and review guidance. |
+| `list_templates`          | Lists published Remotion template families.            |
+| `get_template`            | Returns one template contract.                         |
+| `get_video_schema`        | Returns the public VideoSpec JSON Schema.              |
+| `get_example`             | Returns a starter VideoSpec.                           |
+| `scaffold_video_spec`     | Creates a deterministic VideoSpec skeleton.            |
+| `get_render_instructions` | Returns the local validation and render workflow.      |
+| `diagnose_render_error`   | Classifies common local render failures.               |
 
 Hosted tools, available when `INSTAVAR_API_KEY` is configured:
 
@@ -101,6 +130,7 @@ Hosted tools, available when `INSTAVAR_API_KEY` is configured:
 | `list_jobs`              | List recent jobs (newest first).                                                               |
 | `get_job_status`         | Runs, artifacts, verifications, current video + thumbnail URLs.                                |
 | `get_video_state`        | Materialized composition state for a job.                                                      |
+| `diagnose_render`        | Read-only joined render diagnosis with evidence limits and retry recommendations.              |
 | `get_job_metrics`        | Platform engagement snapshots for a published job.                                             |
 | `get_cost_summary`       | Infra cost summary (Lambda / RunPod / R2 / WaveSpeed / PoYo).                                  |
 | `inspect_workflow`       | Read the current workflow and its version history.                                             |
@@ -148,3 +178,18 @@ npx @instavar/mcp-server --help
 ## License
 
 MIT
+
+## Creative guidance
+
+`get_creative_guide` works without a key. Omit `guideId` to discover the four
+guides, or choose `visual-copy`, `carousel-stories`, `visual-design` or
+`human-review`. The same text is available as Markdown resources at
+`instavar://creative-guides/<guideId>`. The calling assistant applies the guidance
+to the user's brief; this tool does not generate copy, render, save feedback or
+publish media. Carousel recipes are planning guidance, not additional npm renderers.
+
+The monorepo sources live in `docs/guides/creative/`. After an edit, run
+`node scripts/build-creative-guides.mjs`; `--check` rejects a stale bundle.
+The generated TypeScript is bundled into the package, so installed clients need
+no checkout files or access to private knowledge stores. Source changes require
+a normal npm release before installed clients receive them.