Overview

This project runs an MCP server at https://flowgif.com/mcp-server/mcp. The MCP server provides four tools for LLMs/agents:

• mermaid_generator – Generate static or animated Mermaid flowcharts from text.
• mermaid_from_conversation – Extract flows from transcripts and render as diagrams.
• animate_mermaid_code – Add LLM-driven animation to existing Mermaid.
• auto_animate_mermaid_code – Deterministic animation based on flow analysis (no LLM).

Animated or static output is returned as a view URL (e.g., https://flowgif.com/gif/pako:<compressed> or https://flowgif.com/img/pako:<compressed>).

Configure your MCP client

Connect your editor or desktop assistant to the FlowGif MCP server using the steps below.

VS Code — Configure via settings or workspace file

Option A: Workspace file

1. Create .vscode/mcp.json in your workspace with:

{
  "inputs": [],
  "servers": {
    "flowgif-mcp": {
      "type": "https",
      "url": "https://flowgif.com/mcp-server/mcp",
    }
  }
}

Option B: VS Code Settings

1. Open Settings (User or Workspace) and add:

"mcp": {
  "servers": {
    "flowgif-mcp": {
      "type": "https",
      "url": "https://flowgif.com/mcp-server/mcp",
    }
  },
  "discovery": { "enabled": true }
}

Use type: "https" if your MCP client supports it.

Verify

• VS Code: Command Palette → MCP: Show Installed Servers and confirm flowgif-mcp appears.
• Cursor/Claude: Open settings and confirm the server shows as connected/running.
• Try invoking mermaid_generator with a simple request; you should receive a view_url.

Claude Desktop — Adding your MCP server

Option A: GUI (paid-tier or supported builds)

1. Open Claude Desktop.
2. Go to Settings → Integrations (or similar).
3. Click + Add Custom Integration.
4. Enter:
   • Name: e.g., flowgif-mcp
   • URL: https://flowgif.com/mcp-server/mcp
5. Save. Claude should recognize and connect to the MCP endpoint.

Option B: Manual JSON (free-tier)

1. Go to Settings → Developer → Edit Config to open claude_desktop_config.json.
2. Add your server under mcpServers:

{
  "mcpServers": {
    "flowgif-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "--url", "https://flowgif.com/mcp-server/mcp"]
    }
  }
}

Adjust the CLI style per Claude examples. Some builds use npx mcp-remote <url> or pass headers via flags or env.

Save, restart Claude Desktop, then verify in Settings → Developer that the server shows as running. In chat, when tools are requested, choose Allow once or Always allow.

Cursor — Configuring an MCP server

1. Create a config file named mcp.json either at project level (.cursor/mcp.json) or globally (~/.cursor/mcp.json).
2. Use this example for a remote HTTPS endpoint with an auth header:

{
  "mcpServers": {
    "flowgif-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://flowgif.com/mcp-server/mcp",
      ]
    }
  }
}

The name flowgif-mcp is arbitrary. npx mcp-remote is a common helper for remote MCP endpoints.

Use from a PydanticAI Agent (Client)

The simplest way to let an LLM use these tools is to attach the MCP toolset to an agent.

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

server = MCPServerStreamableHTTP("https://flowgif.com/mcp-server/mcp")
agent = Agent("openai:gpt-4o", toolsets=[server])

async def main():
    async with agent:
        res = await agent.run("Create a flowchart for our CI pipeline and animate it. Return a view URL.")
    print(res.output)

See src/mcp_impl/client.py for a runnable example.

Tool contracts

Inputs:
- text_for_mermaid: str
- animated: bool = False
- num_frames: int | None
- base_url: str (default https://flowgif.com)

Returns:
- { "view_url": str }

Inputs:
- conversation_text: str
- focus_on: str = "main_flow"  # main_flow | decisions | all_details
- base_url: str (default https://flowgif.com)

Returns:
- { "view_url": str }

Inputs:
- mermaid_code: str
- num_frames: int | None = 5
- frame_duration: int | None = 800
- base_url: str (default https://flowgif.com)

Returns:
- { "view_url": str }

Inputs:
- mermaid_code: str
- num_frames: int | None  # auto-calculated when None
- frame_duration: int | None = 800
- base_url: str (default https://flowgif.com)

Returns:
- { "view_url": str }

Direct tool call examples

await agent.run({
  "role": "user",
  "content": "Create an animated signup flow (3 frames).",
  "tool": {
    "name": "mermaid_generator",
    "args": {
      "text_for_mermaid": "User signs up & verifies email",
      "animated": true,
      "num_frames": 3,
      "base_url": "https://flowgif.com"
    }
  }
})

code = """
flowchart TD
  A[Start] --> B{Choice}
  B -->|Yes| C[Go]
  B -->|No| D[Stop]
"""

await agent.run({
  "role": "user",
  "content": "Animate this diagram.",
  "tool": {
    "name": "auto_animate_mermaid_code",
    "args": {
      "mermaid_code": code,
      "frame_duration": 900,
      "base_url": "https://flowgif.com"
    }
  }
})

Each tool returns a view_url that you can open directly in a browser.