@modudraft/mcp 0.1.1 → 0.3.0

package/README.md

@@ -1,98 +1,163 @@
-# modudraft-mcp
+# @modudraft/mcp
 
-MCP server for [Modudraft](https://github.com/modudraft/modudraft) — lets AI assistants create and edit system-design diagrams through natural language.
+Model Context Protocol (MCP) server for [Modudraft](https://modudraft.com) — the system-design diagramming tool.
 
-## What it does
+Connect your AI assistant (Claude, Cursor, Copilot, etc.) to your Modudraft diagrams and let it build and edit architecture, sequence, DB schema, and API diagrams for you.
 
-Exposes 14 tools over the [Model Context Protocol](https://modelcontextprotocol.io) (stdio transport):
+---
 
-| Tool | Description |
-|------|-------------|
-| `get_diagram` | Return current nodes and edges |
-| `add_node` | Add a system component (database, queue, API, etc.) |
-| `add_note` | Add a sticky note or title annotation |
-| `add_boundary` | Add a named boundary box (VPC, service, zone…) |
-| `update_node` | Change a node's label, tool, or position |
-| `delete_node` | Remove a node and its connected edges |
-| `add_edge` | Connect two nodes with a directed edge |
-| `delete_edge` | Remove an edge |
-| `clear_diagram` | Reset to an empty diagram |
-| `export_diagram` | Export as a `.modudraft` JSON string |
-| `import_diagram` | Load a diagram from a `.modudraft` string |
-| `list_archetypes` | List all node archetypes (database, compute, queue…) |
-| `list_tools` | List concrete tools for an archetype (postgresql, kafka…) |
-| `list_protocols` | List edge protocol labels (HTTPS, gRPC, Kafka…) |
-
-State is held in memory for the lifetime of the server process. Use `export_diagram` to save and `import_diagram` to reload.
+## Requirements
+
+- **Modudraft Pro** account — API access is a Pro feature
+- **Node.js 18+**
+- An API key from your Modudraft dashboard
+
+---
 
 ## Setup
 
-### Claude Desktop
+### 1. Create an API key
+
+Go to your [Modudraft dashboard](https://app.modudraft.com/dashboard) → **Settings → API Keys** → **Create new key**.
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Copy the key — you'll only see it once.
+
+### 2. Add to your MCP config
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "modudraft": {
       "command": "npx",
-      "args": ["-y", "modudraft-mcp"]
+      "args": ["-y", "@modudraft/mcp"],
+      "env": {
+        "MODUDRAFT_API_KEY": "mdft_your_key_here"
+      }
     }
   }
 }
 ```
 
-Restart Claude Desktop. The Modudraft tools will be available in any conversation.
-
-### Claude Code
+**Cursor** (`.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally):
 
-```bash
-claude mcp add modudraft -- npx -y modudraft-mcp
+```json
+{
+  "mcpServers": {
+    "modudraft": {
+      "command": "npx",
+      "args": ["-y", "@modudraft/mcp"],
+      "env": {
+        "MODUDRAFT_API_KEY": "mdft_your_key_here"
+      }
+    }
+  }
+}
 ```
 
-### Other MCP clients
+### Environment variables
 
-Any client that supports stdio MCP servers can run:
+| Variable | Required | Description |
+|---|---|---|
+| `MODUDRAFT_API_KEY` | Yes | Your `mdft_…` API key |
+| `MODUDRAFT_API_URL` | No | Override API base URL (default: `https://api.modudraft.com`) |
 
-```bash
-npx modudraft-mcp
-```
+---
 
-Node.js ≥ 20 is required.
+## Tools
+
+### Diagram management
+| Tool | Description |
+|---|---|
+| `list_diagrams` | List all your diagrams |
+| `create_diagram` | Create a new diagram |
+| `get_diagram` | Get full diagram state + missing-metadata hints |
+| `delete_diagram` | Move diagram to Bin |
+| `clear_diagram` | Remove all content from a diagram |
+| `layout_diagram` | Auto-arrange nodes (dagre, supports LR/TB/RL/BT) |
+| `get_share_link` | Get or create a share link |
+
+### Architecture nodes & edges
+| Tool | Description |
+|---|---|
+| `add_node` | Add a component (compute, database, queue, gateway, etc.) |
+| `update_node` | Update label, tool, or archetype |
+| `delete_node` | Remove a node and its connections |
+| `add_edge` | Connect two nodes with optional label and protocol |
+| `update_edge` | Update edge label or protocol |
+| `delete_edge` | Remove a connection |
+| `add_boundary` | Add a grouping boundary box |
+| `add_note` | Add a sticky note annotation |
+
+### Node metadata
+| Tool | Description |
+|---|---|
+| `set_node_metadata` | Set a configuration property on a node (host, port, framework, region, etc.) |
+| `suggest_metadata` | Find nodes with missing configuration and suggest what to fill in |
+| `get_node_schema` | Get expected metadata fields for an archetype |
+
+### Sequence diagram
+| Tool | Description |
+|---|---|
+| `add_sequence_message` | Add a message between participants |
+| `add_sequence_participant` | Register a named participant |
+| `clear_sequence` | Remove all sequence messages |
+| `auto_sequence` | Derive sequence messages from the architecture edges |
+
+### DB schema (ER diagram)
+| Tool | Description |
+|---|---|
+| `add_db_table` | Add a database table with columns |
+| `update_db_table` | Replace a table's columns |
+| `delete_db_table` | Remove a table |
+| `export_er_diagram` | Export schema as SQL DDL |
+
+### API schema (OpenAPI)
+| Tool | Description |
+|---|---|
+| `add_api_endpoint` | Add a REST/GraphQL/gRPC endpoint |
+| `update_api_endpoint` | Update endpoint details |
+| `delete_api_endpoint` | Remove an endpoint |
+| `export_openapi` | Export schema as OpenAPI 3.0 JSON |
+
+### Discovery (static, no API call)
+| Tool | Description |
+|---|---|
+| `list_archetypes` | All component archetypes with metadata field schemas |
+| `list_tools` | Available tech tools per archetype (postgresql, redis, kafka, etc.) |
+| `list_protocols` | Valid edge protocol values |
 
 ---
 
-### Local development
+## Example prompts
 
-```bash
-git clone https://github.com/modudraft/modudraft-mcp
-git clone https://github.com/modudraft/modudraft   # sibling dir, needed for @modudraft/core
-cd modudraft-mcp
-npm install
-npm run build
-```
+> "Create a diagram of a typical e-commerce backend with a React frontend, API gateway, user service, product service, order service, PostgreSQL databases, Redis cache, and Kafka queue. Connect them and layout the diagram."
 
-Then point your client at the local build instead of `npx modudraft-mcp`:
+> "Add the DB schema for the order service — orders, order_items, and payments tables."
 
-```json
-{ "command": "node", "args": ["/path/to/modudraft-mcp/dist/index.js"] }
-```
+> "Auto-generate a sequence diagram from the architecture."
 
-## Development
+> "What metadata is missing from the diagram nodes? Fill in the hosts and ports based on our .env file."
 
-```bash
-npm run dev        # watch mode (rebuilds on change)
-npm run typecheck  # type-check without building
-```
+---
 
-## License
+## How it works
+
+Each tool call requires a `diagram_id`. The server reads the current diagram from the Modudraft API, applies the change in memory, and writes it back. Changes appear instantly in the Modudraft web app.
 
-MIT
+The `get_diagram` response includes a `hints` array listing nodes with empty metadata fields so your AI assistant knows what context to ask you for.
 
-## Example usage
+---
+
+## Security
 
-Ask Claude:
+- API keys are hashed (SHA-256) server-side and never stored in plain text
+- Keys can be revoked at any time from the dashboard
+- All requests use HTTPS
 
-> "Create a diagram for an e-commerce checkout flow with a React frontend, a Node API, PostgreSQL database, and a Redis cache. Add edges showing the data flow."
+---
+
+## License
 
-Claude will call `list_archetypes`, `add_node`, and `add_edge` to build the diagram, then you can `export_diagram` and open the `.modudraft` file in the web app.
+MIT © [Modudraft](https://modudraft.com)