mcp-mermiad

# 🎉 Mermaid MCP Connector - Project Summary ## Overview The **Mermaid MCP Connector** is a universal integration layer that enables the Mermaid MCP Server to work with various AI assistants and applications including GitHub Copilot, ChatGPT, Claude, and custom AI systems. ## ✅ What's Been Built ### 1. Core SDK (`src/index.ts`) - ✅ TypeScript-based MCP client wrapper - ✅ Connection management (connect/disconnect) - ✅ Tool listing and invocation - ✅ High-level methods for all MCP operations: - `generateDiagram()` - Generate diagrams from descriptions - `getDiagramTypes()` - List available diagram types - `getTemplates()` - Get pre-built templates - `validateSyntax()` - Validate Mermaid code - `exportDiagram()` - Export to SVG/PNG/PDF ### 2. REST API Server (`src/rest-api.ts`) - ✅ Express-based HTTP server - ✅ CORS enabled for web integration - ✅ RESTful endpoints: - `POST /api/diagram/generate` - Generate diagrams - `GET /api/diagram/types` - Get diagram types - `GET /api/templates` - Get templates - `POST /api/diagram/validate` - Validate syntax - `POST /api/diagram/export` - Export diagrams - `GET /health` - Health check - ✅ OpenAPI 3.0 specification at `/openapi.json` - ✅ ChatGPT plugin manifest at `/.well-known/ai-plugin.json` - ✅ Automatic JSON error handling ### 3. WebSocket Server (`src/websocket.ts`) - ✅ Real-time bidirectional communication - ✅ Message-based protocol - ✅ Supports all MCP operations - ✅ Client connection management - ✅ Error handling and graceful shutdown ### 4. CLI Tool (`src/cli.ts`) - ✅ Command-line interface for all operations - ✅ Commands: - `rest` - Start REST API server - `websocket` / `ws` - Start WebSocket server - `test` - Test MCP server connection - `generate <description>` - Generate diagram - `types` - List diagram types - `templates` - List templates - ✅ Help and version flags - ✅ Environment variable support ### 5. Documentation - ✅ **README.md** - Complete usage guide with examples - ✅ **INTEGRATION_GUIDE.md** - Comprehensive integration guide for: - GitHub Copilot - ChatGPT plugins - Claude - Custom AI assistants - Web applications (React/Vue) - Slack bots - Discord bots ### 6. Examples - ✅ `examples/basic-usage.js` - SDK usage example - ✅ `examples/rest-api-client.js` - REST API client example - ✅ `examples/websocket-client.js` - WebSocket client example ### 7. Configuration - ✅ `package.json` - NPM package configuration - ✅ `tsconfig.json` - TypeScript configuration - ✅ `.env.example` - Environment variables template - ✅ `.gitignore` - Git ignore rules ## 📦 Package Details ```json { "name": "@narasimhaponnada/mermaid-mcp-connector", "version": "1.0.0", "description": "Universal connector for Mermaid MCP Server", "main": "dist/index.js", "bin": { "mermaid-connector": "./dist/cli.js" } } ``` ## 🚀 How to Use ### Install ```bash npm install -g @narasimhaponnada/mermaid-mcp-connector ``` ### Start REST API (for ChatGPT) ```bash mermaid-connector rest # Server: http://localhost:3000 # OpenAPI: http://localhost:3000/openapi.json ``` ### Start WebSocket (for real-time apps) ```bash mermaid-connector websocket # Server: ws://localhost:3001 ``` ### Use SDK in Your App ```typescript import { MermaidMCPConnector } from '@narasimhaponnada/mermaid-mcp-connector'; const connector = new MermaidMCPConnector(); await connector.connect(); const result = await connector.generateDiagram({ description: 'Create a flowchart for user login' }); console.log(result); await connector.disconnect(); ``` ### CLI Commands ```bash # Test connection mermaid-connector test # Generate diagram mermaid-connector generate "Create a sequence diagram" # List types mermaid-connector types # List templates mermaid-connector templates ``` ## 🎯 Integration Targets ### ✅ GitHub Copilot - Via VS Code extension using the SDK - Direct MCP integration via settings.json - Custom commands and code generation ### ✅ ChatGPT - Via REST API as a ChatGPT plugin - OpenAPI spec provided - Plugin manifest auto-served - Local development and production deployment supported ### ✅ Claude - Native MCP support (direct server connection) - No connector needed, but SDK available if wanted ### ✅ Custom AI Assistants - SDK for programmatic integration - REST API for HTTP-based integration - WebSocket for real-time integration ### ✅ Web Applications - REST API endpoints for frontend integration - CORS enabled - React/Vue/Angular compatible ### ✅ Chat Bots - Slack bot integration example - Discord bot integration example - Any chat platform via REST/WebSocket ## 📊 Architecture ``` ┌─────────────────────────────────────────────┐ │ AI Assistants & Applications │ ├─────────┬─────────┬──────────┬──────────────┤ │ Copilot │ ChatGPT │ Claude │ Custom │ └────┬────┴────┬────┴────┬─────┴──────┬───────┘ │ │ │ │ │ │ │ │ ┌────▼─────────▼─────────▼────────────▼────┐ │ Mermaid MCP Connector │ │ ┌────────┐ ┌─────────┐ ┌───────────┐ │ │ │ SDK │ │REST API │ │ WebSocket │ │ │ └────────┘ └─────────┘ └───────────┘ │ └────────────────┬──────────────────────────┘ │ │ MCP Protocol │ ┌────────────────▼──────────────────────────┐ │ Mermaid MCP Server │ │ (Diagram Generation & Templates) │ └───────────────────────────────────────────┘ ``` ## 🔧 Technical Stack - **Language:** TypeScript 5.7.2 - **Runtime:** Node.js 18+ - **Framework:** Express.js (REST API) - **WebSocket:** ws library - **MCP SDK:** @modelcontextprotocol/sdk ^1.0.4 - **Build Tool:** TypeScript Compiler - **Package Manager:** npm ## 📝 Dependencies ### Production Dependencies ```json { "@modelcontextprotocol/sdk": "^1.0.4", "express": "^4.18.2", "cors": "^2.8.5", "ws": "^8.14.2", "dotenv": "^16.3.1" } ``` ### Dev Dependencies ```json { "@types/node": "^20.10.0", "@types/express": "^4.17.21", "@types/cors": "^2.8.17", "@types/ws": "^8.5.10", "typescript": "^5.7.2" } ``` ## 🎉 Benefits ### For Developers - ✅ **Easy Integration** - One package, multiple integration methods - ✅ **Type Safety** - Full TypeScript support - ✅ **Well Documented** - Comprehensive guides and examples - ✅ **Flexible** - Use SDK, REST API, or WebSocket as needed - ✅ **Production Ready** - Error handling, logging, graceful shutdown ### For AI Assistants - ✅ **OpenAPI Spec** - Standard REST API documentation - ✅ **ChatGPT Plugin** - Automatic manifest generation - ✅ **MCP Native** - Works with any MCP-compatible client - ✅ **Real-time** - WebSocket for live interactions ### For End Users - ✅ **Seamless** - Works with their favorite AI tools - ✅ **Fast** - Efficient communication protocols - ✅ **Reliable** - Robust error handling - ✅ **Powerful** - Full access to Mermaid MCP features ## 📈 Next Steps ### Publishing to NPM 1. Update version in package.json 2. Run `npm run build` 3. Run `npm publish --access public` ### Testing 1. Run examples: `node examples/basic-usage.js` 2. Test REST API: `node examples/rest-api-client.js` 3. Test WebSocket: `node examples/websocket-client.js` ### Documentation - Add more integration examples - Create video tutorials - Write blog posts - Update main README ### Features to Add - Authentication/API keys - Rate limiting - Caching layer - Health monitoring - Metrics collection - Admin dashboard ## 🔗 Links - **Main Project:** https://github.com/Narasimhaponnada/mermaid-mcp - **MCP Server:** @narasimhaponnada/mermaid-mcp-server - **Connector:** @narasimhaponnada/mermaid-mcp-connector - **Documentation:** See README.md and INTEGRATION_GUIDE.md ## 📞 Support - **GitHub Issues:** https://github.com/Narasimhaponnada/mermaid-mcp/issues - **Email:** narasimha.ponnada@hotmail.com - **Discussions:** https://github.com/Narasimhaponnada/mermaid-mcp/discussions --- **Status:** ✅ Ready for Testing and NPM Publishing **Date:** November 3, 2025 **Version:** 1.0.0