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

package/README.md

@@ -1,11 +1,13 @@
 # @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:
+designIQ's read-only MCP server: it exposes the models of a designIQ content repo — processes
+(BPMN), decisions (DMN), Wardley Maps, Team Topologies, Event Storming boards, Context Maps,
+Value Chains and Markdown — 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`). Views are **derived from the
+models** on the fly; BPMN gets the richest one — name, roles (BPMN lanes), steps, gateways,
+flow, and sub-process calls. 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`.

package/dist/http.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createMcpServer, r as todosConfigFromEnv, t as DEFAULT_ROOT } from "./tools-V_22sqM1.js";
+import { n as createMcpServer, r as todosConfigFromEnv, t as DEFAULT_ROOT } from "./tools-8vgJc4aD.js";
 import { createServer } from "node:http";
 import { timingSafeEqual } from "node:crypto";
 import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";

package/dist/server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createMcpServer, r as todosConfigFromEnv, t as DEFAULT_ROOT } from "./tools-V_22sqM1.js";
+import { n as createMcpServer, r as todosConfigFromEnv, t as DEFAULT_ROOT } from "./tools-8vgJc4aD.js";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";

package/dist/{tools-V_22sqM1.js → tools-8vgJc4aD.js}

@@ -93,8 +93,8 @@ const NOTATIONS = [
 		id: "wardley",
 		label: "Wardley Map",
 		noun: {
-			singular: "wardley map",
-			plural: "wardley maps"
+			singular: "Wardley Map",
+			plural: "Wardley Maps"
 		},
 		extensions: [".owm", ".wmap"],
 		mediaKind: "dsl",
@@ -109,8 +109,8 @@ const NOTATIONS = [
 		id: "team-topology",
 		label: "Team Topology",
 		noun: {
-			singular: "team topology",
-			plural: "team topologies"
+			singular: "Team Topology",
+			plural: "Team Topologies"
 		},
 		extensions: [".tt", ".ttm.json"],
 		mediaKind: "json",
@@ -121,8 +121,8 @@ const NOTATIONS = [
 		id: "event-storming",
 		label: "Event Storming",
 		noun: {
-			singular: "event storming board",
-			plural: "event storming boards"
+			singular: "Event Storming board",
+			plural: "Event Storming boards"
 		},
 		extensions: [".storm"],
 		mediaKind: "dsl",
@@ -137,8 +137,8 @@ const NOTATIONS = [
 		id: "context-map",
 		label: "Context Map",
 		noun: {
-			singular: "context map",
-			plural: "context maps"
+			singular: "Context Map",
+			plural: "Context Maps"
 		},
 		extensions: [".cm.json"],
 		mediaKind: "json",
@@ -159,8 +159,8 @@ const NOTATIONS = [
 		id: "value-chain",
 		label: "Value Chain",
 		noun: {
-			singular: "value chain",
-			plural: "value chains"
+			singular: "Value Chain",
+			plural: "Value Chains"
 		},
 		extensions: [".vc.json"],
 		mediaKind: "json",
@@ -1342,7 +1342,7 @@ const DERIVERS = {
 		return {
 			notation: "wardley",
 			name: null,
-			summary: `Wardley map with ${counted(stats)}`,
+			summary: `Wardley Map with ${counted(stats)}`,
 			stats
 		};
 	},
@@ -1354,7 +1354,7 @@ const DERIVERS = {
 		return {
 			notation: "team-topology",
 			name: null,
-			summary: `Team topology with ${counted(stats)}`,
+			summary: `Team Topology with ${counted(stats)}`,
 			stats
 		};
 	},
@@ -1378,7 +1378,7 @@ const DERIVERS = {
 		return {
 			notation: "event-storming",
 			name: typeof title === "string" ? title : null,
-			summary: `Event storming board with ${Object.keys(present).length > 0 ? counted(present) : "no elements"}`,
+			summary: `Event Storming board with ${Object.keys(present).length > 0 ? counted(present) : "no elements"}`,
 			stats,
 			detail: {
 				level: graph.meta?.level ?? null,
@@ -1401,7 +1401,7 @@ const DERIVERS = {
 		return {
 			notation: "context-map",
 			name: typeof title === "string" ? title : null,
-			summary: `Context map with ${counted({ contexts: stats.contexts })}${breakdown(CM_SUBDOMAIN_TYPES)}, ${counted({ relationships: stats.relationships })}${breakdown(CM_RELATIONSHIP_PATTERNS)}`,
+			summary: `Context Map with ${counted({ contexts: stats.contexts })}${breakdown(CM_SUBDOMAIN_TYPES)}, ${counted({ relationships: stats.relationships })}${breakdown(CM_RELATIONSHIP_PATTERNS)}`,
 			stats,
 			detail: {
 				contexts: graph.nodes.map((n) => ({
@@ -1432,7 +1432,7 @@ const DERIVERS = {
 		return {
 			notation: "value-chain",
 			name: null,
-			summary: `Value chain with ${counted(stats)}`,
+			summary: `Value Chain with ${counted(stats)}`,
 			stats
 		};
 	}
@@ -1583,6 +1583,20 @@ function todosConfigFromEnv(env) {
 		apiUrl: env.GITHUB_API_URL
 	} : void 0;
 }
+/** "a, b and c" */
+const andList = (items) => items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+/** every registered notation with its file extensions */
+const NOTATION_FILES = andList(NOTATIONS.map((n) => `${n.label} (${n.extensions.join("/")})`));
+function readOnlyInstructions(on) {
+	return [
+		"designIQ is a Git-native workspace where teams model their business and their architecture together, live; this server reads one checkout of such a repository and never writes.",
+		`The repository keeps its models as files under the folder its designiq.yml names, one model per file with the file stem as its id, in these notations: ${NOTATION_FILES}.`,
+		"Start with `list_models` to see which models it holds.",
+		"These tools are notation-neutral: `get_view` (the derived structure), `get_model` (the raw graph of nodes and edges), `enumerate_paths` and `find_cycles` (flow analysis where the notation has flow semantics) and `which_models_use` (which models reference a given one).",
+		"BPMN has deeper tooling: `list_processes`, `get_process` (the derived process view: roles, steps, flow, sub-process calls), `who_owns` (ownership from lanes) and `which_processes_use`" + (on.todos ? "; `list_todos` lists the open todos anchored to processes." : "."),
+		"Live editing, the modeler widgets and release as a pull request are on the designIQ Live Host, not here."
+	].join(" ");
+}
 /** Build a fully configured, read-only MCP server over the repo at `root`. */
 function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 	const config = () => loadContentConfig(root);
@@ -1614,17 +1628,19 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		return graph;
 	};
 	const isGraph = (g) => !("content" in g);
-	/** the registry nouns for user-facing copy ("wardley map" / "team topologies") */
+	/** the registry nouns for user-facing copy ("Wardley Map" / "Team Topologies") */
 	const nounOf = (notation) => byId(notation)?.noun.singular ?? notation;
 	const pluralOf = (notation) => byId(notation)?.noun.plural ?? notation;
 	const notAContentRepo = () => fail(`No usable designiq.yml (or legacy bpmiq.yml) at the content root — not a content repo. Expected a root designiq.yml naming the models folder.`);
 	const unknownProcess = async (id) => fail(`Unknown process '${id}'. Available: ${(await processes()).map((p) => p.id).join(", ") || "(none)"}.`);
 	const server = new McpServer({
 		name: "designiq-mcp",
+		title: "designIQ model repository (read-only)",
 		version: "0.2.0"
-	});
+	}, { instructions: readOnlyInstructions({ todos: todos !== void 0 }) });
 	server.registerTool("list_models", {
-		description: "List EVERY model file of the repository, grouped by notation (bpmn, dmn, wardley, team-topology, …) — the registry-wide superset of list_processes. Each row: id (file stem), path, and — for notations with a registered deriver — the model's own name, summary and stats. Use to see which notations a repo contains before reaching for the notation-specific tools.",
+		title: "List models",
+		description: `List EVERY model file of the repository, grouped by notation (${NOTATIONS.map((n) => n.id).join(", ")}) — the starting point for any question. Each row: id (file stem), path, and — for notations with a registered deriver — the model's own name, summary and stats. Use to see which notations a repo contains before reaching for the notation-specific tools; list_processes is the BPMN-only listing.`,
 		annotations: READ_ONLY
 	}, safe(async () => {
 		const cfg = config();
@@ -1654,7 +1670,8 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		return ok({ models: grouped });
 	}));
 	server.registerTool("list_processes", {
-		description: "List all modeled business processes — every .bpmn file under the repo's designiq.yml models folder. Each row: id (file name without extension), derived name, the file path, and a count of steps/events/gateways/roles. Use to get a portfolio overview or to find a process id before calling get_process, get_model, who_owns or enumerate_paths.",
+		title: "List BPMN processes",
+		description: "BPMN only: list the processes — every .bpmn file under the repo's designiq.yml models folder. Each row: id (file name without extension), derived name, the file path, and a count of steps/events/gateways/roles. Use for a process overview or to find a process id before calling get_process, get_model, who_owns or enumerate_paths; list_models covers every notation.",
 		annotations: READ_ONLY
 	}, safe(async () => {
 		if (!config()) return notAContentRepo();
@@ -1677,7 +1694,8 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		}));
 	}));
 	server.registerTool("get_process", {
-		description: "Get one process in full: the process view DERIVED from its BPMN — name, roles (BPMN lanes = owning teams), steps (activities with their role), events, gateways, the sequence/message flow, and the sub-processes it calls (callActivity → calledElement). Use for walkthroughs and any deep question about a single process.",
+		title: "Get BPMN process view",
+		description: "BPMN only: get one process in full — the process view DERIVED from its BPMN: name, roles (BPMN lanes = owning teams), steps (activities with their role), events, gateways, the sequence/message flow, and the sub-processes it calls (callActivity → calledElement). Use for walkthroughs and any deep question about a single process; get_view covers every notation.",
 		inputSchema: z.object({ id: z.string().describe("Process id = the .bpmn file name without extension, e.g. order-to-cash") }),
 		annotations: READ_ONLY
 	}, safe(async ({ id }) => {
@@ -1693,6 +1711,7 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		});
 	}));
 	server.registerTool("get_model", {
+		title: "Get model graph",
 		description: "Parse ANY model file into its generic graph: nodes (id, type, name), edges and meta — BPMN flows and lanes, DMN requirements, Wardley components/dependencies, … Use to see the raw structure, or to ground any 'how does X work' answer in the actual model.",
 		inputSchema: z.object({
 			id: z.string().describe("Model id = file stem (from list_models), e.g. order-to-cash"),
@@ -1711,7 +1730,8 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		}) : graph;
 	}));
 	server.registerTool("get_view", {
-		description: `The derived view of ANY model — its own name, a one-line summary, stats, and the rich notation payload in \`detail\` where one exists (process view, decision tables, …). The notation-agnostic sibling of get_process: works for every notation with extract+derive capabilities (${NOTATIONS.filter((n) => hasDeriver(n.id)).map((n) => n.id).join(", ")}).`,
+		title: "Get model view",
+		description: `The derived view of ANY model — its own name, a one-line summary, stats, and the rich notation payload in \`detail\` where one exists (the process view for BPMN, the decision tables for DMN). Works for every notation with extract+derive capabilities (${NOTATIONS.filter((n) => hasDeriver(n.id)).map((n) => n.id).join(", ")}).`,
 		inputSchema: z.object({
 			id: z.string().describe("Model id = file stem (from list_models), e.g. tea-shop"),
 			notation: z.string().optional().describe("registry notation id — disambiguates a stem shared across notations")
@@ -1732,6 +1752,7 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		});
 	}));
 	server.registerTool("enumerate_paths", {
+		title: "Enumerate flow paths",
 		description: "Enumerate the possible start→end paths through a model's flow (cycle-safe, capped) — BPMN sequence flows, Wardley dependencies, … per the notation's graph hints. Each path is the ordered list of element names. Use for walkthroughs ('what are the ways an order can go?'), test-case derivation, and spotting unexpected shortcuts or dead branches.",
 		inputSchema: z.object({
 			id: z.string().describe("Model id = file stem, e.g. order-to-cash"),
@@ -1757,6 +1778,7 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		});
 	}));
 	server.registerTool("find_cycles", {
+		title: "Find flow cycles",
 		description: "Detect cycles (loops) in a model's flow — BPMN rework/retry loops, circular Wardley dependencies, circular DMN requirements — per the notation's graph hints. Returns each cycle as the ordered list of element names. Use when analyzing complexity, rework cost, or 'why does this case never finish'.",
 		inputSchema: z.object({
 			id: z.string().describe("Model id = file stem, e.g. order-to-cash"),
@@ -1778,7 +1800,8 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		});
 	}));
 	server.registerTool("who_owns", {
-		description: "Resolve ownership of a process from its BPMN lanes — the roles/teams that own its steps (each lane, with the steps it contains) plus the pools (participants). Use for 'who owns X', 'who does what in X', or handoff questions. Note: on the slim contract ownership is whatever the model's lanes say; a process with no lanes has no modeled owner.",
+		title: "Find who owns a BPMN process",
+		description: "BPMN only: resolve ownership of a process from its lanes — the roles/teams that own its steps (each lane, with the steps it contains) plus the pools (participants). Use for 'who owns X', 'who does what in X', or handoff questions. Note: on the slim contract ownership is whatever the model's lanes say; a process with no lanes has no modeled owner.",
 		inputSchema: z.object({ id: z.string().describe("Process id, e.g. order-to-cash") }),
 		annotations: READ_ONLY
 	}, safe(async ({ id }) => {
@@ -1800,7 +1823,8 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		});
 	}));
 	server.registerTool("which_processes_use", {
-		description: "Impact analysis across the portfolio: find processes whose id, derived name, role/lane names, step names, or sub-process calls (calledElement) match a query — case-insensitive substring. Use for 'what calls invoice-handling', 'which processes have a Billing lane', 'what touches the credit check'.",
+		title: "Search BPMN processes",
+		description: "BPMN only: find processes whose id, derived name, role/lane names, step names, or sub-process calls (calledElement) match a query — case-insensitive substring. Use for 'what calls invoice-handling', 'which processes have a Billing lane', 'what touches the credit check'. which_models_use follows references across every notation.",
 		inputSchema: z.object({ query: z.string().describe("Case-insensitive substring, e.g. 'invoice-handling', 'Billing', 'credit'") }),
 		annotations: READ_ONLY
 	}, safe(async ({ query }) => {
@@ -1834,7 +1858,8 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		return ok(hits);
 	}));
 	server.registerTool("which_models_use", {
-		description: "Reference-level impact analysis across EVERY notation: all models whose typed cross-model references (callActivity calls, businessRuleTask decides, …) point at the given model id (file stem, exact match) — the repo-wide reference index behind it also flags dangling references. The registry-wide sibling of which_processes_use; use for 'what breaks if I change or delete this model?'.",
+		title: "Find models that reference a model",
+		description: "Reference-level impact analysis across EVERY notation: all models whose typed cross-model references (callActivity calls, businessRuleTask decides, …) point at the given model id (file stem, exact match) — the repo-wide reference index behind it also flags dangling references. Use for 'what breaks if I change or delete this model?'.",
 		inputSchema: z.object({ id: z.string().describe("Target model id = file stem (from list_models), e.g. 'credit-check'") }),
 		annotations: READ_ONLY
 	}, safe(async ({ id }) => {
@@ -1858,6 +1883,7 @@ function createMcpServer(root = DEFAULT_ROOT, todos, contributions = []) {
 		const { repo: todosRepo, token: todosToken } = todos;
 		const api = (todos.apiUrl ?? "https://api.github.com").replace(/\/$/, "");
 		server.registerTool("list_todos", {
+			title: "List open todos",
 			description: "List the OPEN model-anchored todos of this content repo — work items filed from the live model into the repo's issue tracker (label 'todo'). Each row carries the tracker id and URL, title, assignees, createdAt and the parsed anchor (process, model file, anchored BPMN elements). Optional filter on one process. Use for 'what is open on process X' or to cross-check a model answer against known open discrepancies.",
 			inputSchema: z.object({ process: z.string().optional().describe("Only todos anchored to this process id, e.g. order-to-cash") }),
 			annotations: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@miragon/design-iq-mcp",
-  "version": "5.0.0-rc.0",
-  "description": "Read-only MCP server exposing a BPM content repo's processes — discovered from designiq.yml, derived from the BPMN — to any MCP client.",
+  "version": "5.1.0",
+  "description": "Read-only MCP server exposing a designIQ content repo's models — BPMN processes, DMN decisions, Wardley Maps, Team Topologies, Event Storming boards, Context Maps and more — to any MCP client. Discovered from designiq.yml, views derived from the models.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -10,9 +10,15 @@
     "directory": "packages/mcp"
   },
   "keywords": [
+    "modeling",
+    "architecture",
     "bpm",
     "bpmn",
     "dmn",
+    "wardley-maps",
+    "team-topologies",
+    "event-storming",
+    "context-maps",
     "mcp",
     "model-context-protocol",
     "process-documentation"
@@ -35,17 +41,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/node": "2.1.0",
-    "@modelcontextprotocol/server": "2.1.0",
-    "fast-xml-parser": "5.11.1",
+    "@modelcontextprotocol/server": "2.2.0",
+    "fast-xml-parser": "5.11.2",
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "2.1.0",
+    "@modelcontextprotocol/client": "2.2.0",
     "tsdown": "0.23.0",
     "@designiq/contracts": "0.1.0",
-    "@designiq/http-kit": "0.1.0",
     "@designiq/github-app": "0.1.0",
+    "@designiq/http-kit": "0.1.0",
     "@designiq/mcp-kit": "0.1.0",
     "@designiq/notations": "0.1.0"
   },