@miragon/design-iq-mcp 5.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragon GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @miragon/design-iq-mcp
+
+designIQ's read-only MCP server: it exposes a BPM content repo's processes to any MCP client
+(Claude Code, Claude Desktop, IDEs, ...). A content repo is a root `designiq.yml` naming its
+models folder (`models:`, legacy alias `processes:`; the legacy file name `bpmiq.yml` is still
+read); a model IS a file with a registered notation extension there (a process its `.bpmn`),
+and the process view — name, roles (BPMN lanes), steps, gateways, flow, and sub-process
+calls — is **derived from the BPMN** on the fly. Tools:
+`list_models`, `list_processes`, `get_process`, `get_view`, `get_model`, `enumerate_paths`,
+`find_cycles`, `who_owns`, `which_processes_use`, `which_models_use`. Read-only by
+construction: the tools only ever read files, and all of them carry `readOnlyHint`.
+
+This server runs against a **checkout** — the right tool for CI, offline use, and any agent
+with the repo on disk. For live, writable access to the collaboratively edited state of a
+running Live Host, use the Live Host's own `/mcp` endpoint instead — see
+[docs/mcp-integration.md](https://github.com/Miragon/design-iq/blob/main/docs/mcp-integration.md).
+
+## Usage
+
+```sh
+# stdio server against your content repo
+npx @miragon/design-iq-mcp --root ./my-content-repo
+```
+
+Installed as a dependency, the same server is the `designiq-mcp-server` binary.
+
+Or register it in an MCP client config (e.g. `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "designiq-content": {
+      "command": "npx",
+      "args": ["@miragon/design-iq-mcp", "--root", "./my-content-repo"]
+    }
+  }
+}
+```
+
+The content root can also be set via `DESIGNIQ_CONTENT_ROOT`. A Streamable-HTTP entry point
+ships as `@miragon/design-iq-mcp/http` (`PORT`, optional `MCP_TOKEN` bearer auth).
+
+## Todos (opt-in)
+
+The designIQ platform files model-anchored work items ("todos") as issues in the content repo's
+own tracker. The `list_todos` tool exposes the open ones (id, URL, title, parsed anchor,
+assignees) with an optional per-process filter — but it only registers when BOTH env vars are
+set, so the zero-auth default above stays untouched (no credentials → the tool does not exist):
+
+```sh
+DESIGNIQ_TODOS_REPO=owner/name   # the tracker repo on GitHub
+DESIGNIQ_TODOS_TOKEN=...         # a token with issues:read on that repo
+```
+
+`GITHUB_API_URL` overrides the REST base (default `https://api.github.com`).
+
+The pre-rename names `BPM_CONTENT_ROOT`, `BPM_TODOS_REPO` and `BPM_TODOS_TOKEN` are still
+accepted; when both names of a variable are set, the `DESIGNIQ_*` one wins.
+
+## Part of designIQ
+
+Source, content contract, and the example content repo live in
+[Miragon/design-iq](https://github.com/Miragon/design-iq) — see
+[docs/mcp-integration.md](https://github.com/Miragon/design-iq/blob/main/docs/mcp-integration.md)
+for the full tool list and setup.
+
+## License
+
+MIT

package/dist/http.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { n as createMcpServer, r as todosConfigFromEnv, t as DEFAULT_ROOT } from "./tools-V_22sqM1.js";
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
+//#region ../http-kit/src/index.ts
+/**
+* Shared node:http primitives for the designIQ backends (@designiq/http-kit).
+*
+* Extracted after the send/redirect/rawBody/OAuth-state plumbing had been
+* copy-pasted between live-host and control-plane and DRIFTED (the control
+* plane's rawBody lost its return-after-reject; the two apps' state secrets
+* had different lifecycles). One canonical implementation, unit-tested,
+* typechecked against both apps — the same anti-drift role cell-protocol and
+* github-app already play.
+*
+* Deliberately zero third-party deps (node builtins only), so the package
+* copies cleanly into the dependency-free control-plane image (COPY + symlink,
+* no pnpm install — see apps/control-plane/Dockerfile).
+*
+* NOT here on purpose: session/cookie POLICY (the two apps have different
+* security models — stateless HMAC cookies vs SQLite sessions), webhook
+* verification (different secrets/flows), and any router abstraction. Only
+* primitives live here.
+*/
+/** JSON/text response. Dynamic + often session-bound → `cache-control: no-store`
+* (static assets are served elsewhere with their own cache headers). String
+* bodies are plain error text — don't mislabel them as HTML. */
+function send(res, status, body, headers = {}) {
+	const text = typeof body === "string" ? body : JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": typeof body === "string" ? "text/plain; charset=utf-8" : "application/json",
+		"cache-control": "no-store",
+		...headers
+	});
+	res.end(text);
+}
+/** buffer a request body, hard-capped (DoS guard). Rejects AND stops buffering
+* past the cap — the missing `return` after reject is exactly the drift bug
+* this package exists to prevent. */
+function readBody(req, opts = {}) {
+	const maxBytes = opts.maxBytes ?? 1e6;
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (c) => {
+			size += c.length;
+			if (size > maxBytes) {
+				req.destroy();
+				reject(/* @__PURE__ */ new Error("body too large"));
+				return;
+			}
+			chunks.push(c);
+		});
+		req.on("end", () => resolve(Buffer.concat(chunks)));
+		req.on("error", reject);
+	});
+}
+/** constant-time string equality — length-safe, no early-out on the first mismatch */
+function timingSafeStr(a, b) {
+	const ab = Buffer.from(a);
+	const bb = Buffer.from(b);
+	return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+/** constant-time check that the request's Bearer token equals `secret` */
+function bearerAuth(req, secret) {
+	return timingSafeStr(req.headers.authorization?.replace(/^Bearer /, "") ?? "", secret);
+}
+//#endregion
+//#region ../mcp-kit/mount.ts
+async function mountStatelessMcp(req, res, server, opts) {
+	const transport = new NodeStreamableHTTPServerTransport({
+		sessionIdGenerator: void 0,
+		enableJsonResponse: true
+	});
+	res.on("close", () => {
+		transport.close();
+		server.close();
+	});
+	try {
+		const raw = (await readBody(req, { maxBytes: opts.maxBytes })).toString();
+		const body = raw ? JSON.parse(raw) : void 0;
+		await server.connect(transport);
+		await transport.handleRequest(req, res, body);
+	} catch (e) {
+		if (!res.headersSent) send(res, 400, {
+			jsonrpc: "2.0",
+			error: {
+				code: -32700,
+				message: e.message
+			},
+			id: null
+		});
+		else res.end();
+	}
+}
+//#endregion
+//#region http.ts
+/**
+* designiq-mcp-server — HTTP entry point (remote use, e.g. fly.io).
+*
+*   POST /mcp     → the MCP server over Streamable HTTP (stateless; same
+*                   read-only tools as the local stdio server — see tools.ts)
+*   GET  /healthz → liveness for the platform's health checks
+*
+* Optional auth: set MCP_TOKEN and clients must send "Authorization: Bearer <token>"
+* for /mcp.
+*
+* Run: node packages/mcp/http.ts   (PORT defaults to 8080)
+*/
+const PORT = Number(process.env.PORT ?? 8080);
+const TOKEN = process.env.MCP_TOKEN;
+const TODOS = todosConfigFromEnv(process.env);
+/** Stateless Streamable HTTP: one fresh server + transport per request (read-only tools, no session state). */
+async function handleMcp(req, res) {
+	if (TOKEN && !bearerAuth(req, TOKEN)) {
+		send(res, 401, { error: "unauthorized" });
+		return;
+	}
+	if (req.method !== "POST") {
+		send(res, 405, {
+			jsonrpc: "2.0",
+			error: {
+				code: -32e3,
+				message: "Stateless server: POST JSON-RPC messages to this endpoint."
+			},
+			id: null
+		}, { allow: "POST" });
+		return;
+	}
+	await mountStatelessMcp(req, res, createMcpServer(DEFAULT_ROOT, TODOS), { maxBytes: 1e6 });
+}
+createServer(async (req, res) => {
+	try {
+		const url = new URL(req.url ?? "/", "http://localhost");
+		if (url.pathname === "/healthz") return send(res, 200, "ok");
+		if (url.pathname === "/mcp") return await handleMcp(req, res);
+		return send(res, 404, "Not found");
+	} catch (e) {
+		console.error(`request failed: ${e.message}`);
+		if (!res.headersSent) send(res, 500, "Internal error");
+		else res.end();
+	}
+}).listen(PORT, () => {
+	console.log(`designIQ MCP listening on :${PORT} — POST /mcp${TOKEN ? " (bearer-token protected)" : ""}`);
+});
+//#endregion
+export {};

package/dist/server.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { n as createMcpServer, r as todosConfigFromEnv, t as DEFAULT_ROOT } from "./tools-V_22sqM1.js";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+//#region ../notations/cli.ts
+/**
+* The content-repo CLI bootstrap — the `--root <dir>` contract every platform
+* CLI speaks (validator, decisions check, MCP stdio server). It existed as
+* three line-for-line copies; `pnpm validate` chains two of them in one gate,
+* so a drift in `--root` semantics would half-break the gate.
+*
+* Node-only (process.exit/console), like ./content — never exported through
+* the browser-safe index.
+*/
+/**
+* Parse `--root <dir>` out of argv (MUTATES argv, exactly like every caller
+* did — the remaining args are positional filters). Missing directory
+* argument → exit 2, the historical contract of all three CLIs.
+*/
+function cliRoot(argv, opts = {}) {
+	const rootFlag = argv.indexOf("--root");
+	const rootArg = rootFlag >= 0 ? argv[rootFlag + 1] : void 0;
+	if (rootFlag >= 0 && !rootArg) {
+		console.error("--root requires a directory argument");
+		process.exit(2);
+	}
+	const root = rootArg ? resolve(rootArg) : resolve(opts.defaultRoot ?? ".");
+	if (rootFlag >= 0) argv.splice(rootFlag, 2);
+	return root;
+}
+//#endregion
+//#region server.ts
+/**
+* designiq-mcp-server — stdio entry point (local use).
+*
+* Claude Code auto-connects via the repo's .mcp.json. Tool definitions live in
+* tools.ts, shared with the HTTP entry point (http.ts) that runs on fly.io.
+*
+* Content repo: `node server.ts --root /path/to/content-repo` or
+* DESIGNIQ_CONTENT_ROOT (the legacy BPM_CONTENT_ROOT is still read; the new // legacy-name-ok
+* name wins) — defaults to the bundled process-documentation example.
+*
+* One command, no build step: node server.ts (Node >= 23.6, built-in type stripping).
+*/
+const root = cliRoot(process.argv.slice(2), { defaultRoot: DEFAULT_ROOT });
+if (!existsSync(root)) {
+	console.error([
+		`designiq-mcp-server: content root not found: ${root}`,
+		"",
+		"Point the server at a content repo (a checkout with a root designiq.yml):",
+		"  npx @miragon/design-iq-mcp --root <path-to-content-repo>",
+		"  DESIGNIQ_CONTENT_ROOT=<path-to-content-repo> npx @miragon/design-iq-mcp",
+		"(the legacy BPM_CONTENT_ROOT is still read; DESIGNIQ_CONTENT_ROOT wins)"
+	].join("\n"));
+	process.exit(2);
+}
+const todos = todosConfigFromEnv(process.env);
+await createMcpServer(root, todos).connect(new StdioServerTransport());
+console.error(`designiq-mcp-server ready — read-only tools${todos ? ` (+ list_todos on ${todos.repo})` : ""}, repo root: ${root}`);
+//#endregion
+export {};