# Chhart MCP Server

[![npm version](https://img.shields.io/npm/v/chhart-mcp.svg)](https://www.npmjs.com/package/chhart-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)

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](https://chhart.app).

## Table of Contents

- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
  - [Quick Start (Public Server)](#quick-start-public-server)
  - [Local Mode (stdio)](#local-mode-stdio)
  - [Remote Mode (StreamableHTTP)](#remote-mode-streamablehttp)
- [Available Tools](#available-tools)
- [Example Conversations](#example-conversations)
- [Development](#development)
- [How It Works](#how-it-works)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Security](#security)
- [License](#license)
- [Links](#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

```bash
npm install -g chhart-mcp
```

Or run directly without installing:

```bash
npx chhart-mcp
```

### From Source

```bash
# 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:

```json
{
  "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:**
   ```bash
   npm run build
   ```

2. **Add to your MCP client configuration:**

   For **Claude Desktop**, edit `claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "chhart": {
         "command": "npx",
         "args": ["-y", "chhart-mcp"]
       }
     }
   }
   ```

   For **Cursor** or other clients, see [CONFIG_EXAMPLES.md](docs/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:**
   ```bash
   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:
   ```json
   {
     "mcpServers": {
       "chhart": {
         "url": "https://your-deployment-url.com/mcp"
       }
     }
   }
   ```

3. **Deploy to Railway:**
   
   See the [Railway Deployment Guide](docs/RAILWAY_DEPLOYMENT_GUIDE.md) 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:
```bash
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:**
```typescript
{
  "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:**
```typescript
{
  "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

```bash
# 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](CONTRIBUTING.md) or open an issue.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](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](SECURITY.md). Do not open public issues for security vulnerabilities.

## License

MIT License - see [LICENSE](LICENSE) for details.

Copyright (c) 2026 Chhart.app

## Links

- [Chhart.app](https://chhart.app) - Create and share diagrams
- [Model Context Protocol](https://modelcontextprotocol.io) - Learn about MCP
- [Documentation](docs/) - Additional guides and examples
- [Changelog](CHANGELOG.md) - Version history and updates
- [Issues](https://github.com/alwank/chhart_MCP/issues) - Report bugs or request features