Chhart MCP

Chhart MCP es una herramienta que permite a los asistentes de IA generar diagramas de flujo y diagramas Sankey instantáneos y compartibles directamente en el chat.

GitHub

Documentación

Servidor Chhart MCP

Un servidor MCP (Model Context Protocol) que permite a asistentes de IA como ChatGPT, Claude y otros crear programáticamente diagramas de flujo y diagramas de Sankey en chhart.app.

Características

🎨 Crear Diagramas de Flujo - Genera diagramas de flujo usando el DSL intuitivo basado en texto de Chhart
📊 Crear Diagramas de Sankey - Construye diagramas de Sankey a partir de datos de flujo
📚 Ayuda de Sintaxis - Obtén documentación completa y ejemplos
🔗 URLs Compartibles - Todos los diagramas vienen con enlaces compartibles de chhart.app
🚀 Integración Fácil - Funciona con cualquier asistente de IA compatible con MCP
🌐 Modo Dual - Ejecuta localmente (stdio) o remotamente (StreamableHTTP)
☁️ Listo para la Nube - Despliega en Railway, Vercel o cualquier hosting de Node.js
🔒 Confiabilidad - Transporte moderno StreamableHTTP para conexiones estables

Requisitos Previos

Node.js 20 o superior
npm o yarn
Un cliente compatible con MCP (Claude Desktop, Cursor, etc.)

Instalación

Desde npm

npm install -g chhart-mcp

O ejecuta directamente sin instalar:

npx chhart-mcp

Desde el Código Fuente

# 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

Uso

Inicio Rápido (Servidor Público)

Puedes usar nuestro servidor MCP administrado sin instalar nada localmente.

Configura tu cliente MCP para conectarte al endpoint público:

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

Modo Local (stdio)

Para usar con Claude Desktop, Cursor u otros clientes MCP locales:

Compila el proyecto:
```
npm run build
```
Agrégalo a la configuración de tu cliente MCP:

Para Claude Desktop, edita claude_desktop_config.json:
```
{
  "mcpServers": {
    "chhart": {
      "command": "npx",
      "args": ["-y", "chhart-mcp"]
    }
  }
}
```
Para Cursor u otros clientes, consulta CONFIG_EXAMPLES.md para más ejemplos.
Reinicia tu cliente MCP

Modo Remoto (StreamableHTTP)

Para despliegue en Railway, Vercel u otras plataformas en la nube, usamos el moderno transporte StreamableHTTP para comunicación confiable y sin estado.

Compila e inicia el servidor StreamableHTTP:
```
npm run build
npm run start:streamable
```
El servidor se iniciará en el puerto 3000 (o el puerto especificado en la variable de entorno PORT).

Configura tu cliente MCP para conectarte al endpoint remoto:

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

Despliega en Railway:

Consulta la Guía de Despliegue en Railway para instrucciones detalladas.

¿Por qué StreamableHTTP?

Migramos del transporte SSE a StreamableHTTP para mayor confiabilidad:

Característica	Transporte SSE	Transporte StreamableHTTP
Tipo de Conexión	Flujo SSE de larga duración	Solicitudes HTTP sin estado
Estabilidad	Propenso a tiempos de espera	✅ Robusto y confiable
Compatibilidad en la Nube	Limitada	✅ Excelente
Gestión de Sesiones	Requerida	Opcional (sin estado)

Modo SSE Heredado

El transporte SSE sigue disponible pero está obsoleto:

npm run start:sse  # Not recommended for production

Herramientas Disponibles

`create_flowchart`

Crea un diagrama de flujo usando el DSL basado en texto de Chhart.

Parámetros:

content (cadena, requerido) - Contenido del diagrama de flujo en formato DSL de Chhart
title (cadena, opcional) - Título para el diagrama de flujo

Ejemplo:

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

Crea un diagrama de Sankey que muestra flujos entre nodos.

Parámetros:

content (cadena, requerido) - Contenido del diagrama de Sankey en formato DSL de Chhart
title (cadena, opcional) - Título para el diagrama

Ejemplo:

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

Devuelve documentación y ejemplos para la sintaxis de Chhart.

Parámetros:

type (enumeración, opcional) - 'flowchart', 'sankey' o 'all' (predeterminado: 'all')

Conversaciones de Ejemplo

Una vez configurado, puedes pedirle a tu asistente de IA:

"Crea un diagrama de flujo que muestre un proceso de inicio de sesión de usuario con verificación de correo electrónico"

"Crea un diagrama de Sankey que muestre cómo $100 de ingresos se dividen en costos, impuestos y ganancias"

"Muéstrame la sintaxis para crear diagramas de flujo en Chhart"

Desarrollo

# 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

Estructura del Proyecto

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

Cómo Funciona

El servidor MCP genera URLs compartibles codificando los datos del gráfico en el hash de la URL, aprovechando la función existente de compartir basada en URL de chhart.app. Esto significa:

✅ No se requiere API de backend
✅ Los gráficos son completamente del lado del cliente
✅ Las URLs funcionan inmediatamente sin almacenamiento
✅ Los gráficos se pueden editar en chhart.app
✅ Respetuoso con la privacidad (los datos permanecen en la URL)

Solución de Problemas

"Comando no encontrado" o "Módulo no encontrado"

Asegúrate de haber ejecutado npm install y npm run build
Verifica que la ruta en la configuración de tu cliente MCP sea absoluta
Comprueba que Node.js 20+ esté instalado: node --version

Problemas de Conexión

"connection closed: EOF" o errores similares:

Si usas el modo remoto, asegúrate de usar el transporte StreamableHTTP (npm run start:streamable)
El transporte SSE heredado está obsoleto y puede tener problemas de estabilidad
Verifica que el servidor esté ejecutándose: revisa el endpoint de salud en http://localhost:3000/health
Revisa la configuración del firewall si despliegas remotamente
Asegúrate de que CORS esté configurado correctamente para tu dominio

Configuración del cliente:

Los clientes StreamableHTTP usan solicitudes application/json a /mcp
Los clientes SSE heredados requieren text/event-stream para el flujo /mcp y JSON para /messages
Asegúrate de que la URL apunte al endpoint /mcp

Los Gráficos No Cargan

Verifica que la URL generada esté completa y no truncada
Revisa la consola del navegador para ver errores
Intenta abrir la URL directamente en un navegador
Los diagramas muy grandes pueden exceder los límites de longitud de URL (típicamente 2000 caracteres)

Errores de Compilación de TypeScript

Asegúrate de usar Node.js 20+
Elimina node_modules y dist, luego ejecuta npm install y npm run build
Verifica la compatibilidad de la versión de TypeScript

Para más ayuda, consulta CONTRIBUTING.md o abre un issue.

Contribuciones

¡Aceptamos contribuciones! Consulta CONTRIBUTING.md para las pautas sobre:

Reportar errores
Sugerir características
Enviar solicitudes de extracción
Configuración de desarrollo
Estándares de codificación

Seguridad

Para preocupaciones de seguridad, consulta nuestra Política de Seguridad. No abras issues públicos para vulnerabilidades de seguridad.

Licencia

Licencia MIT - consulta LICENSE para más detalles.

Enlaces

Chhart.app - Crea y comparte diagramas
Model Context Protocol - Aprende sobre MCP
Documentación - Guías y ejemplos adicionales
Registro de Cambios - Historial de versiones y actualizaciones
Issues - Reporta errores o solicita características