npm package: @shirbarzur/planform-mcp-server
Description: MCP server for Planform diagram management
Latest version: 1.0.7

# 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

1. Clone the repository:
```bash
git clone <repository-url>
cd planform-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Set up environment variables:
```bash
cp env.example .env
```

Edit `.env` with your configuration:
```env
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:
```bash
npm run build
```

Run in development mode with hot reload:
```bash
npm run dev
```

Run in watch mode:
```bash
npm run watch
```

## Production

Build and start the server:
```bash
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:

1. In this repo, set in `.env`:
   ```env
   BACKEND_BASE_URL=http://localhost:8000
   FRONTEND_BASE_URL=http://localhost:5173
   ```
2. 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).
3. 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](#publishing-to-the-mcp-registry), you can add it in Cursor in either of these ways.

### Option 1: Cursor Settings UI

1. Open **Cursor Settings** (Ctrl+, or Cmd+,).
2. Go to **Features → Tools & MCP** (or search for "MCP").
3. Click **Add new MCP server**.
4. 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`
5. 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`**:

```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](https://www.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):

1. Add the server configuration to your MCP settings (same structure as above, under the key your extension expects, e.g. `mcp.servers`).
2. The server runs via stdio transport.
3. 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](#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](https://www.npmjs.com/signup) 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:
  ```bash
  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):
  ```powershell
  $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](https://learn.microsoft.com/en-us/windows/win32/procthread/environment-variables), 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](https://prod.registry.modelcontextprotocol.io/).

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:

```bash
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**

1. **Bump the version** in `package.json` (e.g. `1.0.0` → `1.0.1`).
2. Bump the version in `server.json` (top-level `"version"` and `packages[0].version`).
3. 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