@unstable-dev/unmeshed-mcp 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# 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.
+
+## Setup
+
+1. In Unmeshed, create an **API client**. Copy the client id and auth token.
+2. Add this to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "unmeshed": {
+      "command": "npx",
+      "args": ["-y", "@unmeshed/mcp"],
+      "env": {
+        "UNMESHED_URL": "https://your-org.unmeshed.io",
+        "UNMESHED_CLIENT_ID": "your-client-id",
+        "UNMESHED_AUTH_TOKEN": "your-auth-token"
+      }
+    }
+  }
+}
+```
+
+That is the whole setup: your Unmeshed URL, plus the same client id and auth token used by `@unmeshed/sdk`.
+
+Until `@unmeshed/mcp` is published, point `command` at Node and `args` at this package’s built file:
+
+```json
+{
+  "command": "node",
+  "args": ["/ABS/PATH/TO/unmeshed-mcp/dist/index.js"]
+}
+```
+
+Use `http://localhost:8080` if the engine is running locally.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_docs` | Authoring docs (schemas and step types). Call with no topic to list topics. |
+| `list_processes` | List process definitions. |
+| `get_process` | Fetch one process definition. |
+| `save_process` | Create or update a process definition. |
+| `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`.
+
+## Try it
+
+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?
+
+## Develop
+
+```bash
+npm test
+npm run build
+```

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Matches the Unmeshed JS/Java SDK:
+ * Authorization: Bearer client.sdk.{clientId}.{sha256(authToken)}
+ */
+export declare function createSecureHash(input: string): string;
+export declare function buildAuthorizationHeader(clientId: string, authToken: string): string;

package/dist/auth.js

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+/**
+ * Matches the Unmeshed JS/Java SDK:
+ * Authorization: Bearer client.sdk.{clientId}.{sha256(authToken)}
+ */
+export function createSecureHash(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+export function buildAuthorizationHeader(clientId, authToken) {
+    return `Bearer client.sdk.${clientId}.${createSecureHash(authToken)}`;
+}

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+import type { UnmeshedConfig } from "./config.js";
+export type FetchLike = typeof fetch;
+export declare class UnmeshedApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+export type ProcessDefinitionSummary = {
+    namespace: unknown;
+    name: unknown;
+    version: unknown;
+    type: unknown;
+    description: unknown;
+};
+export type ProcessDefinition = Record<string, unknown> & {
+    namespace?: string;
+    name?: string;
+    version?: number;
+    type?: string;
+    description?: string;
+    steps?: unknown;
+};
+export type RunProcessRequest = {
+    name: string;
+    namespace?: string;
+    version?: number;
+    requestId?: string;
+    correlationId?: string;
+    input?: Record<string, unknown>;
+};
+export declare class UnmeshedClient {
+    private readonly baseUrl;
+    private readonly authorization;
+    private readonly fetchImpl;
+    constructor(config: UnmeshedConfig, fetchImpl?: FetchLike);
+    listProcessDefinitions(namespace?: string): Promise<{
+        count: number;
+        definitions: ProcessDefinitionSummary[];
+    }>;
+    getProcessDefinition(namespace: string, name: string, version?: number): Promise<ProcessDefinition>;
+    createProcessDefinition(definition: ProcessDefinition): Promise<ProcessDefinition>;
+    updateProcessDefinition(definition: ProcessDefinition): Promise<ProcessDefinition | null>;
+    runProcessAsync(request: RunProcessRequest): Promise<unknown>;
+    getProcessContext(processId: number, includeSteps?: boolean): Promise<unknown>;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,97 @@
+import { buildAuthorizationHeader } from "./auth.js";
+export class UnmeshedApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.name = "UnmeshedApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class UnmeshedClient {
+    baseUrl;
+    authorization;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.authorization = buildAuthorizationHeader(config.clientId, config.authToken);
+        this.fetchImpl = fetchImpl;
+    }
+    async listProcessDefinitions(namespace) {
+        const query = namespace ? `?namespace=${encodeURIComponent(namespace)}` : "";
+        const definitions = await this.request("GET", `/api/processDefinitions${query}`);
+        const list = Array.isArray(definitions) ? definitions : [];
+        return {
+            count: list.length,
+            definitions: list.map((pd) => ({
+                namespace: pd.namespace,
+                name: pd.name,
+                version: pd.version,
+                type: pd.type,
+                description: pd.description ?? null,
+            })),
+        };
+    }
+    async getProcessDefinition(namespace, name, version) {
+        const query = version != null ? `?version=${encodeURIComponent(String(version))}` : "";
+        return this.request("GET", `/api/processDefinitions/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}${query}`);
+    }
+    async createProcessDefinition(definition) {
+        return this.request("POST", "/api/processDefinitions", definition);
+    }
+    async updateProcessDefinition(definition) {
+        return this.request("PUT", "/api/processDefinitions", definition);
+    }
+    async runProcessAsync(request) {
+        return this.request("POST", "/api/process/runAsync", {
+            name: request.name,
+            namespace: request.namespace ?? "default",
+            version: request.version ?? null,
+            requestId: request.requestId,
+            correlationId: request.correlationId,
+            input: request.input ?? {},
+        });
+    }
+    async getProcessContext(processId, includeSteps = false) {
+        const query = new URLSearchParams({
+            includeSteps: String(includeSteps),
+            hideLargeValues: "true",
+        });
+        return this.request("GET", `/api/process/context/${encodeURIComponent(String(processId))}?${query}`);
+    }
+    async request(method, path, body) {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: this.authorization,
+                Accept: "application/json",
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await response.text();
+        const parsed = parseJsonOrText(text);
+        if (response.status === 304) {
+            return null;
+        }
+        if (!response.ok) {
+            const message = typeof parsed === "object" && parsed !== null && "message" in parsed
+                ? String(parsed.message)
+                : `Unmeshed API ${method} ${path} failed with ${response.status}`;
+            throw new UnmeshedApiError(response.status, message, parsed);
+        }
+        return parsed;
+    }
+}
+function parseJsonOrText(text) {
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export type UnmeshedConfig = {
+    baseUrl: string;
+    clientId: string;
+    authToken: string;
+};
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function normalizeBaseUrl(baseUrl: string): string;
+export declare function loadConfig(env?: NodeJS.ProcessEnv): UnmeshedConfig;

package/dist/config.js

@@ -0,0 +1,31 @@
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+export function loadConfig(env = process.env) {
+    const baseUrl = env.UNMESHED_URL?.trim() || env.UNMESHED_BASE_URL?.trim();
+    const clientId = env.UNMESHED_CLIENT_ID?.trim();
+    const authToken = env.UNMESHED_AUTH_TOKEN?.trim();
+    const missing = [];
+    if (!baseUrl)
+        missing.push("UNMESHED_URL");
+    if (!clientId)
+        missing.push("UNMESHED_CLIENT_ID");
+    if (!authToken)
+        missing.push("UNMESHED_AUTH_TOKEN");
+    if (missing.length > 0) {
+        throw new ConfigError(`Missing required environment variables: ${missing.join(", ")}. ` +
+            "Create an API client in Unmeshed, then set UNMESHED_URL (your instance, for example https://your-org.unmeshed.io), " +
+            "UNMESHED_CLIENT_ID, and UNMESHED_AUTH_TOKEN.");
+    }
+    return {
+        baseUrl: normalizeBaseUrl(baseUrl),
+        clientId: clientId,
+        authToken: authToken,
+    };
+}

package/dist/get-docs.d.ts

@@ -0,0 +1,8 @@
+export declare function defaultKnowledgeDir(): string;
+export declare function listDocTopics(knowledgeDir: string): string[];
+export declare function getDoc(knowledgeDir: string, topic?: string): {
+    topics: string[];
+} | {
+    topic: string;
+    content: string;
+};

package/dist/get-docs.js

@@ -0,0 +1,64 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const MARKDOWN_EXT = ".md";
+export function defaultKnowledgeDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, "..", "knowledge");
+}
+export function listDocTopics(knowledgeDir) {
+    return collectMarkdownFiles(knowledgeDir)
+        .map((absPath) => toTopic(knowledgeDir, absPath))
+        .sort((a, b) => a.localeCompare(b));
+}
+export function getDoc(knowledgeDir, topic) {
+    const topics = listDocTopics(knowledgeDir);
+    const trimmed = topic?.trim();
+    if (!trimmed) {
+        return { topics };
+    }
+    const resolved = resolveTopic(topics, trimmed);
+    if (!resolved) {
+        return {
+            topics,
+        };
+    }
+    const absPath = join(knowledgeDir, `${resolved.replaceAll("/", sep)}${MARKDOWN_EXT}`);
+    return {
+        topic: resolved,
+        content: readFileSync(absPath, "utf8"),
+    };
+}
+function collectMarkdownFiles(dir) {
+    const entries = readdirSync(dir);
+    const files = [];
+    for (const entry of entries) {
+        const abs = join(dir, entry);
+        const stats = statSync(abs);
+        if (stats.isDirectory()) {
+            files.push(...collectMarkdownFiles(abs));
+        }
+        else if (entry.endsWith(MARKDOWN_EXT) && !entry.startsWith("_")) {
+            files.push(abs);
+        }
+    }
+    return files;
+}
+function toTopic(knowledgeDir, absPath) {
+    const rel = relative(knowledgeDir, absPath);
+    return rel.slice(0, -MARKDOWN_EXT.length).split(sep).join("/");
+}
+function resolveTopic(topics, requested) {
+    const normalized = requested.replace(/\.md$/i, "").replaceAll("\\", "/");
+    const exact = topics.find((topic) => topic === normalized);
+    if (exact) {
+        return exact;
+    }
+    const caseInsensitive = topics.find((topic) => topic.toLowerCase() === normalized.toLowerCase());
+    if (caseInsensitive) {
+        return caseInsensitive;
+    }
+    const suffix = topics.find((topic) => topic.toLowerCase() === normalized.toLowerCase() ||
+        topic.toLowerCase().endsWith(`/${normalized.toLowerCase()}`));
+    return suffix;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { UnmeshedClient } from "./client.js";
+import { ConfigError, loadConfig } from "./config.js";
+import { createUnmeshedMcpServer } from "./server.js";
+export async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (error) {
+        const message = error instanceof ConfigError ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exit(1);
+    }
+    const client = new UnmeshedClient(config);
+    const server = createUnmeshedMcpServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function isDirectRun() {
+    const entry = process.argv[1];
+    if (!entry) {
+        return false;
+    }
+    return import.meta.url === pathToFileURL(entry).href;
+}
+if (isDirectRun()) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.stack ?? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exit(1);
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type UnmeshedClient } from "./client.js";
+export declare const SERVER_INSTRUCTIONS: string;
+export declare function createUnmeshedMcpServer(client: UnmeshedClient, knowledgeDir?: string): McpServer;

package/dist/server.js

@@ -0,0 +1,203 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { UnmeshedApiError } from "./client.js";
+import { defaultKnowledgeDir, getDoc } from "./get-docs.js";
+export const SERVER_INSTRUCTIONS = [
+    "Call get_docs before writing a process definition.",
+    "Use get_docs topics process-definition.schema, step-definition.schema, and steps/<TYPE> so you do not invent Unmeshed step types.",
+    "Then save_process, then run_process, then get_run to inspect the result.",
+    "Use list_processes and get_process to inspect what already exists.",
+].join(" ");
+export function createUnmeshedMcpServer(client, knowledgeDir = defaultKnowledgeDir()) {
+    const server = new McpServer({
+        name: "unmeshed",
+        version: "0.1.0",
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    server.registerTool("list_processes", {
+        description: "List Unmeshed process definitions. Returns name, namespace, version, type, and description only.",
+        inputSchema: {
+            namespace: z
+                .string()
+                .optional()
+                .describe("Optional namespace filter. Omit to list across namespaces."),
+        },
+    }, async ({ namespace }) => jsonResult(() => client.listProcessDefinitions(namespace)));
+    server.registerTool("get_process", {
+        description: "Fetch a single Unmeshed process definition by namespace and name. Omit version to get the latest.",
+        inputSchema: {
+            namespace: z.string().optional().describe("Namespace. Defaults to default."),
+            name: z.string().describe("Process definition name."),
+            version: z.number().int().optional().describe("Optional version. Latest if omitted."),
+        },
+    }, async ({ namespace, name, version }) => jsonResult(() => client.getProcessDefinition(namespace?.trim() || "default", name, version)));
+    server.registerTool("save_process", {
+        description: "Create or update an Unmeshed process definition. Call get_docs first. Use mode=create for a new process and mode=update when changing an existing version.",
+        inputSchema: {
+            mode: z
+                .enum(["create", "update"])
+                .optional()
+                .describe("create (POST) or update (PUT). Defaults to create."),
+            definition: z
+                .record(z.string(), z.unknown())
+                .describe("Full process definition JSON. Required fields: name, namespace, type, steps."),
+        },
+    }, async ({ mode, definition }) => jsonResult(async () => {
+        const prepared = prepareDefinition(definition, mode ?? "create");
+        if (mode === "update") {
+            const updated = await client.updateProcessDefinition(prepared);
+            if (updated == null) {
+                return {
+                    ok: true,
+                    unchanged: true,
+                    message: "Process definition was not modified.",
+                    namespace: prepared.namespace,
+                    name: prepared.name,
+                    version: prepared.version,
+                };
+            }
+            return {
+                ok: true,
+                message: "Process definition updated successfully.",
+                namespace: updated.namespace,
+                name: updated.name,
+                version: updated.version,
+            };
+        }
+        const created = await client.createProcessDefinition(prepared);
+        return {
+            ok: true,
+            message: "Process definition created successfully.",
+            namespace: created.namespace,
+            name: created.name,
+            version: created.version,
+        };
+    }));
+    server.registerTool("run_process", {
+        description: "Start a saved Unmeshed process asynchronously. Returns the new process id. Use get_run to inspect status later.",
+        inputSchema: {
+            name: z.string().describe("Process definition name."),
+            namespace: z.string().optional().describe("Namespace. Defaults to default."),
+            version: z.number().int().optional().describe("Optional version. Latest if omitted."),
+            input: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Process input object. Pass the user-supplied payload here."),
+            correlationId: z.string().optional(),
+            requestId: z.string().optional(),
+        },
+    }, async (args) => jsonResult(() => client.runProcessAsync({
+        name: args.name,
+        namespace: args.namespace?.trim() || "default",
+        version: args.version,
+        input: args.input,
+        correlationId: args.correlationId,
+        requestId: args.requestId,
+    })));
+    server.registerTool("get_run", {
+        description: "Fetch a process run by process id. Set includeSteps=true for step outputs and debugging.",
+        inputSchema: {
+            processId: z.number().int().describe("Process execution id returned by run_process."),
+            includeSteps: z
+                .boolean()
+                .optional()
+                .describe("Include step records and outputs. Defaults to false."),
+        },
+    }, async ({ processId, includeSteps }) => jsonResult(() => client.getProcessContext(processId, includeSteps ?? false)));
+    server.registerTool("get_docs", {
+        description: "Unmeshed authoring docs (schemas, step types, patterns). Call with no topic to list topics. Use topics like process-definition.schema, step-definition.schema, or steps/HTTP.",
+        inputSchema: {
+            topic: z
+                .string()
+                .optional()
+                .describe("Optional doc topic. Omit to list all topics."),
+        },
+    }, async ({ topic }) => {
+        const result = getDoc(knowledgeDir, topic);
+        if ("content" in result) {
+            return {
+                content: [{ type: "text", text: result.content }],
+            };
+        }
+        if (topic?.trim()) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            error: "unknown_topic",
+                            message: `Unknown topic "${topic}". Use one of the listed topics.`,
+                            topics: result.topics,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: true,
+                        topics: result.topics,
+                        hint: "Call get_docs again with a topic, for example process-definition.schema or steps/HTTP.",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    return server;
+}
+function prepareDefinition(definition, mode) {
+    const prepared = { ...definition };
+    if (!prepared.namespace || String(prepared.namespace).trim() === "") {
+        prepared.namespace = "default";
+    }
+    if (!prepared.type) {
+        prepared.type = "API_ORCHESTRATION";
+    }
+    if (prepared.version == null && mode === "create") {
+        prepared.version = 1;
+    }
+    return prepared;
+}
+async function jsonResult(run) {
+    try {
+        const value = await run();
+        return {
+            content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify(toErrorPayload(error), null, 2) }],
+        };
+    }
+}
+function toErrorPayload(error) {
+    if (error instanceof UnmeshedApiError) {
+        return {
+            ok: false,
+            error: "unmeshed_api_error",
+            status: error.status,
+            message: error.message,
+            body: error.body,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            ok: false,
+            error: error.name,
+            message: error.message,
+        };
+    }
+    return {
+        ok: false,
+        error: "unknown_error",
+        message: String(error),
+    };
+}

package/knowledge/README.md

@@ -0,0 +1,16 @@
+# Schema-Driven Assistant Knowledge
+
+This directory is the source of truth for Unmeshed Assistant's workflow
+generation and process-run debugging knowledge.
+
+Use it as a registry:
+- `process-definition.schema.md` defines the top-level process definition contract.
+- `step-definition.schema.md` defines the shared step contract.
+- `step-output-paths.md` defines how step outputs are referenced.
+- `steps/<STEP_TYPE>.md` defines one step type at a time.
+- `execution/*.md` defines executed process/run/step records for debugging.
+
+When adding a new step type, add a file under `steps/` using
+`steps/_TEMPLATE.md`, then add backend validation rules for high-risk mistakes
+where possible.
+