pmx-canvas 0.7.2 → 0.8.0

package/.github/extensions/pmx-canvas/mcp-bootstrap.ts

@@ -0,0 +1,198 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  CallToolResultSchema,
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListToolsRequestSchema,
+  ListToolsResultSchema,
+  McpError,
+  ReadResourceRequestSchema,
+  ResourceUpdatedNotificationSchema,
+  ResourceListChangedNotificationSchema,
+  ToolListChangedNotificationSchema,
+  CreateMessageRequestSchema,
+  ElicitRequestSchema,
+  ListRootsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { isAbsolute, dirname, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { canonicalWorkspace, ensurePmxServer, probePmxServer, runtimeCommand, runtimeVersion } from './runtime.mjs';
+
+const connector = 'canvas_connect_workspace';
+const packageRoot = canonicalWorkspace(dirname(fileURLToPath(import.meta.url)));
+const catalog = ListToolsResultSchema.parse(JSON.parse(readFileSync(new URL('./tools.json', import.meta.url), 'utf8')));
+const server = new Server(
+  { name: 'pmx-canvas-plugin', version: runtimeVersion },
+  {
+    capabilities: { tools: { listChanged: true }, resources: { listChanged: true } },
+    instructions: `Before using any PMX board tool, call ${connector} with the absolute active project directory. Never use the plugin installation directory as the workspace. Then read skill://pmx-canvas/SKILL.md for workbench guidance. The connection returns a browser workbench URL; the native Copilot canvas is client-specific.`,
+  },
+);
+let upstream: Client | undefined;
+let upstreamTransport: StdioClientTransport | undefined;
+let binding: Promise<{ workspaceRoot: string; serverUrl: string }> | undefined;
+let boundWorkspace: string | undefined;
+let boundServerUrl: string | undefined;
+
+async function connected(): Promise<Client> {
+  if (!upstream || !boundServerUrl || !boundWorkspace) {
+    throw new McpError(ErrorCode.InvalidRequest, `Call ${connector} with your absolute project directory first.`);
+  }
+  const health = await probePmxServer(boundServerUrl, boundWorkspace);
+  if (!health.ok) {
+    throw new McpError(ErrorCode.InvalidRequest, `The bound PMX server is unavailable or belongs to another workspace: ${health.error}`);
+  }
+  return upstream;
+}
+
+async function bindWorkspace(root: string) {
+  if (!isAbsolute(root)) throw new McpError(ErrorCode.InvalidParams, 'workspaceRoot must be an absolute project directory.');
+  root = canonicalWorkspace(root);
+  const withinPackage = relative(packageRoot, root);
+  if (!withinPackage || (withinPackage !== '..' && !withinPackage.startsWith(`..${sep}`) && !isAbsolute(withinPackage))) {
+    throw new McpError(ErrorCode.InvalidParams, 'The plugin installation directory is not a project workspace.');
+  }
+  if (boundWorkspace && boundWorkspace !== root) {
+    throw new McpError(ErrorCode.InvalidParams, 'This MCP session is already bound to another workspace. Start a new session.');
+  }
+  if (binding) {
+    const target = await binding;
+    await connected();
+    return target;
+  }
+  boundWorkspace = root;
+  binding = (async () => {
+    const target = await ensurePmxServer(root);
+    if (!target.ok || !target.baseUrl || !target.health) throw new Error(target.error ?? 'PMX Canvas is unavailable.');
+    if (closing) throw new Error('MCP session closed while connecting the workspace.');
+    const runtime = runtimeCommand();
+    const transport = new StdioClientTransport({
+      command: runtime.command,
+      args: [...runtime.args, '--mcp'],
+      cwd: root,
+      env: {
+        ...Object.fromEntries(Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined)),
+        PMX_CANVAS_URL: target.baseUrl,
+        PMX_CANVAS_WORKSPACE_ROOT: root,
+        PMX_CANVAS_DISABLE_BROWSER_OPEN: '1',
+      },
+      stderr: 'inherit',
+    });
+    const capabilities = server.getClientCapabilities() ?? {};
+    const client = new Client(
+      { name: 'pmx-canvas-plugin', version: runtimeVersion },
+      { capabilities },
+    );
+    if (capabilities.roots) client.setRequestHandler(ListRootsRequestSchema, () => server.listRoots());
+    if (capabilities.sampling) {
+      client.setRequestHandler(CreateMessageRequestSchema, (request) => server.createMessage(request.params));
+    }
+    if (capabilities.elicitation) {
+      client.setRequestHandler(ElicitRequestSchema, (request) => server.elicitInput(request.params));
+    }
+    client.setNotificationHandler(ToolListChangedNotificationSchema, () => server.sendToolListChanged());
+    client.setNotificationHandler(ResourceListChangedNotificationSchema, () => server.sendResourceListChanged());
+    client.setNotificationHandler(ResourceUpdatedNotificationSchema, (notification) => server.notification(notification));
+    try {
+      await client.connect(transport);
+      if (closing) throw new Error('MCP session closed while connecting the workspace.');
+      upstream = client;
+      upstreamTransport = transport;
+      boundServerUrl = target.baseUrl;
+      await server.sendToolListChanged();
+      await server.sendResourceListChanged();
+    } catch (error) {
+      upstream = undefined;
+      upstreamTransport = undefined;
+      boundServerUrl = undefined;
+      await client.close();
+      await transport.close();
+      throw error;
+    }
+    return { workspaceRoot: root, serverUrl: target.baseUrl };
+  })();
+  try {
+    return await binding;
+  } catch (error) {
+    binding = undefined;
+    boundWorkspace = undefined;
+    throw error;
+  }
+}
+
+// Some hosts cache the initial tool set even after tools/list_changed; board tools stay locked until binding.
+server.setRequestHandler(ListToolsRequestSchema, async (request) => ({
+  tools: [
+    {
+      name: connector,
+      description: 'Connect PMX Canvas to the user-selected project BEFORE using board tools. Pass the absolute active project directory, never the plugin installation folder. Returns the browser workbench URL and enables the PMX tools for this MCP session.',
+      inputSchema: {
+        type: 'object',
+        properties: { workspaceRoot: { type: 'string', description: 'Absolute directory of the intended project.' } },
+        required: ['workspaceRoot'],
+        additionalProperties: false,
+      },
+    },
+    ...(upstream ? (await (await connected()).listTools(request.params)).tools : catalog.tools),
+  ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  if (request.params.name !== connector) {
+    return await (await connected()).request(request, CallToolResultSchema, { signal: extra.signal });
+  }
+  const root = request.params.arguments?.workspaceRoot;
+  if (typeof root !== 'string') throw new McpError(ErrorCode.InvalidParams, 'workspaceRoot is required.');
+  try {
+    const target = await bindWorkspace(root);
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ ...target, workbenchUrl: `${target.serverUrl}/workbench` }) }],
+      structuredContent: { ...target, workbenchUrl: `${target.serverUrl}/workbench` },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[pmx-canvas] Workspace connection failed: ${message}\n`);
+    return { isError: true, content: [{ type: 'text', text: message }] };
+  }
+});
+server.setRequestHandler(ListResourcesRequestSchema, async (request) =>
+  upstream ? await (await connected()).listResources(request.params) : { resources: [] });
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async (request) =>
+  upstream ? await (await connected()).listResourceTemplates(request.params) : { resourceTemplates: [] });
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => await (await connected()).readResource(request.params));
+
+server.oninitialized = async () => {
+  try {
+    const configured = process.env.PMX_CANVAS_WORKSPACE_ROOT;
+    if (configured) {
+      await bindWorkspace(configured);
+    } else if (server.getClientCapabilities()?.roots) {
+      const { roots } = await server.listRoots();
+      if (roots.length === 1 && roots[0].uri.startsWith('file:')) await bindWorkspace(fileURLToPath(roots[0].uri));
+    }
+  } catch (error) {
+    process.stderr.write(`[pmx-canvas] Automatic workspace connection failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  }
+};
+let closing = false;
+async function shutdown() {
+  if (closing) return;
+  closing = true;
+  try {
+    await upstream?.close();
+    await upstreamTransport?.close();
+    await server.close();
+  } catch (error) {
+    process.stderr.write(`[pmx-canvas] MCP shutdown failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+server.onclose = () => void shutdown();
+process.once('SIGTERM', () => void shutdown());
+process.once('SIGINT', () => void shutdown());
+await server.connect(new StdioServerTransport());

package/.github/extensions/pmx-canvas/runtime.d.mts

@@ -0,0 +1,41 @@
+export interface RuntimeInput {
+    serverUrl?: string;
+    port?: number;
+    autoStart?: boolean;
+    allowWorkspaceMismatch?: boolean;
+}
+
+export interface RuntimeCommand {
+    command: string;
+    args: string[];
+}
+
+export interface ServerProbe {
+    ok: boolean;
+    baseUrl: string | null;
+    health: { ok: boolean; workspace: string } | null;
+    workspaceOk: boolean;
+    error: string | null;
+}
+
+export const runtimeVersion: string;
+export function canonicalWorkspace(path: string): string;
+export function runtimeCommand(): RuntimeCommand;
+export function preferredPort(input?: RuntimeInput): number;
+export function explicitServerUrl(input?: RuntimeInput): string | null;
+export function probePmxServer(
+    baseUrl: string,
+    workspaceRoot: string,
+    input?: RuntimeInput,
+    fetchImpl?: typeof fetch,
+): Promise<ServerProbe>;
+export function findPmxServer(
+    workspaceRoot: string,
+    input?: RuntimeInput,
+    fetchImpl?: typeof fetch,
+): Promise<ServerProbe>;
+export function ensurePmxServer(
+    workspaceRoot: string,
+    input?: RuntimeInput,
+    command?: RuntimeCommand,
+): Promise<ServerProbe>;

package/.github/extensions/pmx-canvas/runtime.json

@@ -0,0 +1,3 @@
+{
+  "version": "0.8.0"
+}

package/.github/extensions/pmx-canvas/runtime.mjs

@@ -0,0 +1,194 @@
+import { execFile } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { resolve } from "node:path";
+
+export const runtimeVersion = JSON.parse(readFileSync(new URL("./runtime.json", import.meta.url), "utf8")).version;
+if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(runtimeVersion)) {
+    throw new Error("PMX Canvas runtime.json must contain an exact package version.");
+}
+
+export function canonicalWorkspace(path) {
+    // .native expands Windows 8.3 short names (RUNNER~1), so every caller compares one spelling.
+    const directory = realpathSync.native(resolve(path));
+    if (!statSync(directory).isDirectory()) throw new Error("PMX Canvas workspace must be a directory.");
+    return directory;
+}
+
+export function runtimeCommand() {
+    return { command: "bun", args: ["x", "--bun", `pmx-canvas@${runtimeVersion}`] };
+}
+
+export function preferredPort(input = {}) {
+    const port = Number(input.port ?? process.env.PMX_CANVAS_PORT ?? process.env.PMX_WEB_CANVAS_PORT ?? 4313);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("PMX Canvas port must be between 1 and 65535.");
+    return port;
+}
+
+export function explicitServerUrl(input = {}) {
+    const value = input.serverUrl ?? process.env.PMX_CANVAS_URL;
+    if (!value) return null;
+    const url = new URL(value);
+    if (!["http:", "https:"].includes(url.protocol)) throw new Error("PMX Canvas server URL must use HTTP or HTTPS.");
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+
+const NO_SERVER = "No matching PMX Canvas server is running.";
+
+export async function probePmxServer(baseUrl, workspaceRoot, input = {}, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(`${baseUrl}/health`, { signal: AbortSignal.timeout(500) });
+    } catch {
+        // Nothing answered (refused, timed out). The raw fetch error ("fetch failed") is not
+        // actionable; a reachable server's own failure below is reported verbatim.
+        return { ok: false, baseUrl, health: null, workspaceOk: false, error: NO_SERVER };
+    }
+    try {
+        if (!response.ok) throw new Error(`Health check returned HTTP ${response.status}.`);
+        const health = await response.json();
+        const workspaceOk = typeof health.workspace === "string" &&
+            (input.allowWorkspaceMismatch === true || canonicalWorkspace(health.workspace) === canonicalWorkspace(workspaceRoot));
+        return {
+            ok: health.ok === true && workspaceOk,
+            baseUrl,
+            health,
+            workspaceOk,
+            error: workspaceOk ? null : `PMX server belongs to ${health.workspace ?? "an unknown workspace"}.`,
+        };
+    } catch (error) {
+        return { ok: false, baseUrl, health: null, workspaceOk: false, error: error.message };
+    }
+}
+
+function daemonPorts(workspaceRoot) {
+    try {
+        return readdirSync(resolve(workspaceRoot, ".pmx-canvas"))
+            .map((name) => /^daemon-(\d+)\.pid$/.exec(name))
+            .filter(Boolean)
+            .map((match) => Number(match[1]))
+            .filter((port) => port > 0 && port <= 65535)
+            .sort((a, b) => a - b);
+    } catch (error) {
+        if (error.code === "ENOENT") return [];
+        throw error;
+    }
+}
+
+export async function findPmxServer(workspaceRoot, input = {}, fetchImpl = fetch) {
+    const explicit = explicitServerUrl(input);
+    if (explicit) return await probePmxServer(explicit, workspaceRoot, input, fetchImpl);
+    const port = preferredPort(input);
+    // Daemon pid filenames locate arbitrary ports; health, not the pid file, proves ownership.
+    const ports = [...new Set([...daemonPorts(workspaceRoot), port, ...Array.from({ length: 9 }, (_, i) => 4313 + i)])];
+    const results = await Promise.all(ports.map((candidate) =>
+        probePmxServer(`http://127.0.0.1:${candidate}`, workspaceRoot, input, fetchImpl)));
+    return results.find((result) => result.ok) ??
+        { ok: false, baseUrl: null, health: null, workspaceOk: false, error: NO_SERVER };
+}
+
+async function portAvailable(port) {
+    return await new Promise((resolveAvailable) => {
+        const server = createServer();
+        server.once("error", () => resolveAvailable(false));
+        server.listen(port, "127.0.0.1", () => server.close(() => resolveAvailable(true)));
+    });
+}
+
+export async function ensurePmxServer(workspaceRoot, input = {}, command = runtimeCommand()) {
+    workspaceRoot = canonicalWorkspace(workspaceRoot);
+    const existing = await findPmxServer(workspaceRoot, input);
+    if (existing.ok || input.autoStart === false) return existing;
+    if (explicitServerUrl(input)) throw new Error(existing.error);
+
+    const directory = resolve(workspaceRoot, ".pmx-canvas");
+    const lock = resolve(directory, "plugin-start.lock");
+    mkdirSync(directory, { recursive: true });
+    const deadline = Date.now() + 75_000;
+    while (Date.now() < deadline) {
+        let fd;
+        try {
+            fd = openSync(lock, "wx");
+        } catch (error) {
+            if (error.code !== "EEXIST") throw error;
+            try {
+                const pid = Number(readFileSync(lock, "utf8"));
+                if (Number.isInteger(pid) && pid > 0) {
+                    try {
+                        process.kill(pid, 0);
+                    } catch (signalError) {
+                        if (signalError.code !== "ESRCH") throw signalError;
+                        rmSync(lock);
+                        continue;
+                    }
+                } else if (Date.now() - statSync(lock).mtimeMs > 5_000) {
+                    rmSync(lock);
+                    continue;
+                }
+            } catch (lockError) {
+                if (lockError.code === "ENOENT") continue;
+                throw lockError;
+            }
+            const server = await findPmxServer(workspaceRoot, input);
+            if (server.ok) return server;
+            await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+            continue;
+        }
+        try {
+            try {
+                writeFileSync(fd, String(process.pid));
+            } finally {
+                closeSync(fd);
+            }
+            const server = await findPmxServer(workspaceRoot, input);
+            if (server.ok) return server;
+            return await startPmxServer(workspaceRoot, input, command);
+        } finally {
+            rmSync(lock, { force: true });
+        }
+    }
+    throw new Error("Timed out waiting for another PMX Canvas plugin startup.");
+}
+
+async function startPmxServer(workspaceRoot, input, command) {
+    const firstPort = preferredPort(input);
+    let port;
+    for (let candidate = firstPort; candidate < Math.min(firstPort + 20, 65536); candidate++) {
+        // Another starter may have claimed this port since discovery.
+        const probe = await probePmxServer(`http://127.0.0.1:${candidate}`, workspaceRoot);
+        if (probe.ok) return probe;
+        if (await portAvailable(candidate)) {
+            port = candidate;
+            break;
+        }
+    }
+    if (!port) throw new Error(`No free PMX Canvas port near ${firstPort}.`);
+
+    // serve --daemon owns the exclusive spawn lock and outlives either client.
+    let startupError;
+    try {
+        await new Promise((resolveStart, rejectStart) => execFile(command.command, [
+            ...command.args, "serve", "--daemon", "--no-open", `--port=${port}`,
+        ], {
+            cwd: workspaceRoot,
+            env: { ...process.env, PMX_CANVAS_WORKSPACE_ROOT: workspaceRoot, PMX_CANVAS_DISABLE_BROWSER_OPEN: "1" },
+            timeout: 60_000,
+            maxBuffer: 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            if (error) rejectStart(new Error(`PMX Canvas startup failed: ${stderr || stdout || error.message}`));
+            else resolveStart();
+        }));
+    } catch (error) {
+        startupError = error;
+    }
+    // A concurrent starter can win the lock. Only verified health makes that a success.
+    for (let attempt = 0; attempt < (startupError ? 40 : 1); attempt++) {
+        const result = await findPmxServer(workspaceRoot, input);
+        if (result.ok) return result;
+        if (startupError?.message.includes("ENOENT")) break;
+        await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+    }
+    throw startupError ?? new Error("PMX Canvas started but its workspace health check failed.");
+}