Composer

<p align="center"> <img src="https://github.com/OliverGrabner/composer-mcp/raw/main/demo.gif" alt="Composer demo" /> </p> <p align="center"> <img src="https://usecomposer.com/logo_warm_trio_no_bg.svg" width="14" alt="Composer logo" /> <strong>Composer MCP Server</strong> </p> <p align="center"> Give your AI coding agent an architecture canvas.<br/> Design, visualize, and evolve software architecture diagrams - right from your IDE. </p> <p align="center"> <a href="https://www.npmjs.com/package/@usecomposer/mcp"><img src="https://img.shields.io/npm/v/@usecomposer/mcp?color=D27754&label=npm" alt="npm version" /></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP Compatible" /></a> </p> --- **Composer** is a visual system design tool that lets AI coding agents create and modify interactive architecture diagrams through [MCP (Model Context Protocol)](https://modelcontextprotocol.io). Your agent gets tools to add services, databases, queues, and connections, and you get a live canvas at [usecomposer.com](https://usecomposer.com) that updates in real-time. ``` Your IDE <--> MCP Server (this package) <--> Composer API <--> Your Diagram ``` ## Getting Started ### Connect your IDE **Claude Code:** ```bash claude mcp add --transport http composer https://mcp.usecomposer.com ``` **Cursor** — create `.cursor/mcp.json` in your project root: ```json { "mcpServers": { "composer": { "type": "http", "url": "https://mcp.usecomposer.com" } } } ``` Your browser will open for authorization on first use. <details> <summary><strong>Claude Code</strong></summary> ```bash claude mcp add --transport http composer https://mcp.usecomposer.com ``` </details> <details> <summary><strong>Cursor</strong></summary> Create `.cursor/mcp.json` in your project root: ```json { "mcpServers": { "composer": { "type": "http", "url": "https://mcp.usecomposer.com" } } } ``` </details> <details> <summary><strong>Codex</strong></summary> ```bash codex mcp add composer -- npx -y @usecomposer/mcp --stdio ``` </details> <details> <summary><strong>VS Code (Copilot Chat)</strong></summary> Create `.vscode/mcp.json` in your project root: ```json { "servers": { "composer": { "type": "http", "url": "https://mcp.usecomposer.com" } } } ``` </details> <details> <summary><strong>VS Code (Cline)</strong></summary> Open Cline sidebar > Settings (gear icon) > MCP Servers > Add Remote Server: ```json { "mcpServers": { "composer": { "type": "http", "url": "https://mcp.usecomposer.com" } } } ``` </details> <details> <summary><strong>VS Code (Continue)</strong></summary> Add to `.continue/config.yaml`: ```yaml mcpServers: - name: composer url: https://mcp.usecomposer.com ``` </details> <details> <summary><strong>Windsurf</strong></summary> Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "composer": { "serverUrl": "https://mcp.usecomposer.com" } } } ``` > **Note:** Windsurf uses `"serverUrl"` instead of `"url"`. </details> <details> <summary><strong>OpenCode</strong></summary> Create `opencode.json` in your project root: ```json { "mcp": { "composer": { "type": "remote", "url": "https://mcp.usecomposer.com" } } } ``` </details> ## Tools ### Diagram Management | Tool | Description | |------|-------------| | `list_diagrams` | List all your diagrams. Call this first to find which diagram to work on | | `create_diagram` | Create a new diagram and auto-select it for this session | | `select_diagram` | Select which diagram to work on for this session | | `rename_diagram` | Rename the currently selected diagram | > **Note:** Call `list_diagrams` then `select_diagram` (or `create_diagram`) before using other tools. ### Read | Tool | Description | |------|-------------| | `get_graph` | Get the full architecture diagram - all nodes and edges | | `get_node` | Get details for a single node including connected edges | | `search_graph` | Search nodes and edges by keyword | | `get_screenshot` | Get a PNG thumbnail of the diagram from the last auto-save | ### Write | Tool | Description | |------|-------------| | `upsert_node` | Create or update a node (service, database, queue, etc.) | | `upsert_edge` | Create or update a connection between two nodes | | `define_api` | Define API endpoints on a backend service node | | `delete_element` | Delete a node or edge from the diagram | | `link_path` | Link a node to a file or folder in your codebase | ### Plan & Verify | Tool | Description | |------|-------------| | `verify_diagram` | Check for issues like missing endpoints or orphaned nodes | | `plan_import` | Step-by-step workflow for importing an existing codebase | | `get_guide` | Reference guide for node types, protocols, and best practices | ### Node Types `client` · `frontend` · `backend` · `database` · `cache` · `queue` · `storage` · `external` ### Edge Protocols `REST` · `gRPC` · `GraphQL` · `WebSocket` · `TCP` · `UDP` · `async` · `event` · `internal` ## Example Prompts Once connected, try asking your AI agent: | Prompt | What it does | |--------|-------------| | *"Import this codebase into Composer"* | Scans your repo and builds the architecture diagram | | *"Create a new Composer diagram called Backend Architecture"* | Creates and auto-selects a new diagram | | *"Add a Redis cache between the API and the database in Composer"* | Adds a new node and edges to the diagram | | *"Add analytics monitoring to the Composer diagram"* | Adds observability nodes and connections | | *"Update the APIs I defined in Composer"* | Refreshes endpoint definitions on backend nodes | | *"Verify my Composer diagram"* | Checks for missing endpoints, orphaned nodes, etc. | | *"Link each Composer node to its source code"* | Associates diagram nodes with file paths | ## How It Works Authentication is handled via OAuth 2.1 — your browser opens for a one-time consent flow, and you're connected. Tool calls are proxied to the Composer API at `mcp.usecomposer.com`. Your diagram data lives on Composer's servers. The MCP server itself is stateless. Changes made through MCP are immediately visible on the [Composer canvas](https://usecomposer.com) via real-time WebSocket sync. ## Development ```bash git clone https://github.com/olivergrabner/composer-mcp cd composer-mcp npm install npm run dev # Watch mode (rebuilds on change) npm run build # Production build ``` ## Links - [Composer](https://usecomposer.com) - the visual architecture canvas - [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol spec - [Issues](https://github.com/olivergrabner/composer-mcp/issues) - bug reports and feature requests ## License MIT