Chhart

npm version License: MIT Node.js Version

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.

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
  • Quick Start (Public Server)
  • Local Mode (stdio)
  • Remote Mode (StreamableHTTP)
• 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:

1. Build the project:

   npm run build
   

2. 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.

3. 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.

1. 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).

2. Configure your MCP client to connect to the remote endpoint:

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

3. 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

Charts Not Loading

• Verify the generated URL is complete and not truncated
• Check browser console for errors
• Try opening the URL directly in a browser
• Very large diagrams may exceed URL length limits (typically 2000 characters)

TypeScript Build Errors

• Ensure you're using Node.js 20+
• Delete node_modules and dist, then run npm install and npm run build
• Check for TypeScript version compatibility

For more help, see CONTRIBUTING.md or open an issue.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Reporting bugs
• Suggesting features
• Submitting pull requests
• Development setup
• Coding standards

Security

For security concerns, please see our Security Policy. Do not open public issues for security vulnerabilities.

License

MIT License - see LICENSE for details.

Copyright (c) 2026 Chhart.app

Links

• Chhart.app - Create and share diagrams
• Model Context Protocol - Learn about MCP
• Documentation - Additional guides and examples
• Changelog - Version history and updates
• Issues - Report bugs or request features