callman-mcp 0.1.0

package/dist-cjs/lib/ids.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sequentialIds = exports.normalizeName = exports.isObjectId = exports.OBJECT_ID = void 0;
+exports.OBJECT_ID = /^[0-9a-fA-F]{24}$/;
+const isObjectId = (value) => typeof value === "string" && exports.OBJECT_ID.test(value);
+exports.isObjectId = isObjectId;
+const normalizeName = (value) => value.trim().toLowerCase();
+exports.normalizeName = normalizeName;
+// Deterministic, readable ids for generated documents (n1, n2 … / e1, e2 …).
+const sequentialIds = (prefix, taken = []) => {
+    const used = new Set(taken);
+    let counter = 1;
+    return () => {
+        let candidate = `${prefix}${counter}`;
+        while (used.has(candidate)) {
+            counter += 1;
+            candidate = `${prefix}${counter}`;
+        }
+        used.add(candidate);
+        counter += 1;
+        return candidate;
+    };
+};
+exports.sequentialIds = sequentialIds;

package/dist-cjs/lib/log.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silentLogger = exports.createLogger = void 0;
+const RANK = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 };
+const createLogger = (level, sink = (line) => console.error(line)) => {
+    const emit = (severity, message, meta) => {
+        if (RANK[severity] > RANK[level])
+            return;
+        const suffix = meta === undefined ? "" : ` ${safeJson(meta)}`;
+        sink(`[callman-mcp] ${severity}: ${message}${suffix}`);
+    };
+    return {
+        error: (message, meta) => emit("error", message, meta),
+        warn: (message, meta) => emit("warn", message, meta),
+        info: (message, meta) => emit("info", message, meta),
+        debug: (message, meta) => emit("debug", message, meta),
+    };
+};
+exports.createLogger = createLogger;
+exports.silentLogger = { error() { }, warn() { }, info() { }, debug() { } };
+const safeJson = (value) => {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+};

package/dist-cjs/lib/mask.js

@@ -0,0 +1,72 @@
+"use strict";
+// Secret masking on the way OUT to the model. The backend already masks
+// environment values for a personal token; this covers what it does not —
+// request auth secrets, sensitive headers and anything a local run resolved.
+// Same sentinel as the backend so a masked value is recognisable and can
+// never be written back by accident (the server rejects it).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskVariableValues = exports.maskAuth = exports.maskHeaderRecord = exports.maskHeaderValue = exports.isSensitiveHeader = exports.isMasked = exports.maskSecret = exports.MASK_SENTINEL = void 0;
+exports.MASK_SENTINEL = "••••";
+const maskSecret = (value) => value.length >= 8 ? `${exports.MASK_SENTINEL}${value.slice(-2)}` : exports.MASK_SENTINEL;
+exports.maskSecret = maskSecret;
+const isMasked = (value) => typeof value === "string" && value.startsWith(exports.MASK_SENTINEL);
+exports.isMasked = isMasked;
+const SENSITIVE_HEADERS = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-auth-token",
+    "api-key",
+]);
+const isSensitiveHeader = (name) => SENSITIVE_HEADERS.has(name.trim().toLowerCase());
+exports.isSensitiveHeader = isSensitiveHeader;
+const maskHeaderValue = (name, value) => (0, exports.isSensitiveHeader)(name) && value ? (0, exports.maskSecret)(value) : value;
+exports.maskHeaderValue = maskHeaderValue;
+const maskHeaderRecord = (headers) => {
+    const out = {};
+    for (const [key, value] of Object.entries(headers ?? {}))
+        out[key] = (0, exports.maskHeaderValue)(key, value);
+    return out;
+};
+exports.maskHeaderRecord = maskHeaderRecord;
+// Compact, masked view of a request's auth: enough to know HOW it
+// authenticates, never the credential itself.
+const maskAuth = (auth) => {
+    const type = auth?.type ?? "none";
+    switch (type) {
+        case "bearer":
+            return { type, token: auth?.bearerToken ? (0, exports.maskSecret)(auth.bearerToken) : "" };
+        case "basic":
+            return {
+                type,
+                username: auth?.basicUsername ?? "",
+                password: auth?.basicPassword ? (0, exports.maskSecret)(auth.basicPassword) : "",
+            };
+        case "apikey":
+            return {
+                type,
+                key: auth?.apiKeyKey ?? "",
+                value: auth?.apiKeyValue ? (0, exports.maskSecret)(auth.apiKeyValue) : "",
+                location: auth?.apiKeyLocation ?? "header",
+            };
+        case "oauth2": {
+            const oauth2 = auth?.oauth2 ?? {};
+            return {
+                type,
+                grantType: oauth2.grantType ?? "client_credentials",
+                tokenUrl: oauth2.tokenUrl ?? "",
+                clientId: oauth2.clientId ?? "",
+                clientSecret: typeof oauth2.clientSecret === "string" && oauth2.clientSecret ? (0, exports.maskSecret)(oauth2.clientSecret) : "",
+                scope: oauth2.scope ?? "",
+            };
+        }
+        default:
+            return { type: "none" };
+    }
+};
+exports.maskAuth = maskAuth;
+// Mask every `value` in a key/value list (environment / scenario variables).
+const maskVariableValues = (variables) => variables.map((variable) => ({ ...variable, value: (0, exports.maskSecret)(variable.value), valueMasked: true }));
+exports.maskVariableValues = maskVariableValues;

package/dist-cjs/lib/pagination.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sliceWithCursor = exports.nextCursorFor = exports.pageFromCursor = exports.clampLimit = exports.decodeCursor = exports.encodeCursor = void 0;
+const truncate_js_1 = require("./truncate.js");
+const encodeCursor = (cursor) => Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+exports.encodeCursor = encodeCursor;
+const decodeCursor = (raw) => {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+        if (typeof parsed.page !== "number" || typeof parsed.limit !== "number")
+            return null;
+        if (!Number.isInteger(parsed.page) || parsed.page < 1)
+            return null;
+        return { page: parsed.page, limit: (0, exports.clampLimit)(parsed.limit) };
+    }
+    catch {
+        return null;
+    }
+};
+exports.decodeCursor = decodeCursor;
+const clampLimit = (limit) => Math.min(truncate_js_1.LIMITS.LIST_MAX, Math.max(1, Math.floor(limit ?? truncate_js_1.LIMITS.LIST_DEFAULT)));
+exports.clampLimit = clampLimit;
+const pageFromCursor = (cursor, limit) => {
+    const decoded = (0, exports.decodeCursor)(cursor);
+    if (decoded)
+        return decoded;
+    return { page: 1, limit: (0, exports.clampLimit)(limit) };
+};
+exports.pageFromCursor = pageFromCursor;
+const nextCursorFor = (pagination) => pagination.page < pagination.totalPages
+    ? (0, exports.encodeCursor)({ page: pagination.page + 1, limit: pagination.limit })
+    : null;
+exports.nextCursorFor = nextCursorFor;
+// Client-side slice for list endpoints that are not paginated server-side.
+const sliceWithCursor = (items, cursor, limit) => {
+    const { page, limit: size } = (0, exports.pageFromCursor)(cursor, limit);
+    const start = (page - 1) * size;
+    const slice = items.slice(start, start + size);
+    const totalPages = Math.max(1, Math.ceil(items.length / size));
+    return {
+        items: slice,
+        total: items.length,
+        nextCursor: page < totalPages ? (0, exports.encodeCursor)({ page: page + 1, limit: size }) : null,
+    };
+};
+exports.sliceWithCursor = sliceWithCursor;

package/dist-cjs/lib/truncate.js

@@ -0,0 +1,52 @@
+"use strict";
+// Output-size discipline: every tool result is bounded so a large workspace
+// can never blow a model's context. The caps are deliberate constants — a
+// tool that needs more takes an explicit `full: true` and still hits the
+// FULL_* ceilings, reporting `truncated: true` when it does.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.byteLength = exports.safeStringify = exports.jsonPreview = exports.clipBytes = exports.clip = exports.LIMITS = void 0;
+exports.LIMITS = Object.freeze({
+    URL: 120,
+    NAME: 120,
+    BODY_PREVIEW: 2_000,
+    FULL_BODY: 64 * 1024,
+    RUN_BODY_DEFAULT: 16 * 1024,
+    RUN_BODY_MAX: 256 * 1024,
+    SCENARIO_FULL: 256 * 1024,
+    DIAGRAM_FULL: 512 * 1024,
+    SEARCH_RESULTS: 50,
+    TREE_ITEMS: 5_000,
+    LIST_DEFAULT: 50,
+    LIST_MAX: 100,
+});
+const clip = (value, max) => value.length > max ? `${value.slice(0, max)}…` : value;
+exports.clip = clip;
+// Byte-bounded clip for bodies (UTF-8 aware: cut on a character boundary).
+const clipBytes = (value, maxBytes) => {
+    const totalBytes = Buffer.byteLength(value, "utf8");
+    if (totalBytes <= maxBytes)
+        return { text: value, truncated: false, totalBytes };
+    let end = Math.min(value.length, maxBytes);
+    while (end > 0 && Buffer.byteLength(value.slice(0, end), "utf8") > maxBytes)
+        end -= Math.ceil((end * 0.05) || 1);
+    return { text: `${value.slice(0, end)}…`, truncated: true, totalBytes };
+};
+exports.clipBytes = clipBytes;
+const jsonPreview = (value, max = exports.LIMITS.BODY_PREVIEW) => {
+    if (value === null || value === undefined)
+        return null;
+    const text = typeof value === "string" ? value : (0, exports.safeStringify)(value);
+    return (0, exports.clip)(text, max);
+};
+exports.jsonPreview = jsonPreview;
+const safeStringify = (value, space) => {
+    try {
+        return JSON.stringify(value, null, space) ?? "null";
+    }
+    catch {
+        return String(value);
+    }
+};
+exports.safeStringify = safeStringify;
+const byteLength = (value) => Buffer.byteLength(typeof value === "string" ? value : (0, exports.safeStringify)(value), "utf8");
+exports.byteLength = byteLength;

package/dist-cjs/main.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silentLogger = exports.createLogger = exports.CallmanApi = exports.CallmanHttpClient = exports.hintFor = exports.ToolInputError = exports.CallmanNetworkError = exports.CallmanApiError = exports.toolAvailability = exports.TOOL_CATALOG = exports.createToolContext = exports.resolveConfig = exports.normalizeApiUrl = exports.DEFAULT_CLOUD_API_URL = exports.SERVER_NAME = exports.SERVER_INSTRUCTIONS = exports.createCallmanMcpServer = void 0;
+// Library entry (`import { createCallmanMcpServer } from "callman-mcp"`) —
+// for hosts that embed the tool layer (the Callman backend's remote MCP
+// endpoint) and for tests. The bin lives in index.ts.
+var server_js_1 = require("./server.js");
+Object.defineProperty(exports, "createCallmanMcpServer", { enumerable: true, get: function () { return server_js_1.createCallmanMcpServer; } });
+Object.defineProperty(exports, "SERVER_INSTRUCTIONS", { enumerable: true, get: function () { return server_js_1.SERVER_INSTRUCTIONS; } });
+Object.defineProperty(exports, "SERVER_NAME", { enumerable: true, get: function () { return server_js_1.SERVER_NAME; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "DEFAULT_CLOUD_API_URL", { enumerable: true, get: function () { return config_js_1.DEFAULT_CLOUD_API_URL; } });
+Object.defineProperty(exports, "normalizeApiUrl", { enumerable: true, get: function () { return config_js_1.normalizeApiUrl; } });
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_js_1.resolveConfig; } });
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "createToolContext", { enumerable: true, get: function () { return context_js_1.createToolContext; } });
+var catalog_js_1 = require("./tools/catalog.js");
+Object.defineProperty(exports, "TOOL_CATALOG", { enumerable: true, get: function () { return catalog_js_1.TOOL_CATALOG; } });
+Object.defineProperty(exports, "toolAvailability", { enumerable: true, get: function () { return catalog_js_1.toolAvailability; } });
+var errors_js_1 = require("./client/errors.js");
+Object.defineProperty(exports, "CallmanApiError", { enumerable: true, get: function () { return errors_js_1.CallmanApiError; } });
+Object.defineProperty(exports, "CallmanNetworkError", { enumerable: true, get: function () { return errors_js_1.CallmanNetworkError; } });
+Object.defineProperty(exports, "ToolInputError", { enumerable: true, get: function () { return errors_js_1.ToolInputError; } });
+Object.defineProperty(exports, "hintFor", { enumerable: true, get: function () { return errors_js_1.hintFor; } });
+var http_js_1 = require("./client/http.js");
+Object.defineProperty(exports, "CallmanHttpClient", { enumerable: true, get: function () { return http_js_1.CallmanHttpClient; } });
+var api_js_1 = require("./client/api.js");
+Object.defineProperty(exports, "CallmanApi", { enumerable: true, get: function () { return api_js_1.CallmanApi; } });
+var log_js_1 = require("./lib/log.js");
+Object.defineProperty(exports, "createLogger", { enumerable: true, get: function () { return log_js_1.createLogger; } });
+Object.defineProperty(exports, "silentLogger", { enumerable: true, get: function () { return log_js_1.silentLogger; } });

package/dist-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist-cjs/prompts/index.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPrompts = void 0;
+const zod_1 = require("zod");
+// Prompts: reusable playbooks a user picks in their client ("/callman:…").
+// Each one tells the model which resources to read and which tools to call,
+// in which order — the workflows that need discipline to come out right.
+const user = (text) => ({ messages: [{ role: "user", content: { type: "text", text } }] });
+const where = (workspace) => (workspace ? ` in the Callman workspace "${workspace}"` : "");
+const registerPrompts = (server, _ctx) => {
+    server.registerPrompt("import_endpoints_from_code", {
+        title: "Import the endpoints of this codebase into Callman",
+        description: "Find the HTTP routes in the project's source, build one request per endpoint (method, path, query, headers, body from the DTO) and create them in a Callman collection with folders per resource.",
+        argsSchema: {
+            path: zod_1.z.string().optional().describe("Directory or file to scan (default: the whole project)"),
+            collection: zod_1.z.string().optional().describe("Target collection name (existing or new); default: named after the project"),
+            workspace: zod_1.z.string().optional(),
+        },
+    }, ({ path, collection, workspace }) => user(`Import the HTTP endpoints defined in ${path ? `\`${path}\`` : "this project"} into Callman${where(workspace)}.
+
+Steps:
+1. Call \`whoami\` to confirm the connection${workspace ? "" : " and the workspace"}.
+2. Read the routing code yourself (framework route definitions, controllers, OpenAPI files if present). For every endpoint collect: method, path (turn \`:id\` / \`{id}\` params into Callman path variables \`:id\`), query parameters, required headers, and a realistic JSON body from the request DTO/validation schema. Group endpoints by resource (users, orders …) — one folder per resource.
+3. Use \`{{baseUrl}}\` for the host. Note which environment variables the collection needs (baseUrl, accessToken …).
+4. Call \`list_collections\`. If a collection named "${collection ?? "<project name>"}" exists, add to it with \`create_requests_bulk\` (\`collection:\`); otherwise create it with \`create_requests_bulk\` (\`collectionName:\` + \`folders\` skeleton + \`folderKey\` per request). For more than 50 requests run with \`dryRun: true\` first and show me the summary.
+5. If the API has a login/token endpoint, give that request a \`postResponseScript\` that stores the token: \`pm.environment.set("accessToken", pm.response.json().token)\`, and use \`{ "type": "bearer", "token": "{{accessToken}}" }\` on the others.
+6. Offer to create an environment (\`create_environment\`) with the variables you found, with placeholder values I must fill in.
+7. Finish with a short summary: collection, folders, request count, variables to set.`));
+    server.registerPrompt("design_system_diagram", {
+        title: "Draw a system-design diagram of this codebase",
+        description: "Identify services, data stores, queues, external APIs and infrastructure in the project and draw an architecture diagram in Callman's Diagram Studio.",
+        argsSchema: {
+            scope: zod_1.z.string().optional().describe("What to diagram (default: the whole system); e.g. 'the order pipeline'"),
+            name: zod_1.z.string().optional().describe("Diagram name"),
+        },
+    }, ({ scope, name }) => user(`Draw a system-design diagram of ${scope ? scope : "this system"} in Callman.
+
+Steps:
+1. Read \`callman://diagram/components\` — use ONLY those \`type\` values.
+2. From the code and configuration (docker-compose, Kubernetes manifests, terraform, env files, package manifests) identify: services/apps, databases and caches, message brokers/queues, external APIs, auth providers, observability, cloud resources, and the boundaries they live in (VPC, cluster, namespace).
+3. Model 8–25 nodes with 1–3 word labels. Put components inside boundaries with \`parent\` (declare the container node). Give each edge a meaning: \`sync\` for request/response calls, \`async\` for events/callbacks, \`bus\` for streams/queues, \`fallback\` for retries or optional paths. Short edge labels (protocol or event name) only where they add information.
+4. Call \`create_diagram\` with \`name: "${name ?? "<system name>"}"\`, no positions (automatic layout). If it reports unknown types, fix them with the suggestions and retry.
+5. Describe the diagram in a few sentences and tell me it is in the Callman Diagrams library (Refresh to see it). For corrections use \`patch_diagram\`, not a full rebuild.`));
+    server.registerPrompt("create_scenario_from_flow", {
+        title: "Create a test scenario for a user flow",
+        description: "Turn a described flow (e.g. 'sign up, log in, create an order, check it appears') into a runnable Callman scenario using the saved requests.",
+        argsSchema: {
+            flow: zod_1.z.string().describe("The flow to test, in plain words"),
+            collection: zod_1.z.string().optional().describe("Collection whose requests to use"),
+            workspace: zod_1.z.string().optional(),
+        },
+    }, ({ flow, collection, workspace }) => user(`Create a Callman scenario that tests this flow${where(workspace)}: ${flow}
+
+Steps:
+1. Read \`callman://docs/scenario-nodes\` for the node types and their config fields.
+2. Find the requests to reuse with \`search_requests\`${collection ? ` in the collection "${collection}"` : ""} and read the ones you need with \`get_request\` (method, url, body, auth). Request nodes carry their own config — copy method/url/headers/body from the saved request and use \`{{variables}}\` for values produced by earlier steps.
+3. Build the graph: one \`request\` node per call; an \`assertion\` node after each important response (status code, key fields); \`set-vars\` to capture ids/tokens from responses for later steps; a \`condition\` with \`yes\`/\`no\` edges where the flow branches; \`poll\` for eventually-consistent checks; an \`end\` node last. Add a scenario environment with the variables the flow needs.
+4. Call \`create_scenario\` with \`dryRun: true\`, review the resolved graph, then create it for real.
+5. Offer to run it with \`run_scenario\` and to explain the report. On-prem: mention that the scenario is a draft until approved in the desktop app.`));
+    server.registerPrompt("document_collection", {
+        title: "Document an API collection",
+        description: "Read a Callman collection and write API documentation (Markdown or an OpenAPI skeleton) from its requests.",
+        argsSchema: {
+            collection: zod_1.z.string().describe("Collection id or name"),
+            format: zod_1.z.string().optional().describe("markdown (default) or openapi"),
+            workspace: zod_1.z.string().optional(),
+        },
+    }, ({ collection, format, workspace }) => user(`Document the Callman collection "${collection}"${where(workspace)} as ${format === "openapi" ? "an OpenAPI 3.1 skeleton" : "Markdown"}.
+
+Steps:
+1. \`get_collection_tree\` for the folders and requests, then \`get_request\` (\`full: true\`) for each request you document. Secrets stay masked — never try to reveal them.
+2. Group by folder. For each request: purpose (infer from the name/URL), method + path, path/query parameters, headers that matter, a request body example, what the post-response script asserts (as the expected response), and the variables it depends on.
+3. Write the document to a file in the project (e.g. \`docs/api/${collection.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}.${format === "openapi" ? "yaml" : "md"}\`) and summarise what it covers and what was unclear.`));
+};
+exports.registerPrompts = registerPrompts;

package/dist-cjs/resources/docs/diagramSchema.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIAGRAM_SCHEMA_DOC = void 0;
+exports.DIAGRAM_SCHEMA_DOC = `# Diagrams (create_diagram, update_diagram, patch_diagram)
+
+A diagram is a **DiagramDocument** (schemaVersion 1): typed nodes with positions and sizes,
+edges between nodes, a title. You write the compact form below; the server assigns ids,
+sizes from the component catalog, edge styles from the semantic, and lays the nodes out.
+
+## Compact input
+\`\`\`jsonc
+{
+  "name": "Order platform",             // library entry name
+  "title": "Order platform — runtime view",
+  "nodes": [
+    { "id": "gw",    "type": "net.gateway",   "label": "API Gateway" },
+    { "id": "orders","type": "net.service",   "label": "Orders service", "parent": "k8s" },
+    { "id": "k8s",   "type": "net.zone",      "label": "Kubernetes" },      // a container
+    { "id": "db",    "type": "db.postgres",   "label": "orders db" },
+    { "id": "bus",   "type": "mq.kafka",      "label": "events" }
+  ],
+  "edges": [
+    { "source": "gw",     "target": "orders", "label": "REST",  "semantic": "sync" },
+    { "source": "orders", "target": "db",     "semantic": "sync" },
+    { "source": "orders", "target": "bus",    "label": "OrderCreated" }   // → bus automatically
+  ]
+}
+\`\`\`
+
+- \`type\` MUST be a catalog type — read \`callman://diagram/components\` (or one category:
+  \`callman://diagram/components/aws\`). Unknown types are rejected with suggestions; pass
+  \`strictTypes: false\` to draw them as plain rectangles instead.
+- \`parent\` puts a node inside a container node (zones, frames, pools). Declare the
+  container as a node too.
+- Edge \`semantic\`: \`sync\` (solid — request/response, default), \`async\` (dashed — event,
+  callback), \`fallback\` (dotted — retry / optional path), \`bus\` (heavy — message bus /
+  stream; automatic when an endpoint is a messaging component).
+- Positions are optional; when any node lacks one the whole diagram is laid out
+  (\`direction\`: DOWN, RIGHT, UP, LEFT). Give explicit \`position: {x,y}\` only when the user
+  asks for a specific arrangement.
+- Keep diagrams readable: 8–25 nodes, labels of 1–3 words, one edge per relationship.
+
+## Editing: patch_diagram ops
+\`\`\`jsonc
+{ "op": "addNode",    "node": { "type": "db.redis", "label": "cache" } }
+{ "op": "updateNode", "id": "orders", "changes": { "label": "Orders API" } }
+{ "op": "removeNode", "id": "bus" }                 // its edges are removed too
+{ "op": "addEdge",    "edge": { "source": "orders", "target": "n6", "semantic": "async" } }
+{ "op": "updateEdge", "id": "e2", "changes": { "label": "gRPC" } }
+{ "op": "removeEdge", "id": "e3" }
+{ "op": "setTitle",   "title": "New title" }
+\`\`\`
+\`relayout\`: \`new\` (default — only new nodes get a place), \`all\` (re-run layout), \`none\`.
+
+## Stored document (get_diagram view: "full")
+\`\`\`ts
+interface DiagramDocument {
+  schemaVersion: 1; id: string;
+  meta: { title: string; createdAt: string; updatedAt: string };
+  canvas?: { background?: "grid" | "dots" | "blank"; gridSize?: number };
+  nodes: { id; type; position: {x,y}; size: {width,height}; label?; parentId?; style?; data? }[];
+  edges: { id; source?; target?; label?; routing?; style?; markerEnd?; waypoints? }[];
+}
+\`\`\`
+Edge meaning is derived from \`style\` (dashed + dashPattern + strokeWidth) — you never set
+style directly; use \`semantic\`.
+`;

package/dist-cjs/resources/docs/overview.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERVIEW_DOC = void 0;
+exports.OVERVIEW_DOC = `# Working with Callman through MCP
+
+Callman is an API client and test platform (collections of HTTP requests, environments,
+multi-step test scenarios, system-design diagrams). This server exposes it to you through
+tools; everything you do goes to the same server the Callman desktop app uses, as the user
+whose token is configured, limited to that token's permissions and the user's workspace role.
+
+## Start here
+1. \`whoami\` — proves the connection and tells you the workspaces, features and which tools
+   this token can use. If several workspaces exist and none is default, pass \`workspace\`
+   to workspace-scoped tools (or ask the user which one).
+2. Look before you create: \`list_collections\` / \`get_collection_tree\` / \`search_requests\`.
+   Creating a collection whose name exists is refused on purpose.
+3. Names work as references everywhere an id does (collection, folder, request, environment,
+   scenario, diagram, workspace). Ambiguous names come back as a candidate list — pick one.
+4. Preview big writes with \`dryRun: true\` (bulk create, imports, scenarios, diagrams).
+5. Deletions need \`confirm: true\`. Ask the user unless they explicitly requested the deletion.
+
+## Requests
+- Use \`{{variable}}\` for hosts and secrets (\`{{baseUrl}}/users\`) and put the values in an
+  environment (\`create_environment\` / \`set_environment_variables\`). Use \`:id\` for path
+  variables. See \`callman://docs/request-schema\`.
+- Bodies: a JSON value, a raw string, or \`{ mode: raw|formdata|urlencoded }\`.
+- Scripts run in a sandbox with the \`pm.*\` API — \`callman://docs/scripting/pm-api\`.
+- \`run_request\` / \`run_collection\` execute on the user's machine with real variable values;
+  you only get results and the names of variables scripts changed.
+
+## Secrets
+Environment values come back masked (\`••••ab\`) unless the token holds \`environments:reveal\`
+and you ask for \`reveal: true\`. Never write a masked value back — the server refuses it.
+
+## Scenarios
+Multi-step flows as a graph of typed nodes (request, condition, assertion, set-vars, poll,
+db, kafka, script, wait, end …). Read \`callman://docs/scenario-nodes\` before building one;
+partial node configs are merged over defaults. Runs happen on the server (\`run_scenario\`).
+
+## Diagrams
+System-design diagrams use a fixed component catalog — \`callman://diagram/components\`.
+Build with \`create_diagram\` (auto layout), edit with \`patch_diagram\`, share with
+\`share_diagram\`. See \`callman://docs/diagram-schema\`.
+
+## After writing
+The desktop app refreshes when the user switches back to it. Tell the user what you created
+and where (collection / folder names).
+`;

package/dist-cjs/resources/docs/requestSchema.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_SCHEMA_DOC = void 0;
+exports.REQUEST_SCHEMA_DOC = `# Request input (create_request, create_requests_bulk, update_request)
+
+\`\`\`jsonc
+{
+  "name": "Create order",                 // 1–120 chars, shown in the sidebar
+  "method": "POST",                       // GET POST PUT PATCH DELETE HEAD OPTIONS TRACE
+  "url": "{{baseUrl}}/orders/:orderId",   // {{var}} = environment/global variable, :name = path variable
+  "headers": [{ "key": "Content-Type", "value": "application/json" }],
+  "query":   [{ "key": "expand", "value": "items", "enabled": true }],
+  "pathVariables": [{ "key": "orderId", "value": "123" }],
+  "body": { "sku": "A1", "qty": 2 },      // see Body
+  "auth": { "type": "bearer", "token": "{{accessToken}}" },   // see Auth
+  "preRequestScript": "",                 // pm.* script before sending
+  "postResponseScript": "pm.test('created', () => pm.response.to.have.status(201));\\npm.environment.set('orderId', pm.response.json().id);",
+  "testsScript": "",                      // legacy tests script (same API)
+  "folder": "Orders/Write",               // folder id, name or path (create_request / existing collection)
+  "folderKey": "orders"                   // create_requests_bulk with collectionName: key from \`folders\`
+}
+\`\`\`
+
+## Body
+| You send | Stored as |
+|---|---|
+| a JSON object / array / number / boolean | that JSON value (JSON tab in the editor) |
+| a string | parsed as JSON when valid; otherwise raw text/xml/html by sniffing |
+| \`{ "mode": "raw", "raw": "<xml/>", "language": "xml" }\` | raw body with that language (json, xml, text, html) |
+| \`{ "mode": "formdata", "entries": [{ "key": "file", "value": "a.txt" }] }\` | multipart form |
+| \`{ "mode": "urlencoded", "entries": [ … ] }\` | x-www-form-urlencoded |
+| \`{ "mode": "none" }\` or omitted | no body |
+
+Set \`Content-Type\` yourself for raw non-JSON bodies; JSON gets it automatically at send time.
+
+## Auth
+\`\`\`jsonc
+{ "type": "none" }
+{ "type": "bearer", "token": "{{accessToken}}" }
+{ "type": "basic", "username": "{{user}}", "password": "{{pass}}" }
+{ "type": "apiKey", "key": "X-API-Key", "value": "{{apiKey}}", "location": "header" }   // or "query"
+{ "type": "oauth2", "grantType": "client_credentials", "tokenUrl": "{{authUrl}}/token",
+  "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}", "scope": "read write" }
+\`\`\`
+Prefer \`{{variables}}\` over literal secrets — the environment keeps them out of the request.
+
+## Variables
+- \`{{name}}\` resolves from the active environment, then global variables, then values set
+  by scripts during a run (\`pm.environment.set\`).
+- Dynamic values: \`{{$uuid}}\`, \`{{$timestamp}}\`, \`{{$randomInt}}\`, \`{{$randomEmail}}\` … —
+  see \`callman://docs/scripting/templating\`.
+- Data-driven rows: \`{{data.column}}\`.
+
+## Scripts (pm.* API)
+\`pm.test(name, fn)\`, \`pm.expect(value)\`, \`pm.response.json()\` / \`.code\` / \`.headers\`,
+\`pm.environment.set/get\`, \`pm.globals\`, \`pm.variables\`, \`pm.request\`, \`pm.sendRequest\`,
+\`pm.db.query\` (when a DB connection is attached). Full reference:
+\`callman://docs/scripting/pm-api\`; sandbox limits: \`callman://docs/scripting/sandbox\`.
+
+## Folder skeleton (create_requests_bulk with collectionName)
+\`\`\`jsonc
+{
+  "collectionName": "Users API",
+  "folders": [
+    { "key": "users", "name": "Users" },
+    { "key": "users-admin", "name": "Admin", "parentKey": "users" }
+  ],
+  "requests": [ { "name": "List users", "method": "GET", "url": "{{baseUrl}}/users", "folderKey": "users" } ]
+}
+\`\`\`
+The whole payload is created atomically (all or nothing).
+`;