@shirbarzur/planform-mcp-server

Planform MCP Server

A Model Context Protocol (MCP) server for Planform diagram management. This server allows VS Code, Cursor, and other MCP-compatible clients to interact with the Planform backend API for creating and managing UML diagrams.

Features

• Device Code Authentication: Secure OAuth-like flow for MCP authentication
• Health Monitoring: Built-in health check endpoint
• Extensible Architecture: Ready for additional diagram management tools

Prerequisites

• Node.js 18+
• npm or yarn
• Access to Planform backend API

Installation

• Clone the repository:

git clone <repository-url>
cd planform-mcp

• Install dependencies:

npm install

• Set up environment variables:

cp env.example .env

Edit .env with your configuration:

BACKEND_BASE_URL=https://www.planform.io/api
MCP_SERVER_NAME=planform-mcp
MCP_SERVER_VERSION=1.0.0
LOG_LEVEL=info

Development

Build the TypeScript code:

npm run build

Run in development mode with hot reload:

npm run dev

Run in watch mode:

npm run watch

Production

Build and start the server:

npm run build
npm start

Running locally (against local backend)

When you run the server from this repo (npm run dev or npm start), it loads .env from this project root. To point at your local backend once:

• In this repo, set in .env:

  BACKEND_BASE_URL=http://localhost:8000
  FRONTEND_BASE_URL=http://localhost:5173
  

• Run npm run dev or npm run build && npm start, and use the MCP (e.g. add a command in Cursor that runs node with dist/index.js and cwd set to this repo).
• When you’re done, change .env back to the production URLs or leave it for next time.

The published package (npx) does not read your workspace .env; only when running from this repo does .env here apply.

Add to Cursor

After the server is published, you can add it in Cursor in either of these ways.

Option 1: Cursor Settings UI

• Open Cursor Settings (Ctrl+, or Cmd+,).
• Go to Features → Tools & MCP (or search for "MCP").
• Click Add new MCP server.
• Configure:
  • Name: planform (or any label you like)
  • Type: Command
  • Command: npx
  • Arguments: -y, @shirbarzur/planform-mcp-server
  • Env (optional; defaults point to https://www.planform.io):
    • BACKEND_BASE_URL = https://www.planform.io/api
    • FRONTEND_BASE_URL = https://www.planform.io
• Save and restart Cursor so the new server is picked up.

Option 2: Edit mcp.json directly

Create or edit your MCP config:

• Project: .cursor/mcp.json in your project root (good for sharing with the team).
• Global: ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json).

Example .cursor/mcp.json:

{
  "mcpServers": {
    "planform": {
      "command": "npx",
      "args": ["-y", "@shirbarzur/planform-mcp-server"],
      "env": {
        "BACKEND_BASE_URL": "https://www.planform.io/api",
        "FRONTEND_BASE_URL": "https://www.planform.io"
      }
    }
  }
}

You can omit the env block to use the built-in defaults (production Planform API). Restart Cursor after changing the file.

The server loads .env only from the package directory (next to the executable), not from your workspace, so your project’s .env does not override the default (production) backend URL.

First use: When you use the MCP, the sign_in tool will give you a link and code to sign in at planform.io and authorize the connection. The access token is stored on disk (~/.planform/mcp-token.json) so it persists across tool calls even if the MCP server is restarted each time.

VS Code Integration

To use this MCP server with VS Code (with an MCP extension):

• Add the server configuration to your MCP settings (same structure as above, under the key your extension expects, e.g. mcp.servers).
• The server runs via stdio transport.
• Call sign_in once to authenticate; the server then remembers your session and current diagram—no IDs to pass to other tools.

Available Tools

Tools are listed in recommended flow order: authenticate first, then diagrams, then nodes, then links. All use verb_noun names; the server handles session and current diagram—no UUIDs to pass.

Discovery and health

• health_check – Check the health status of the Planform MCP server.
• get_usage_guide – Get step-by-step instructions and recommended flow. Call when unsure how to use the server.
• check_backend_health – Check the health status of the Planform backend API.

Authentication (required first)

• sign_in – Call this first. Opens browser for you to approve; the server remembers your session. No IDs to pass to other tools.
• poll_auth_token (optional/advanced) – Manually poll for auth token after user approves. Usually not needed since sign_in polls automatically.

Diagrams

• list_diagrams – List your diagrams. Uses your session; no arguments required (optional: status, page, page_size).
• create_diagram – Create a new diagram (title, type). Becomes the current diagram for node/link tools.
• open_diagram – Open a diagram by title or ID; omit to refresh the current diagram. Opened diagram becomes current.

Nodes

• create_node – Add a node (class, interface, enum) to the current diagram. Refer to nodes by name elsewhere.
• update_node – Update a node's fields, methods, or name. Use node name (e.g. "User"); uses current diagram.
• verify_node – Mark a node as verified. Use node name.
• delete_node – Delete a node. Use node name.

Links

• create_link – Create a link between two nodes. Use node names for from and to (e.g. "User", "Account"); server resolves them.
• update_link – Update a link's label, direction, etc. Use link_id from create_link or open_diagram response.
• verify_link – Mark a link as verified. Use link_id from response.
• delete_link – Delete a link. Use link_id from response.

Architecture

The server is built with:

• TypeScript: Type-safe development
• MCP SDK: Official Model Context Protocol SDK
• Axios: HTTP client for API communication
• Modular Design: Separate concerns for server, API client, and logging

Development Roadmap

This implements steps D22, D23, and D24 of the Planform implementation plan. Completed:

• ✅ D22: Scaffold minimal MCP server (Node.js + MCP SDK)
• ✅ D23: Implement create_diagram, list_diagrams, open_diagram tools
• ✅ D24: Implement create_node, create_link tools with full CRUD operations

Future steps will add:

• D25: Diagram rearrangement capabilities
• Full integration with the Planform backend

Publishing to the MCP Registry

To make your MCP server discoverable so others can find and use it in Cursor, VS Code, etc., do the following once (in order). If you’ve already registered, use the When you update the MCP section instead.

1. Publish to npm

The MCP Registry only stores metadata; the actual package is installed from npm.

• Create an npm account if you don’t have one.
• Log in: npm login
• Scoped package: The project is set up as @shirbarzur/planform-mcp-server (npm) and io.github.ShirBarZur/planform-mcp (MCP Registry). Log in to npm with the account that owns the shirbarzur scope, and use GitHub account ShirBarZur for mcp-publisher login github.
• Bump version if needed, then publish:

  npm run build
  npm publish --access public
  

  (--access public is required for scoped packages so they are installable by everyone.)
• package.json already includes mcpName so the registry can verify ownership; it must match the name in server.json.

Optional – Publish from GitHub (no npm token in repo): On the package page on npm, go to Code → Trusted Publisher and set up the connection. Use Organization or user: your GitHub username or org (e.g. ShirBarZur), Repository: planform-mcp, Workflow filename: publish.yml. After that, pushing a version tag (e.g. v1.0.1) will trigger .github/workflows/publish.yml to build and publish to npm via OIDC.

2. Install the MCP Publisher CLI

• macOS/Linux/WSL (Homebrew): brew install mcp-publisher
• Windows (PowerShell): Run in PowerShell from this repo (or any folder where you want the binary):

  $arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
  Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz" -UseBasicParsing
  tar xf mcp-publisher.tar.gz mcp-publisher.exe
  Remove-Item mcp-publisher.tar.gz
  

  Then move mcp-publisher.exe to a folder that’s in your PATH (e.g. create %USERPROFILE%\bin, add it to PATH, and move the exe there).

3. Authenticate and publish to the MCP Registry

server.json is already configured in this repo; only edit it when you bump the package version (keep it in sync with package.json).

• Authenticate (e.g. GitHub): mcp-publisher login github
• Publish: mcp-publisher publish
• Confirm your server appears on the MCP Registry.

After that, users can discover “Planform MCP Server” in the registry and add it to their MCP client (e.g. Cursor) from there.

Note: The MCP Registry is in preview; behavior and schema may change.

When you update the MCP

Option A – automated (recommended)
From the project root:

npm run release          # bump patch (1.0.0 -> 1.0.1)
npm run release:minor   # bump minor (1.0.0 -> 1.1.0)
npm run release:major   # bump major (1.0.0 -> 2.0.0)

The script bumps the version in package.json and server.json, runs npm run build, then npm publish --access public, then mcp-publisher publish. Ensure you're logged in to npm and have run mcp-publisher login github at least once.

Option B – manual

• Bump the version in package.json (e.g. 1.0.0 → 1.0.1).
• Bump the version in server.json (top-level "version" and packages[0].version).
• Run npm run build, then npm publish --access public, then mcp-publisher publish.

That’s it. Users get updates by upgrading the package (e.g. npm update @planform/planform-mcp-server or reinstalling from the registry).

License

MIT