callman-mcp 0.1.0

package/dist-cjs/tools/environments.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEnvironmentTools = void 0;
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const requestShape_js_1 = require("../domain/requestShape.js");
+const resolve_js_1 = require("../domain/resolve.js");
+const mask_js_1 = require("../lib/mask.js");
+const truncate_js_1 = require("../lib/truncate.js");
+const lookups_js_1 = require("./lookups.js");
+const shared_js_1 = require("./shared.js");
+// Environments hold the values requests reference as {{key}}. Values come
+// back MASKED for a personal token (••••ab) unless the token holds
+// environments:reveal AND the call asks for reveal — the server enforces
+// both; this side only forwards the flag and refuses to write a masked
+// value back.
+const registerEnvironmentTools = (server, ctx) => {
+    server.registerTool("list_environments", {
+        title: "List environments",
+        description: "List a workspace's environments with their variable KEYS (values are not included). Global variables (shared by every environment) are listed too.",
+        inputSchema: { workspace: shared_js_1.workspaceArg },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const [environments, globals] = await Promise.all([
+            (0, lookups_js_1.loadEnvironments)(ctx, ws.id),
+            ctx.api.listGlobalVariables(ws.id).catch(() => []),
+        ]);
+        return (0, shared_js_1.ok)({
+            workspace: { id: ws.id, name: ws.name },
+            environments: environments.map((environment) => ({
+                id: environment.id,
+                name: environment.name,
+                variableCount: environment.variables.length,
+                variableKeys: environment.variables.map((variable) => variable.key).slice(0, 200),
+            })),
+            globalVariableKeys: globals.map((variable) => variable.key),
+        });
+    }));
+    server.registerTool("get_environment", {
+        title: "Get an environment",
+        description: "Read one environment's variables. Values are masked (••••ab) unless reveal: true AND the token holds environments:reveal. Global variables are returned alongside.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, environment: (0, shared_js_1.refArg)("Environment"), reveal: zod_1.z.boolean().optional() },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, environment, reveal }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveEnvironment)(ctx, ws.id, environment);
+        const [fresh, globals] = await Promise.all([
+            ctx.api.getEnvironment(ws.id, resolved.item.id, reveal ?? false),
+            ctx.api.listGlobalVariables(ws.id, reveal ?? false).catch(() => []),
+        ]);
+        const masked = fresh.variables.some((variable) => variable.valueMasked);
+        return (0, shared_js_1.ok)({
+            environment: {
+                id: fresh.id,
+                name: fresh.name,
+                variables: fresh.variables.map((variable) => ({ key: variable.key, value: variable.value, ...(variable.enabled === false ? { enabled: false } : {}) })),
+            },
+            globalVariables: globals.map((variable) => ({ key: variable.key, value: variable.value })),
+            valuesMasked: masked,
+            ...(masked && reveal ? { note: "Values stayed masked: the token lacks environments:reveal." } : {}),
+            resolved: [(0, resolve_js_1.resolvedSummary)(environment, resolved)],
+        });
+    }));
+    server.registerTool("create_environment", {
+        title: "Create an environment",
+        description: "Create an environment with optional variables (key/value). Use it for hosts ({{baseUrl}}) and credentials so requests never hard-code them.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            name: zod_1.z.string().min(1).max(truncate_js_1.LIMITS.NAME),
+            variables: zod_1.z.array(requestShape_js_1.kvSchema).max(500).optional(),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, name, variables }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const rows = (0, requestShape_js_1.toRows)(variables);
+        const maskedKeys = rows.filter((row) => (0, mask_js_1.isMasked)(row.value)).map((row) => row.key);
+        if (maskedKeys.length > 0)
+            throw new errors_js_1.ToolInputError("MASKED_VALUE", `Masked values cannot be stored (keys: ${maskedKeys.join(", ")}). Provide the real values.`);
+        const created = await ctx.api.createEnvironment(ws.id, { name: name.trim(), variables: rows });
+        ctx.invalidate(`environments:${ws.id}`);
+        return (0, shared_js_1.ok)({ environment: { id: created.id, name: created.name, variableKeys: created.variables.map((variable) => variable.key) } });
+    }));
+    server.registerTool("set_environment_variables", {
+        title: "Set / unset environment variables",
+        description: "Upsert variables (`set`) and/or remove keys (`unset`) in an environment. Existing keys are updated in place, new keys appended, other keys untouched. A masked value (starting with ••••) is refused — read it with reveal or supply a real value.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            environment: (0, shared_js_1.refArg)("Environment"),
+            set: zod_1.z.array(requestShape_js_1.kvSchema).max(500).optional(),
+            unset: zod_1.z.array(zod_1.z.string().min(1).max(100)).max(500).optional(),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, environment, set, unset }) => {
+        const rows = (0, requestShape_js_1.toRows)(set);
+        const removals = (unset ?? []).map((key) => key.trim()).filter(Boolean);
+        if (rows.length === 0 && removals.length === 0)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass set and/or unset.");
+        const maskedKeys = rows.filter((row) => (0, mask_js_1.isMasked)(row.value)).map((row) => row.key);
+        if (maskedKeys.length > 0)
+            throw new errors_js_1.ToolInputError("MASKED_VALUE", `Masked values cannot be written back (keys: ${maskedKeys.join(", ")}).`);
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveEnvironment)(ctx, ws.id, environment);
+        const existingKeys = new Set(resolved.item.variables.map((variable) => variable.key));
+        const updated = [];
+        const added = [];
+        const removed = [];
+        const failed = [];
+        for (const row of rows) {
+            try {
+                if (existingKeys.has(row.key)) {
+                    await ctx.api.updateEnvironmentVariable(ws.id, resolved.item.id, row.key, { value: row.value });
+                    updated.push(row.key);
+                }
+                else {
+                    await ctx.api.addEnvironmentVariable(ws.id, resolved.item.id, { key: row.key, value: row.value });
+                    added.push(row.key);
+                    existingKeys.add(row.key);
+                }
+            }
+            catch (error) {
+                failed.push({ key: row.key, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        for (const key of removals) {
+            try {
+                if (!existingKeys.has(key))
+                    continue;
+                await ctx.api.deleteEnvironmentVariable(ws.id, resolved.item.id, key);
+                removed.push(key);
+            }
+            catch (error) {
+                failed.push({ key, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        ctx.invalidate(`environments:${ws.id}`);
+        return (0, shared_js_1.ok)({ environment: { id: resolved.item.id, name: resolved.item.name }, updated, added, removed, failed, resolved: [(0, resolve_js_1.resolvedSummary)(environment, resolved)] });
+    }));
+    server.registerTool("delete_environment", {
+        title: "Delete an environment",
+        description: "Delete an environment and all its variables. Permanent — confirm with the user first.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, environment: (0, shared_js_1.refArg)("Environment"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, environment, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "an environment");
+        const ws = await ctx.resolveWorkspace(workspace);
+        const resolved = await (0, lookups_js_1.resolveEnvironment)(ctx, ws.id, environment);
+        await ctx.api.deleteEnvironment(ws.id, resolved.item.id);
+        ctx.invalidate(`environments:${ws.id}`);
+        return (0, shared_js_1.ok)({ deleted: { id: resolved.item.id, name: resolved.item.name }, resolved: [(0, resolve_js_1.resolvedSummary)(environment, resolved)] });
+    }));
+};
+exports.registerEnvironmentTools = registerEnvironmentTools;

package/dist-cjs/tools/import.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestRef = exports.registerImportTools = void 0;
+const callman_core_1 = require("callman-core");
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const importDetect_js_1 = require("../domain/importDetect.js");
+const resolve_js_1 = require("../domain/resolve.js");
+const truncate_js_1 = require("../lib/truncate.js");
+const lookups_js_1 = require("./lookups.js");
+const shared_js_1 = require("./shared.js");
+const CONTENT_MAX = 8 * 1024 * 1024;
+const IMPORT_FORMATS = ["auto", "postman", "openapi", "insomnia", "bruno", "internal", "curl", "http"];
+const registerImportTools = (server, ctx) => {
+    server.registerTool("import_content", {
+        title: "Import a file's content",
+        description: "Import API definitions from file CONTENT you read: Postman collection, OpenAPI/Swagger (JSON or YAML), Insomnia, Bruno, a Callman export, a cURL script, or a .http/.rest file. The format is detected (`format: auto`). Document formats always create a new collection; cURL/.http create a new collection (`collectionName`) or add to an existing one (`targetCollection` + optional `folder`). Use dryRun: true to see what was detected before writing. For endpoints found in source code, read the routes yourself and call create_requests_bulk instead.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            content: zod_1.z.string().min(1).max(CONTENT_MAX).describe("The raw file content"),
+            fileName: zod_1.z.string().max(300).optional().describe("Original file name — helps detection (.bru, .http, .yaml …)"),
+            format: zod_1.z.enum(IMPORT_FORMATS).default("auto"),
+            collectionName: zod_1.z.string().max(truncate_js_1.LIMITS.NAME).optional().describe("Name for the new collection (documents: fallback when the file carries no name)"),
+            targetCollection: zod_1.z.string().max(200).optional().describe("cURL/.http only: add to this existing collection instead of creating one"),
+            folder: zod_1.z.string().max(300).optional().describe("cURL/.http + targetCollection: folder to put the requests in"),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, content, fileName, format, collectionName, targetCollection, folder, dryRun }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        const detection = (0, importDetect_js_1.detectImport)(fileName, content);
+        const resolvedFormat = format === "auto" ? detection.format : format;
+        if (resolvedFormat === "unknown" || resolvedFormat === "scenario" || resolvedFormat === "environment") {
+            throw new errors_js_1.ToolInputError("IMPORT_FORMAT_UNSUPPORTED", resolvedFormat === "scenario"
+                ? "This is a Callman scenario export — use import_scenario."
+                : resolvedFormat === "environment"
+                    ? "This is an environment export — create it with create_environment / set_environment_variables."
+                    : "Could not detect the format. Pass `format` explicitly (postman, openapi, insomnia, bruno, internal, curl, http).", { detected: detection });
+        }
+        if (resolvedFormat === "curl" || resolvedFormat === "http") {
+            const name = fileName ?? (resolvedFormat === "curl" ? "requests.sh" : "requests.http");
+            let payload;
+            try {
+                payload = resolvedFormat === "curl" ? (0, callman_core_1.parseCurlFile)(name, content) : (0, callman_core_1.parseHttpFile)(name, content);
+            }
+            catch (error) {
+                throw new errors_js_1.ToolInputError("IMPORT_PARSE_FAILED", error instanceof Error ? error.message : String(error));
+            }
+            if (collectionName)
+                payload = { ...payload, collectionName: collectionName.trim() };
+            const sample = payload.requests.slice(0, 5).map((request) => `${request.method} ${request.name}`);
+            if (targetCollection) {
+                const resolved = await (0, lookups_js_1.resolveCollection)(ctx, ws.id, targetCollection);
+                const targetFolder = await (0, lookups_js_1.resolveFolder)(ctx, ws.id, resolved.item.id, folder);
+                if (dryRun) {
+                    return (0, shared_js_1.ok)({ dryRun: true, detected: detection, format: resolvedFormat, mode: "existing-collection", collection: { id: resolved.item.id, name: resolved.item.name }, requestCount: payload.requests.length, sample });
+                }
+                const created = [];
+                const failed = [];
+                for (const request of payload.requests) {
+                    try {
+                        const row = await ctx.api.createRequest(ws.id, { ...request, collectionId: resolved.item.id, folderId: targetFolder?.item.id ?? null });
+                        created.push({ id: row.id, name: row.name, method: row.method });
+                    }
+                    catch (error) {
+                        failed.push({ name: request.name, error: error instanceof errors_js_1.CallmanApiError ? `${error.code}: ${error.message}` : String(error) });
+                    }
+                }
+                ctx.invalidate(`tree:${ws.id}:${resolved.item.id}`);
+                ctx.invalidate(`collections:${ws.id}`);
+                return (0, shared_js_1.ok)({ format: resolvedFormat, collection: { id: resolved.item.id, name: resolved.item.name }, created: created.length, failed, requests: created, resolved: [(0, resolve_js_1.resolvedSummary)(targetCollection, resolved)] });
+            }
+            const existing = (await (0, lookups_js_1.loadCollections)(ctx, ws.id)).find((entry) => (0, lookups_js_1.sameName)(entry.name, payload.collectionName));
+            if (existing) {
+                throw new errors_js_1.ToolInputError("COLLECTION_NAME_EXISTS", `A collection named "${existing.name}" already exists. Pass collectionName for a new name, or targetCollection: "${existing.id}" to add to it.`, {
+                    existing: { id: existing.id, name: existing.name },
+                });
+            }
+            if (dryRun) {
+                return (0, shared_js_1.ok)({ dryRun: true, detected: detection, format: resolvedFormat, mode: "new-collection", collectionName: payload.collectionName, requestCount: payload.requests.length, sample });
+            }
+            const result = await ctx.api.importJson(ws.id, { format: "requests", payload });
+            ctx.invalidate(`collections:${ws.id}`);
+            return (0, shared_js_1.ok)({ format: resolvedFormat, collection: { id: result.collection.id, name: result.collection.name }, created: result.importedCounts });
+        }
+        if (!importDetect_js_1.SERVER_DOCUMENT_FORMATS.has(resolvedFormat)) {
+            throw new errors_js_1.ToolInputError("IMPORT_FORMAT_UNSUPPORTED", `Format "${resolvedFormat}" is not importable here.`);
+        }
+        const payload = (0, importDetect_js_1.documentPayload)(resolvedFormat, content);
+        if (dryRun) {
+            return (0, shared_js_1.ok)({ dryRun: true, detected: detection, format: resolvedFormat, mode: "new-collection", note: "The server parses this document; request counts are known after the import." });
+        }
+        const result = await ctx.api.importJson(ws.id, { format: resolvedFormat, payload, ...(collectionName ? { fallbackCollectionName: collectionName.trim() } : {}) });
+        ctx.invalidate(`collections:${ws.id}`);
+        return (0, shared_js_1.ok)({ format: resolvedFormat, collection: { id: result.collection.id, name: result.collection.name }, created: result.importedCounts });
+    }));
+    server.registerTool("import_scenario", {
+        title: "Import a scenario export",
+        description: "Import a Callman scenario export (a `callman.scenario` envelope — the JSON of a .callman.scenario file, as text or object). Connections referenced by the export that have no counterpart here are skipped (the nodes import without a connection; the result lists warnings).",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            envelope: zod_1.z.union([zod_1.z.string().max(CONTENT_MAX), zod_1.z.record(zod_1.z.unknown())]).describe("The export envelope (JSON text or object)"),
+            name: zod_1.z.string().max(200).optional().describe("Override the imported scenario's name"),
+            folder: zod_1.z.string().max(200).optional().describe("Scenario folder id or name"),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, envelope, name, folder, dryRun }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        let parsed = envelope;
+        if (typeof envelope === "string") {
+            try {
+                parsed = JSON.parse(envelope);
+            }
+            catch {
+                throw new errors_js_1.ToolInputError("IMPORT_INVALID_JSON", "The envelope is not valid JSON.");
+            }
+        }
+        const record = parsed;
+        if (record?.kind !== "callman.scenario") {
+            throw new errors_js_1.ToolInputError("IMPORT_NOT_SCENARIO", "This is not a Callman scenario export (expected kind: \"callman.scenario\").");
+        }
+        const targetFolder = folder ? await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws.id, folder) : null;
+        const connections = record.connections ?? [];
+        const connectionMap = Object.fromEntries(connections.filter((connection) => connection.refId).map((connection) => [connection.refId, { action: "skip" }]));
+        if (dryRun) {
+            return (0, shared_js_1.ok)({
+                dryRun: true,
+                scenario: { name: name ?? record.scenario?.name ?? null, nodeCount: Array.isArray(record.scenario?.nodes) ? record.scenario?.nodes.length : null },
+                connectionsSkipped: connections.map((connection) => `${connection.name ?? connection.refId} (${connection.type ?? "?"})`),
+                folder: targetFolder ? { id: targetFolder.item.id, name: targetFolder.item.name } : null,
+            });
+        }
+        const result = await ctx.api.importScenario(ws.id, { envelope: parsed, ...(name ? { name } : {}), folderId: targetFolder?.item.id ?? null, connectionMap });
+        ctx.invalidate("scenarios:");
+        const scenario = result.scenario;
+        return (0, shared_js_1.ok)({
+            scenario: { id: scenario.id, name: scenario.name, nodeCount: scenario.nodes?.length ?? null, reviewStatus: scenario.reviewStatus ?? null },
+            warnings: result.warnings ?? [],
+            ...(connections.length > 0 ? { note: "Connections from the export were skipped — attach the right workspace connections to the DB/Kafka/Redis nodes in the desktop app." } : {}),
+            ...(targetFolder ? { resolved: [(0, resolve_js_1.resolvedSummary)(folder, targetFolder)] } : {}),
+        });
+    }));
+};
+exports.registerImportTools = registerImportTools;
+// Re-exported for the run/collection tools' folder resolution symmetry.
+exports.requestRef = shared_js_1.refArg;

package/dist-cjs/tools/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAllTools = exports.toolAvailability = exports.TOOL_CATALOG = void 0;
+const collections_js_1 = require("./collections.js");
+const diagrams_js_1 = require("./diagrams.js");
+const environments_js_1 = require("./environments.js");
+const import_js_1 = require("./import.js");
+const meta_js_1 = require("./meta.js");
+const requests_js_1 = require("./requests.js");
+const run_js_1 = require("./run.js");
+const scenarios_js_1 = require("./scenarios.js");
+const workspaces_js_1 = require("./workspaces.js");
+var catalog_js_1 = require("./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; } });
+// Registration order = the order clients list tools in. Run tools are only
+// registered when local execution is allowed (a backend-hosted server passes
+// allowLocalRun: false and they disappear from tools/list).
+const registerAllTools = (server, ctx) => {
+    (0, meta_js_1.registerMetaTools)(server, ctx);
+    (0, workspaces_js_1.registerWorkspaceTools)(server, ctx);
+    (0, collections_js_1.registerCollectionTools)(server, ctx);
+    (0, requests_js_1.registerRequestTools)(server, ctx);
+    (0, import_js_1.registerImportTools)(server, ctx);
+    (0, environments_js_1.registerEnvironmentTools)(server, ctx);
+    (0, scenarios_js_1.registerScenarioTools)(server, ctx);
+    (0, diagrams_js_1.registerDiagramTools)(server, ctx);
+    if (ctx.config.allowLocalRun)
+        (0, run_js_1.registerRunTools)(server, ctx);
+};
+exports.registerAllTools = registerAllTools;

package/dist-cjs/tools/lookups.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sameName = exports.resolveDiagram = exports.loadDiagrams = exports.resolveScenarioFolder = exports.resolveScenario = exports.loadScenarioCatalog = exports.resolveEnvironment = exports.loadEnvironments = exports.resolveRequest = exports.searchRequests = exports.requestIdsInFolder = exports.resolveFolder = exports.loadTree = exports.resolveCollection = exports.loadCollections = void 0;
+const resolve_js_1 = require("../domain/resolve.js");
+const ids_js_1 = require("../lib/ids.js");
+const truncate_js_1 = require("../lib/truncate.js");
+// Cached lookups + reference resolution shared by the tool modules. Reads go
+// through the context cache (15 s TTL); every write tool invalidates the
+// prefixes it touches so the next read is fresh.
+const loadCollections = (ctx, ws) => ctx.cache.getOrSet(`collections:${ws}`, () => ctx.api.listAllCollections(ws));
+exports.loadCollections = loadCollections;
+const resolveCollection = async (ctx, ws, ref) => {
+    const collections = await (0, exports.loadCollections)(ctx, ws);
+    if ((0, ids_js_1.isObjectId)(ref) && !collections.some((collection) => collection.id === ref)) {
+        // Not in the cached list (just created?) — let the server decide.
+        try {
+            const fresh = await ctx.api.getCollection(ws, ref);
+            return { item: fresh, matched: "id" };
+        }
+        catch {
+            // fall through to the resolver's error with candidates
+        }
+    }
+    return (0, resolve_js_1.resolveRef)("collection", ref, collections, {
+        describe: (collection) => ({ requestCount: collection.requestCount ?? null }),
+    });
+};
+exports.resolveCollection = resolveCollection;
+const loadTree = (ctx, ws, collectionId) => ctx.cache.getOrSet(`tree:${ws}:${collectionId}`, async () => {
+    const [folderTree, requests] = await Promise.all([ctx.api.folderTree(ws, collectionId), ctx.api.requestTree(ws, collectionId)]);
+    return { folders: (0, resolve_js_1.flattenFolderTree)(folderTree.tree ?? []), requests };
+});
+exports.loadTree = loadTree;
+const resolveFolder = async (ctx, ws, collectionId, ref) => {
+    if (!ref || !ref.trim())
+        return null;
+    const tree = await (0, exports.loadTree)(ctx, ws, collectionId);
+    return (0, resolve_js_1.resolveFolderRef)(ref, tree.folders);
+};
+exports.resolveFolder = resolveFolder;
+// Request ids inside a folder, subfolders included.
+const requestIdsInFolder = (tree, folderId) => {
+    const childrenOf = new Map();
+    for (const folder of tree.folders) {
+        const list = childrenOf.get(folder.parentId) ?? [];
+        list.push(folder.id);
+        childrenOf.set(folder.parentId, list);
+    }
+    const folderIds = new Set([folderId]);
+    const queue = [folderId];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const child of childrenOf.get(current) ?? []) {
+            if (!folderIds.has(child)) {
+                folderIds.add(child);
+                queue.push(child);
+            }
+        }
+    }
+    return tree.requests.filter((request) => request.folderId && folderIds.has(request.folderId)).map((request) => request.id);
+};
+exports.requestIdsInFolder = requestIdsInFolder;
+// Search requests across the workspace (or one collection): every query token
+// must appear in "name method url" (case-insensitive) — the desktop
+// assistant's rule.
+const searchRequests = async (ctx, ws, query, collectionId, limit = truncate_js_1.LIMITS.SEARCH_RESULTS) => {
+    const tokens = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const collections = await (0, exports.loadCollections)(ctx, ws);
+    const targets = collectionId ? collections.filter((collection) => collection.id === collectionId) : collections;
+    const matches = [];
+    for (const collection of targets) {
+        if (matches.length >= limit)
+            break;
+        const tree = await (0, exports.loadTree)(ctx, ws, collection.id);
+        for (const request of tree.requests) {
+            if (matches.length >= limit)
+                break;
+            const haystack = `${request.name} ${request.method} ${request.url}`.toLowerCase();
+            if (tokens.every((token) => haystack.includes(token)))
+                matches.push({ ...request, collectionName: collection.name });
+        }
+    }
+    return matches;
+};
+exports.searchRequests = searchRequests;
+// A request reference: an id (fetched directly) or a name — unique across the
+// given collection, or across the workspace when no collection is given.
+const resolveRequest = async (ctx, ws, ref, collectionRef) => {
+    if ((0, ids_js_1.isObjectId)(ref)) {
+        return { request: await ctx.api.getRequest(ws, ref) };
+    }
+    const collectionId = collectionRef ? (await (0, exports.resolveCollection)(ctx, ws, collectionRef)).item.id : null;
+    const collections = await (0, exports.loadCollections)(ctx, ws);
+    const targets = collectionId ? collections.filter((collection) => collection.id === collectionId) : collections;
+    const candidates = [];
+    for (const collection of targets) {
+        const tree = await (0, exports.loadTree)(ctx, ws, collection.id);
+        for (const request of tree.requests)
+            candidates.push({ ...request, collectionName: collection.name });
+    }
+    const resolved = (0, resolve_js_1.resolveRef)("request", ref, candidates, {
+        describe: (request) => ({ method: request.method, url: request.url, collection: request.collectionName }),
+        aliases: (request) => [`${request.method} ${request.url}`, request.url],
+    });
+    return { request: await ctx.api.getRequest(ws, resolved.item.id), annotation: resolved.annotation };
+};
+exports.resolveRequest = resolveRequest;
+const loadEnvironments = (ctx, ws) => ctx.cache.getOrSet(`environments:${ws}`, async () => (await ctx.api.listEnvironments(ws)).items);
+exports.loadEnvironments = loadEnvironments;
+const resolveEnvironment = async (ctx, ws, ref) => (0, resolve_js_1.resolveRef)("environment", ref, await (0, exports.loadEnvironments)(ctx, ws), {
+    describe: (environment) => ({ variables: environment.variables.length }),
+});
+exports.resolveEnvironment = resolveEnvironment;
+const loadScenarioCatalog = (ctx, ws) => ctx.cache.getOrSet(`scenarios:${ws ?? "-"}`, async () => {
+    const [scenarios, foldersRaw] = await Promise.all([
+        ctx.api.listScenarios(ws),
+        ctx.api.listScenarioFolders(ws).catch(() => []),
+    ]);
+    const folders = Array.isArray(foldersRaw) ? foldersRaw : (foldersRaw.items ?? []);
+    return { scenarios, folders };
+});
+exports.loadScenarioCatalog = loadScenarioCatalog;
+const resolveScenario = async (ctx, ws, ref) => {
+    if ((0, ids_js_1.isObjectId)(ref)) {
+        return { item: await ctx.api.getScenario(ws, ref), matched: "id" };
+    }
+    const { scenarios, folders } = await (0, exports.loadScenarioCatalog)(ctx, ws);
+    const folderName = new Map(folders.map((folder) => [folder.id, folder.name]));
+    return (0, resolve_js_1.resolveRef)("scenario", ref, scenarios, {
+        describe: (scenario) => ({ folder: scenario.folderId ? (folderName.get(scenario.folderId) ?? null) : null, reviewStatus: scenario.reviewStatus }),
+    });
+};
+exports.resolveScenario = resolveScenario;
+const resolveScenarioFolder = async (ctx, ws, ref) => (0, resolve_js_1.resolveRef)("scenario folder", ref, (await (0, exports.loadScenarioCatalog)(ctx, ws)).folders);
+exports.resolveScenarioFolder = resolveScenarioFolder;
+const loadDiagrams = (ctx) => ctx.cache.getOrSet("diagrams", () => ctx.api.listDiagrams());
+exports.loadDiagrams = loadDiagrams;
+const resolveDiagram = async (ctx, ref) => {
+    if ((0, ids_js_1.isObjectId)(ref))
+        return { item: await ctx.api.getDiagram(ref), matched: "id" };
+    const resolved = (0, resolve_js_1.resolveRef)("diagram", ref, await (0, exports.loadDiagrams)(ctx), {
+        describe: (diagram) => ({ canEdit: diagram.canEdit }),
+    });
+    // The list carries the document too, but fetch by id for the freshest copy.
+    return { ...resolved, item: await ctx.api.getDiagram(resolved.item.id) };
+};
+exports.resolveDiagram = resolveDiagram;
+const sameName = (a, b) => (0, ids_js_1.normalizeName)(a) === (0, ids_js_1.normalizeName)(b);
+exports.sameName = sameName;

package/dist-cjs/tools/meta.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMetaTools = void 0;
+const errors_js_1 = require("../client/errors.js");
+const catalog_js_1 = require("./catalog.js");
+const shared_js_1 = require("./shared.js");
+// whoami — the first call a model should make: proves the connection, tells
+// it who it acts as, which workspaces exist, which features are on and which
+// tools the token can actually use. Never throws for a missing/invalid token:
+// the answer explains how to fix the setup.
+const registerMetaTools = (server, ctx) => {
+    server.registerTool("whoami", {
+        title: "Who am I (connection check)",
+        description: "Check the Callman connection: server URL, the user the token acts as, token permissions (scopes), the workspaces you can use (and which one is the default), enabled features and which tools are available with this token. Call this first in a session, or when a tool reports a permission problem.",
+        inputSchema: {},
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async () => {
+        if (!ctx.config.token) {
+            return (0, shared_js_1.ok)({
+                apiUrl: ctx.config.apiUrl,
+                connected: false,
+                error: {
+                    code: "TOKEN_MISSING",
+                    message: "No token is configured.",
+                    hint: "Create a personal token in the Callman desktop app (Settings → AI tools → New token) and set CALLMAN_TOKEN (or CALLMAN_TOKEN_FILE) in this MCP server's config, then restart the AI tool.",
+                },
+                tools: (0, catalog_js_1.toolAvailability)([], ctx.config.allowLocalRun),
+            });
+        }
+        const [meResult, workspacesResult, featuresResult] = await Promise.allSettled([
+            ctx.api.me(),
+            ctx.listWorkspaces(),
+            ctx.api.features(),
+        ]);
+        if (meResult.status === "rejected") {
+            const error = meResult.reason;
+            return (0, shared_js_1.ok)({
+                apiUrl: ctx.config.apiUrl,
+                connected: false,
+                error: error instanceof errors_js_1.CallmanApiError
+                    ? { code: error.code, status: error.status, message: error.message, hint: (0, errors_js_1.hintFor)(error) }
+                    : { code: "NETWORK_UNREACHABLE", message: error instanceof Error ? error.message : String(error) },
+                tools: (0, catalog_js_1.toolAvailability)([], ctx.config.allowLocalRun),
+            });
+        }
+        const me = meResult.value;
+        const workspaces = workspacesResult.status === "fulfilled" ? workspacesResult.value : [];
+        const features = featuresResult.status === "fulfilled" ? featuresResult.value.features : {};
+        const defaultWorkspace = ctx.config.defaultWorkspaceId
+            ? (workspaces.find((workspace) => workspace.id === ctx.config.defaultWorkspaceId) ?? null)
+            : workspaces.length === 1
+                ? workspaces[0]
+                : null;
+        return (0, shared_js_1.ok)({
+            apiUrl: ctx.config.apiUrl,
+            connected: true,
+            serverVersion: ctx.version,
+            user: me.user,
+            token: {
+                name: me.token.name,
+                scopes: me.token.scopes,
+                expiresAt: me.token.expiresAt,
+                lastUsedAt: me.token.lastUsedAt,
+            },
+            workspaces: workspaces.map((workspace) => ({
+                id: workspace.id,
+                name: workspace.name,
+                role: workspace.role,
+                isDefault: workspace.id === defaultWorkspace?.id,
+            })),
+            defaultWorkspaceId: defaultWorkspace?.id ?? null,
+            ...(workspaces.length > 1 && !defaultWorkspace
+                ? { note: "Several workspaces and no default: pass `workspace` to tools or set CALLMAN_WORKSPACE_ID." }
+                : {}),
+            features,
+            localRun: ctx.config.allowLocalRun,
+            tools: (0, catalog_js_1.toolAvailability)(me.token.scopes, ctx.config.allowLocalRun),
+        });
+    }));
+};
+exports.registerMetaTools = registerMetaTools;