Chhart MCP

Chhart MCP 服务

一个 MCP（Model Context Protocol）服务，可让 ChatGPT、Claude 等 AI 助手在 chhart.app 上以编程方式创建流程图和桑基图。

目录

• 功能
• 前置条件
• 安装
• 用法
  • 快速开始（公共服务）
  • 本地模式（stdio）
  • 远程模式（StreamableHTTP）
• 可用工具
• 对话示例
• 开发
• 工作原理
• 故障排除
• 贡献
• 安全
• 许可证
• 链接

功能

• 🎨 创建流程图 - 使用 Chhart 直观的文本 DSL 生成流程图
• 📊 创建桑基图 - 根据流数据构建桑基图
• 📚 语法帮助 - 获取全面的文档和示例
• 🔗 可分享的 URL - 所有图表均附带可分享的 chhart.app 链接
• 🚀 轻松集成 - 适用于任何兼容 MCP 的 AI 助手
• 🌐 双模式 - 可在本地（stdio）或远程（StreamableHTTP）运行
• ☁️ 适用于云端 - 可部署到 Railway、Vercel 或任何 Node.js 托管平台
• 🔒 可靠 - 采用现代 StreamableHTTP 传输，确保连接稳定

前置条件

• Node.js 20 或更高版本
• npm 或 yarn
• 兼容 MCP 的客户端（Claude Desktop、Cursor 等）

安装

从 npm 安装

npm install -g chhart-mcp

也可以直接运行，无需安装：

npx chhart-mcp

从源代码安装

# 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

用法

快速开始（公共服务）

无需在本地安装任何内容，即可使用我们托管的 MCP 服务。

配置 MCP 客户端，以连接公共端点：

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

本地模式（stdio）

用于 Claude Desktop、Cursor 或其他本地 MCP 客户端：

1. 构建项目：

   npm run build
   

2. 添加到 MCP 客户端配置：

   对于 Claude Desktop，请编辑 claude_desktop_config.json：

   {
     "mcpServers": {
       "chhart": {
         "command": "npx",
         "args": ["-y", "chhart-mcp"]
       }
     }
   }
   

   对于 Cursor 或其他客户端，更多示例请参阅 CONFIG_EXAMPLES.md。

3. 重启 MCP 客户端

远程模式（StreamableHTTP）

部署到 Railway、Vercel 或其他云平台时，我们使用现代的 StreamableHTTP 传输，实现可靠的无状态通信。

1. 构建并启动 StreamableHTTP 服务：

   npm run build
   npm run start:streamable
   

   服务将在端口 3000 上启动（或使用 PORT 环境变量指定的端口）。

2. 配置 MCP 客户端，以连接远程端点：

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

3. 部署到 Railway：

   详细说明请参阅 Railway Deployment Guide。

为什么选择 StreamableHTTP？

为提高可靠性，我们已将传输方式从 SSE 迁移到 StreamableHTTP：

功能	SSE 传输	StreamableHTTP 传输
连接类型	长连接 SSE 流	无状态 HTTP 请求
稳定性	容易超时	✅ 稳健可靠
云端兼容性	有限	✅ 出色
会话管理	必需	可选（无状态）

旧版 SSE 模式

仍可使用 SSE 传输，但该方式已弃用：

npm run start:sse  # Not recommended for production

可用工具

create_flowchart

使用 Chhart 的文本 DSL 创建流程图。

参数：

• content（字符串，必需）- Chhart DSL 格式的流程图内容
• title（字符串，可选）- 流程图标题

示例：

{
  "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

创建展示节点之间流向的桑基图。

参数：

• content（字符串，必填）- Chhart DSL 格式的桑基图内容
• title（字符串，可选）- 图表标题

示例：

{
  "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

返回 Chhart 语法的文档和示例。

参数：

• type（枚举，可选）- 'flowchart'、'sankey' 或 'all'（默认值：'all'）

对话示例

配置完成后，你可以向 AI 助手提出以下请求：

“创建一个展示用户登录流程并包含电子邮件验证的流程图”

“创建一个桑基图，展示 100 美元收入如何分配到成本、税款和利润”

“向我展示如何使用 Chhart 语法创建流程图”

开发

# 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

项目结构

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

工作原理

MCP 服务会将图表数据编码到 URL 哈希中，从而生成可分享的 URL，并利用 chhart.app 现有的基于 URL 的分享功能。这意味着：

• ✅ 无需后端 API
• ✅ 图表完全在客户端运行
• ✅ URL 无需存储即可立即使用
• ✅ 可在 chhart.app 上编辑图表
• ✅ 注重隐私（数据保留在 URL 中）

故障排除

“找不到命令”或“找不到模块”

• 确保已运行 npm install 和 npm run build
• 确认 MCP 客户端配置中的路径为绝对路径
• 检查是否已安装 Node.js 20+：node --version

连接问题

“connection closed: EOF”或类似错误：

• 如果使用远程模式，请确保使用 StreamableHTTP 传输（npm run start:streamable）
• 旧版 SSE 传输已弃用，且可能存在稳定性问题
• 确认服务正在运行：检查 http://localhost:3000/health 健康检查端点
• 如果部署在远程环境，请检查防火墙设置
• 确保已为你的域名正确配置 CORS

客户端配置：

• StreamableHTTP 客户端使用 application/json 请求 /mcp
• 旧版 SSE 客户端对 /mcp 流要求使用 text/event-stream，对 /messages 使用 JSON
• 确保 URL 指向 /mcp 端点

图表无法加载

• 确认生成的 URL 完整且未被截断
• 检查浏览器控制台是否有错误
• 尝试直接在浏览器中打开 URL
• 超大型图表可能会超出 URL 长度限制（通常为 2000 个字符）

TypeScript 构建错误

• 确保使用的是 Node.js 20+
• 删除 node_modules 和 dist，然后运行 npm install 和 npm run build
• 检查 TypeScript 版本兼容性

如需更多帮助，请参阅 CONTRIBUTING.md 或提交问题。

贡献

欢迎贡献！有关以下方面的指南，请参阅 CONTRIBUTING.md：

• 报告错误
• 提出功能建议
• 提交拉取请求
• 配置开发环境
• 编码规范

安全

有关安全问题，请参阅我们的 Security Policy。请勿针对安全漏洞公开提交问题。

许可证

MIT License - 详情请参阅 LICENSE。

版权所有 (c) 2026 Chhart.app

链接

• Chhart.app - 创建并分享图表
• Model Context Protocol - 了解 MCP
• 文档 - 更多指南和示例
• 更新日志 - 版本历史和更新
• 问题 - 报告错误或请求功能