@unstable-dev/unmeshed-mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,11 +1,29 @@
 # Unmeshed MCP server
 
-Use Unmeshed from Cursor, Claude Code, Codex, and other MCP clients. You do not need the Unmeshed source repo or the Unmeshed CLI.
+Talk to Unmeshed from Cursor, Claude Code, Codex, or any other MCP client. List, write, save, and run processes with prompts. You do not need the Unmeshed source repo or the Unmeshed CLI.
 
-## Setup
+This is a test package: **`@unstable-dev/unmeshed-mcp`**. Use this name, not `@unmeshed/mcp`.
 
-1. In Unmeshed, create an **API client**. Copy the client id and auth token.
-2. Add this to your MCP config:
+## What you need
+
+- [Node.js](https://nodejs.org/) 18 or later (`node -v`)
+- Access to an Unmeshed org
+- Your own API client credentials (same Client Id + Token as `@unmeshed/sdk`)
+
+Do not paste someone else’s token. Each person should create their own API client.
+
+## 1. Get credentials
+
+1. Open Unmeshed in the browser. Copy the origin from the address bar — that is `UNMESHED_URL`.  
+   Example: `https://your-org.unmeshed.io` (no path, no trailing slash).
+2. In Unmeshed go to **Admin → Applications → Add**. Give the client a name and confirm.
+3. Copy **Client Id** and **Token**. The token is shown **only once**.
+
+[Generating client credentials](https://unmeshed.io/docs/sdks/creating-client-credentials) has screenshots.
+
+## 2. Add it to your MCP client
+
+Use this block. Replace the three env values with yours.
 
 ```json
 {
@@ -23,18 +41,43 @@ Use Unmeshed from Cursor, Claude Code, Codex, and other MCP clients. You do not
 }
 ```
 
-That is the whole setup: your Unmeshed URL, plus the same client id and auth token used by `@unmeshed/sdk`.
+`UNMESHED_BASE_URL` is accepted as an alias for `UNMESHED_URL`.
 
-Until you switch this to `@unmeshed/mcp`, testers should use `@unstable-dev/unmeshed-mcp`. For local source, point `command` at Node and `args` at this package’s built file:
+### Cursor
 
-```json
-{
-  "command": "node",
-  "args": ["/ABS/PATH/TO/unmeshed-mcp/dist/index.js"]
-}
+Cursor **Settings → MCP**, add a new server, and paste the JSON above (or merge the `unmeshed` entry into an existing file).
+
+- All projects: `~/.cursor/mcp.json`
+- This project only: `.cursor/mcp.json`
+
+Reload MCP. `unmeshed` should show as connected, with tools `get_docs`, `list_processes`, `get_process`, `save_process`, `run_process`, and `get_run`.
+
+### Claude Code
+
+Same JSON in `.mcp.json` at the project root, or:
+
+```bash
+claude mcp add unmeshed \
+  --env UNMESHED_URL=https://your-org.unmeshed.io \
+  --env UNMESHED_CLIENT_ID=your-client-id \
+  --env UNMESHED_AUTH_TOKEN=your-auth-token \
+  -- npx -y @unstable-dev/unmeshed-mcp
 ```
 
-Use `http://localhost:8080` if the engine is running locally.
+### Other clients (Codex, Claude Desktop, …)
+
+Same `command`, `args`, and `env`. On native Windows, if `npx` does not start, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@unstable-dev/unmeshed-mcp"]`.
+
+## 3. Try it
+
+In Agent chat:
+
+1. What processes do I have in Unmeshed?
+2. Show me the process definition schema.
+3. Create a hello-world process, save it, and run it.
+4. Did that run succeed?
+
+The assistant should call `get_docs` before writing a process, then `save_process`, `run_process`, and `get_run`.
 
 ## Tools
 
@@ -47,16 +90,24 @@ Use `http://localhost:8080` if the engine is running locally.
 | `run_process` | Start a process. |
 | `get_run` | Fetch a process run by id. |
 
-Call `get_docs` before writing a process. Then `save_process`, then `run_process`, then `get_run`.
+## Troubleshooting
 
-## Try it
+**Not connected / `Connection closed`**
 
-1. What processes do I have?
-2. Show me the process definition schema.
-3. Create a hello-world process, save it, and run it.
-4. Did that run succeed?
+- Confirm `node -v` is 18+ and that Node is on your PATH in the GUI app (not only in a terminal).
+- If you tried an older build, pin `@unstable-dev/unmeshed-mcp@0.1.1` (or later), then reload MCP.
+- Open the MCP log and look for `Missing required environment variables`. Credentials must be in the MCP `env` block, not only in your shell.
+
+**401 or 403**
+
+- Recreate the API client if you lost the token (it is shown only once).
+- Check that this API client’s user can read and write process definitions on that org.
+
+**Wrong org / empty process list**
+
+- `UNMESHED_URL` must be the instance you log into in the browser, not `http://localhost:8080` unless you really run the engine locally.
 
-## Develop
+## Develop (this repo)
 
 ```bash
 npm test

package/dist/server.js

@@ -11,7 +11,7 @@ export const SERVER_INSTRUCTIONS = [
 export function createUnmeshedMcpServer(client, knowledgeDir = defaultKnowledgeDir()) {
     const server = new McpServer({
         name: "unmeshed",
-        version: "0.1.1",
+        version: "0.1.3",
     }, {
         instructions: SERVER_INSTRUCTIONS,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unstable-dev/unmeshed-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for Unmeshed — list, author, save, run, and inspect processes from Cursor, Claude Code, and other MCP clients.",
   "type": "module",
   "main": "./dist/index.js",