MCP 服务器

Chhart-MCP

MCP for https://chhart.app to easily create flowcharts or sankey diagram

README

Chhart MCP Server

An MCP (Model Context Protocol) server that enables AI assistants like ChatGPT, Claude, and others to programmatically create flowcharts and Sankey diagrams on chhart.app.

Features
Prerequisites
Installation
Usage
Available Tools
Example Conversations
Development
How It Works
Troubleshooting
Contributing
Security
License
Links

Features

🎨 Create Flowcharts - Generate flowcharts using Chhart's intuitive text-based DSL
📊 Create Sankey Diagrams - Build Sankey diagrams from flow data
📚 Syntax Help - Get comprehensive documentation and examples
🔗 Shareable URLs - All diagrams come with shareable chhart.app links
🚀 Easy Integration - Works with any MCP-compatible AI assistant
🌐 Dual Mode - Run locally (stdio) or remotely (StreamableHTTP)
☁️ Cloud Ready - Deploy to Railway, Vercel, or any Node.js hosting
🔒 Reliable - Modern StreamableHTTP transport for stable connections

Prerequisites

Node.js 20 or higher
npm or yarn
An MCP-compatible client (Claude Desktop, Cursor, etc.)

Installation

From npm

npm install -g chhart-mcp

Or run directly without installing:

npx chhart-mcp

From Source

# Clone the repository
git clone https://github.com/alwank/chhart_MCP.git
cd chhart_MCP

# Install dependencies
npm install

# Build the project
npm run build

Usage

Quick Start (Public Server)

You can use our managed MCP server without installing anything locally.

Configure your MCP client to connect to the public endpoint:

{
  "mcpServers": {
    "chhart": {
      "url": "https://mcp.chhart.app/mcp"
    }
  }
}

Local Mode (stdio)

For use with Claude Desktop, Cursor, or other local MCP clients:

Build the project:
```
npm run build
```
Add to your MCP client configuration:

For Claude Desktop, edit claude_desktop_config.json:
```
{
  "mcpServers": {
    "chhart": {
      "command": "npx",
      "args": ["-y", "chhart-mcp"]
    }
  }
}
```
For Cursor or other clients, see CONFIG_EXAMPLES.md for more examples.
Restart your MCP client

Remote Mode (StreamableHTTP)

For deployment to Railway, Vercel, or other cloud platforms, we use the modern StreamableHTTP transport for reliable, stateless communication.

Build and start the StreamableHTTP server:
```
npm run build
npm run start:streamable
```
The server will start on port 3000 (or the port specified in PORT environment variable).

Configure your MCP client to connect to the remote endpoint:

{
  "mcpServers": {
    "chhart": {
      "url": "https://your-deployment-url.com/mcp"
    }
  }
}

Deploy to Railway:

See the Railway Deployment Guide for detailed instructions.

Why StreamableHTTP?

We migrated from SSE to StreamableHTTP transport for better reliability:

Feature	SSE Transport	StreamableHTTP Transport
Connection Type	Long-lived SSE stream	Stateless HTTP requests
Stability	Prone to timeouts	✅ Robust and reliable
Cloud Compatibility	Limited	✅ Excellent
Session Management	Required	Optional (stateless)

Legacy SSE Mode

The SSE transport is still available but deprecated:

npm run start:sse  # Not recommended for production

Available Tools

`create_flowchart`

Creates a flowchart using Chhart's text-based DSL.

Parameters:

content (string, required) - Flowchart content in Chhart DSL format
title (string, optional) - Title for the flowchart

Example:

{
  "content": "Start\n  Process Step\n    Decision? [shape=diamond]\n      Yes\n        Action\n        End\n      No\n        Skip\n        End",
  "title": "Simple Workflow"
}

`create_sankey`

Creates a Sankey diagram showing flows between nodes.

Parameters:

content (string, required) - Sankey diagram content in Chhart DSL format
title (string, optional) - Title for the diagram

Example:

{
  "content": "Revenue [value=100]\n  Costs [value=40]\n    Salaries [value=25]\n    Operations [value=15]\n  Profit [value=60]",
  "title": "Budget Flow"
}

`get_syntax_help`

Returns documentation and examples for Chhart syntax.

Parameters:

type (enum, optional) - 'flowchart', 'sankey', or 'all' (default: 'all')

Example Conversations

Once configured, you can ask your AI assistant:

"Create a flowchart showing a user login process with email verification"

"Create a Sankey diagram showing how $100 of revenue splits into costs, taxes, and profit"

"Show me the syntax for creating flowcharts in Chhart"

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Run locally (stdio mode)
npm start

# Run StreamableHTTP server (recommended for remote access)
npm run start:streamable

# Run SSE server (legacy, deprecated)
npm run start:sse

Project Structure

chhart_MCP/
├── src/
│   ├── index.ts              # Main entry point (stdio mode)
│   ├── server-streamable.ts  # StreamableHTTP server (recommended)
│   ├── server-sse.ts         # SSE server (legacy)
│   ├── tools/                # MCP tool implementations
│   ├── utils/                # Utility functions
│   └── transports/           # Transport implementations
│       ├── streamable.ts     # StreamableHTTP transport
│       └── sse.ts            # SSE transport (legacy)
├── dist/                     # Compiled JavaScript (generated)
└── docs/                     # Documentation files

How It Works

The MCP server generates shareable URLs by encoding chart data into the URL hash, leveraging chhart.app's existing URL-based sharing feature. This means:

✅ No backend API required
✅ Charts are fully client-side
✅ URLs work immediately without storage
✅ Charts can be edited on chhart.app
✅ Privacy-friendly (data stays in the URL)

Troubleshooting

"Command not found" or "Module not found"

Ensure you've run npm install and npm run build
Verify the path in your MCP client configuration is absolute
Check that Node.js 20+ is installed: node --version

Connection Issues

"connection closed: EOF" or similar errors:

If using remote mode, ensure you're using StreamableHTTP transport (npm run start:streamable)
The legacy SSE transport is deprecated and may have stability issues
Verify the server is running: check the health endpoint at http://localhost:3000/health
Check firewall settings if deploying remotely
Ensure CORS is properly configured for your domain

Client configuration:

StreamableHTTP clients use application/json requests to /mcp
Legacy SSE clients require text/event-stream for the /mcp stream and JSON for /messages
Ensure the URL points to the /mcp endpoint