Metadata-Version: 2.5
Name: visionstory-mcp
Version: 0.0.8
Summary: MCP server for the VisionStory API - task-oriented tools for AI talking-avatar video generation.
Project-URL: Homepage, https://developers.visionstory.ai
Project-URL: Documentation, https://developers.visionstory.ai/guides/for-agents
Author-email: VisionStory <register@visionstory.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,avatar,mcp,model-context-protocol,talking-avatar,video-generation,visionstory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.14.0
Requires-Dist: visionstory==0.0.8
Description-Content-Type: text/markdown

# visionstory-mcp

MCP server for the [VisionStory API](https://developers.visionstory.ai) — task-oriented tools that let AI agents (Claude Desktop, Cursor, and any Model Context Protocol client) generate AI talking-avatar videos without writing code.

It exposes all **26 public API operations**, kept in sync with the [`visionstory`](https://pypi.org/project/visionstory/) SDK and `visionstory` CLI:

- Talking-avatar videos: generate, get, list, and delete.
- Avatars and voices: create or clone, list, and delete.
- AI Video: discover models, estimate cost, generate, get one or many, list, and delete.
- Images, speech, and audio: discover image models, generate or edit images, synthesize localized MP3 audio, transcribe speech, and align known text with word timestamps.
- Assets and account: upload, list, and delete assets; list avatar models; check credits.

On startup, the local server checks the shared release manifest and writes an upgrade notice to stderr when a newer package is available. Agents can read `visionstory://release` for the installed and latest versions, feature highlights, release notes, and the upgrade command. Set `VISIONSTORY_UPDATE_CHECK=0` to disable the check.

Delete tools require `confirm=true` after explicit user confirmation. The local stdio server keeps direct local-file support for avatar, voice, talking-video, and asset workflows.

## Install & run

Requires an API key — create one on the [VisionStory API keys page](https://developers.visionstory.ai/api-keys) (Pro plan and up) and set it as `VISIONSTORY_API_KEY`.

Add it to Claude Desktop (or any MCP client):

```json
{
  "mcpServers": {
    "visionstory": {
      "command": "uvx",
      "args": ["visionstory-mcp"],
      "env": { "VISIONSTORY_API_KEY": "sk-vs-xxxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

`generate_video` and `generate_ai_video` submit and poll to completion, returning the final video URL — one call in, one result out. `create_speech` returns standard MCP audio content plus usage metadata. `transcribe_audio` and `align_audio` accept a local WAV/MP3 file, public URL, or reusable asset ID.

The `visionstory://contract` MCP resource reports the same contract version, SHA-256 fingerprint,
and operation count as `visionstory.get_contract_info()` and `visionstory contract`.

## Run standalone

Verify that the package and all public tools load, then exit:

```bash
uvx visionstory-mcp --check
```

Run the stdio server for an MCP client:

```bash
export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"
uvx visionstory-mcp          # or: python -m visionstory_mcp
```

The normal server command waits silently for MCP messages. Use `--check` when testing it directly in a terminal.

## License

MIT
