@shirbarzur/planform-mcp-server 1.0.1

package/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+# Publish to npm when a version tag is pushed.
+# Set up the Trusted Publisher on npm (package → Code → Trusted Publisher):
+#   Organization or user: your GitHub org or username (e.g. ShirBarZur)
+#   Repository: planform-mcp
+#   Workflow filename: publish.yml
+
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write   # Required for npm OIDC trusted publishing
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --access public --provenance

package/.mcpregistry_github_token

@@ -0,0 +1 @@
+ghu_Ga2cE4Cz4yPBSg7GxI1a6dTrv9MyX40uxRYp

package/.mcpregistry_registry_token

@@ -0,0 +1 @@
+{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzE3MDEzMDgsIm5iZiI6MTc3MTcwMTAwOCwiaWF0IjoxNzcxNzAxMDA4LCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6IlNoaXJCYXJadXIiLCJwZXJtaXNzaW9ucyI6W3siYWN0aW9uIjoicHVibGlzaCIsInJlc291cmNlIjoiaW8uZ2l0aHViLlNoaXJCYXJadXIvKiJ9XX0.vl5OH8FXtLLkVLIZOPnKJV_CIliDhwKp3JJ-H2nNqQ0BbVlMHKEiFljipIh09ZSzu09uYi6Gbo-nTzATQO2aAQ","expires_at":1771701308}

package/MCP_CONNECTION_GUIDE.md

@@ -0,0 +1,263 @@
+# Quick Guide: Connecting Planform MCP to Cursor/Copilot
+
+This guide will help you connect your local Planform MCP server to Cursor or GitHub Copilot.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- Cursor IDE or VS Code with MCP support
+- Planform backend API running (default: `http://localhost:8000`)
+
+## Step 1: Build the MCP Server
+
+First, ensure the MCP server is built:
+
+```bash
+npm install
+npm run build
+```
+
+## Step 2: Configure Environment Variables
+
+Create a `.env` file in the project root (copy from `env.example`):
+
+```bash
+cp env.example .env
+```
+
+Edit `.env` with your configuration:
+```env
+BACKEND_BASE_URL=http://localhost:8000
+MCP_SERVER_NAME=planform-mcp
+MCP_SERVER_VERSION=1.0.0
+LOG_LEVEL=info
+
+# Optional: Override verification URI if backend returns wrong port/URL
+# If backend returns http://localhost:3000/activate but you need a different port:
+# FRONTEND_BASE_URL=http://localhost:5173
+```
+
+## Step 3: Configure Cursor/VS Code
+
+### For Cursor
+
+1. Open Cursor Settings (Ctrl+, or Cmd+,)
+2. Search for "MCP" or navigate to MCP settings
+3. Add the following configuration to your MCP settings file
+
+**Location**: `%APPDATA%\Cursor\User\globalStorage\mcp.json` (Windows) or `~/Library/Application Support/Cursor/User/globalStorage/mcp.json` (Mac) or `~/.config/Cursor/User/globalStorage/mcp.json` (Linux)
+
+**Configuration**:
+```json
+{
+  "mcpServers": {
+    "planform": {
+      "command": "node",
+      "args": [
+        "C:\\path\\to\\planform-mcp\\dist\\index.js"
+      ],
+      "env": {
+        "BACKEND_BASE_URL": "http://localhost:8000",
+        "MCP_SERVER_NAME": "planform-mcp",
+        "MCP_SERVER_VERSION": "1.0.0",
+        "LOG_LEVEL": "info",
+        "FRONTEND_BASE_URL": "http://localhost:5173"
+      }
+    }
+  }
+}
+```
+
+**Note**: If your backend returns a verification URI with the wrong port, add `FRONTEND_BASE_URL` to the `env` section above with your correct frontend URL (replace `5173` with your actual port).
+
+**⚠️ IMPORTANT**: 
+- **Replace `C:\\path\\to\\planform-mcp\\dist\\index.js`** with your actual absolute path to `dist/index.js`
+- On Windows, you can use forward slashes: `C:/path/to/planform-mcp/dist/index.js`
+- On Mac/Linux, use: `/Users/username/path/to/planform-mcp/dist/index.js`
+
+**To find your path:**
+1. Navigate to your project folder in File Explorer (Windows) or Finder (Mac)
+2. Go into the `dist` folder
+3. Right-click on `index.js` → Properties → Copy the full path
+4. Use forward slashes or double backslashes for Windows paths
+
+### For VS Code with MCP Extension
+
+If using VS Code with an MCP extension, add similar configuration:
+
+```json
+{
+  "mcp.servers": {
+    "planform": {
+      "command": "node",
+      "args": ["C:/path/to/planform-mcp/dist/index.js"],
+      "env": {
+        "BACKEND_BASE_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+**Replace the path** with your actual absolute path to `dist/index.js`.
+
+## Step 4: Restart Cursor/VS Code
+
+After adding the configuration, restart Cursor or VS Code to load the MCP server.
+
+## Step 5: Authenticate (Device Flow)
+
+The MCP server uses device code authentication. When you first use the MCP tools:
+
+1. **Start Device Flow**: Use the `device_start` tool in Cursor/Copilot
+   - This will return a `user_code` (e.g., "ABCD-EFGH") and `verification_uri`
+   - **The browser will automatically open** with the verification page
+
+2. **Approve in Browser**: 
+   - The browser should open automatically with the verification page
+   - If it doesn't open automatically, manually open the `verification_uri` from the response
+   - Log in with Firebase (if required)
+   - Enter the `user_code` when prompted (it may be pre-filled if using `verification_uri_complete`)
+   - Click "Allow" to authorize the MCP server
+
+3. **Automatic Token Polling**: 
+   - The MCP server **automatically polls and waits** for your approval (up to 2 minutes by default)
+   - It will poll every few seconds until you approve, deny, or the max wait time is reached
+   - Once you approve in the browser, the token will be received automatically
+   - You'll see log messages indicating polling status
+   - The access token is valid for 7 days and is stored automatically
+   - **Note**: `device_token_poll` is available as an optional/advanced tool if you need to manually check status, but it's usually not needed
+
+## Step 6: Verify Connection
+
+Test the connection by using MCP tools in Cursor:
+
+- `health_check` - Check MCP server status
+- `backend_health_check` - Check backend API status
+- `diagrams_list` - List your diagrams (requires authentication)
+
+## Troubleshooting
+
+### Server Not Starting
+
+1. **Check Node.js version**: Ensure Node.js 18+ is installed
+   ```bash
+   node --version
+   ```
+
+2. **Verify build**: Make sure the server is built
+   ```bash
+   npm run build
+   ```
+
+3. **Check file path**: Ensure the absolute path in your MCP config is correct
+
+4. **Check logs**: Look for error messages in Cursor's output panel or terminal
+
+### Authentication Issues
+
+1. **Backend not running**: Ensure your Planform backend is running on the configured URL
+   ```bash
+   curl http://localhost:8000/healthz
+   ```
+
+2. **Token expired**: If your token expires (after 7 days), restart the device flow by calling `device_start` again
+
+3. **User code expired**: Device codes expire after 10 minutes. Start a new flow if needed
+
+4. **Wrong verification URI port**: If the backend returns a verification URI with the wrong port (e.g., `http://localhost:3000/activate` but you need port 5173), add `FRONTEND_BASE_URL` to your MCP configuration's `env` section in `mcp.json`:
+   ```json
+   "env": {
+     "BACKEND_BASE_URL": "http://localhost:8000",
+     "FRONTEND_BASE_URL": "http://localhost:5173"
+   }
+   ```
+   Then restart Cursor (no rebuild needed - the code already supports this).
+
+### Path Errors
+
+**MODULE_NOT_FOUND or ENOENT errors** usually mean:
+1. The path in your config is incorrect or uses a placeholder
+2. You're using `npm start` instead of the direct `node` command
+
+**Solution**: Use the direct `node` command with your actual absolute path:
+
+```json
+{
+  "mcpServers": {
+    "planform": {
+      "command": "node",
+      "args": ["C:/path/to/planform-mcp/dist/index.js"],
+      "env": {
+        "BACKEND_BASE_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+**Path format tips:**
+- Windows: Use forward slashes `C:/path/to/file.js` or double backslashes `C:\\path\\to\\file.js`
+- Mac/Linux: Use forward slashes `/Users/username/path/to/file.js`
+- Always use the absolute path, not a relative path
+
+### "Server does not support tools" Error
+
+If you see:
+```
+Error: Server does not support tools (required for tools/list)
+```
+
+This means the server wasn't built with the latest code. **Solution**:
+
+1. Rebuild the server:
+   ```bash
+   npm run build
+   ```
+2. Restart Cursor/VS Code
+
+## Available MCP Tools
+
+Once connected, you can use these tools in Cursor/Copilot:
+
+- **Authentication**: `device_start` (required), `device_token_poll` (optional/advanced)
+- **Health**: `health_check`, `backend_health_check`
+- **Diagrams**: `diagram_create`, `diagram_get`, `diagrams_list`
+- **Nodes**: `nodes_create`, `node_update`, `node_verify`, `node_delete`
+- **Links**: `links_create`, `link_update`, `link_verify`, `link_delete`
+
+## Development Mode
+
+For development with hot reload:
+
+```bash
+npm run dev
+```
+
+Then update your MCP config to use `tsx` instead of `node`:
+
+```json
+{
+  "mcpServers": {
+    "planform": {
+      "command": "npx",
+      "args": ["tsx", "C:/path/to/planform-mcp/src/index.ts"],
+      "env": {
+        "BACKEND_BASE_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+**Replace the path** with your actual absolute path to `src/index.ts`.
+
+## Next Steps
+
+- Create diagrams using `diagram_create`
+- Add UML nodes from your codebase using `nodes_create`
+- Link nodes together using `links_create`
+- Verify code matches diagrams using `node_verify` and `link_verify`
+
+For more details, see the main [README.md](README.md).
+

package/README.md

@@ -0,0 +1,210 @@
+# 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
+```
+
+## VS Code Integration
+
+To use this MCP server with VS Code or Cursor:
+
+1. Add the server configuration to your MCP settings
+2. The server will be available via stdio transport
+3. Use the device flow authentication to get access tokens
+
+## Available Tools
+
+### `health_check`
+Check the health status of the Planform MCP server.
+
+### `device_start`
+Start device code flow for MCP authentication. Returns device_code, user_code, and verification URLs.
+
+### `device_token_poll` (Optional/Advanced)
+Manually poll for MCP JWT after user approves. Usually not needed since `device_start` polls automatically. Useful for edge cases or debugging.
+
+### `backend_health_check`
+Check the health status of the Planform backend API.
+
+### `diagram_create`
+Create a new diagram (MCP is allowed). Requires user_uuid and title.
+
+### `diagram_get`
+Fetch full diagram (nodes + links) to mirror state locally.
+
+### `diagrams_list`
+List all diagrams of the bound user with pagination support.
+
+### `nodes_create`
+Create UML node with immutable grid placement.
+
+### `node_update`
+Update structural fields (MCP authoritative).
+
+### `node_verify`
+Mark a node as verified by MCP after confirming structure in code.
+
+### `node_delete`
+Delete node with status-based logic.
+
+### `links_create`
+Create link between nodes (never moves nodes).
+
+### `link_update`
+Update link fields (MCP authoritative).
+
+### `link_verify`
+Mark a link as verified by MCP after confirming relationship in code.
+
+### `link_delete`
+Delete link with status-based logic.
+
+## 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 Roadmahe health stp
+
+This implements steps D22, D23, and D24 of the Planform implementation plan. Completed:
+- ✅ D22: Scaffold minimal MCP server (Node.js + MCP SDK)
+- ✅ D23: Implement diagram_create, diagrams_list, diagram_get tools
+- ✅ D24: Implement nodes_create, links_create 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