callman-mcp 0.7.1 → 0.8.0

package/dist-cjs/client/api.js

@@ -347,6 +347,73 @@ class CallmanApi {
     importUiTests(ws, body) {
         return this.http.request("POST", "/import/ui-tests", { workspaceId: ws, body, timeoutMs: 120_000 });
     }
+    // ── mock APIs (server) ──────────────────────────────────────────────
+    // Mocks are addressed by their slug (`mockId`), not the database id.
+    listMocks(ws, page = 1, search) {
+        return this.http.request("GET", "/mocks", { workspaceId: ws, query: { page, limit: 100, search } });
+    }
+    async listAllMocks(ws) {
+        const out = [];
+        for (let page = 1; page <= 20; page += 1) {
+            const result = await this.listMocks(ws, page);
+            out.push(...result.items);
+            if (page >= result.pagination.totalPages || result.items.length === 0)
+                break;
+        }
+        return out;
+    }
+    getMock(ws, mockId, includeSecrets = false) {
+        return this.http.request("GET", `/mocks/${encodeURIComponent(mockId)}`, { workspaceId: ws, query: includeSecrets ? { includeSecrets: "true" } : {} });
+    }
+    createMock(ws, body) {
+        return this.http.request("POST", "/mocks", { workspaceId: ws, body });
+    }
+    updateMock(ws, mockId, body) {
+        return this.http.request("PATCH", `/mocks/${encodeURIComponent(mockId)}`, { workspaceId: ws, body });
+    }
+    deleteMock(ws, mockId) {
+        return this.http.request("DELETE", `/mocks/${encodeURIComponent(mockId)}`, { workspaceId: ws });
+    }
+    addMockRoute(ws, mockId, body) {
+        return this.http.request("POST", `/mocks/${encodeURIComponent(mockId)}/routes`, { workspaceId: ws, body });
+    }
+    updateMockRoute(ws, mockId, routeId, body) {
+        return this.http.request("PATCH", `/mocks/${encodeURIComponent(mockId)}/routes/${encodeURIComponent(routeId)}`, { workspaceId: ws, body });
+    }
+    deleteMockRoute(ws, mockId, routeId) {
+        return this.http.request("DELETE", `/mocks/${encodeURIComponent(mockId)}/routes/${encodeURIComponent(routeId)}`, { workspaceId: ws });
+    }
+    reorderMockRoutes(ws, mockId, routeIds) {
+        return this.http.request("POST", `/mocks/${encodeURIComponent(mockId)}/routes/reorder`, { workspaceId: ws, body: { routeIds } });
+    }
+    getMockState(ws, mockId) {
+        return this.http.request("GET", `/mocks/${encodeURIComponent(mockId)}/state`, { workspaceId: ws });
+    }
+    replaceMockState(ws, mockId, state) {
+        return this.http.request("PUT", `/mocks/${encodeURIComponent(mockId)}/state`, { workspaceId: ws, body: state });
+    }
+    replaceMockInitialState(ws, mockId, initialState) {
+        return this.http.request("PUT", `/mocks/${encodeURIComponent(mockId)}/initial-state`, { workspaceId: ws, body: initialState });
+    }
+    resetMockState(ws, mockId) {
+        return this.http.request("POST", `/mocks/${encodeURIComponent(mockId)}/state/reset`, { workspaceId: ws, body: {} });
+    }
+    getMockStats(ws, mockId) {
+        return this.http.request("GET", `/mocks/${encodeURIComponent(mockId)}/stats`, { workspaceId: ws });
+    }
+    listMockLogs(ws, mockId, query) {
+        return this.http.request("GET", `/mocks/${encodeURIComponent(mockId)}/logs`, { workspaceId: ws, query });
+    }
+    // ── local mocks (the desktop app's own mock servers, via the relay) ─────
+    listLocalMockAgents(ws) {
+        return this.http.request("GET", "/local-mock-agents", { workspaceId: ws });
+    }
+    queueLocalMockCommand(ws, body) {
+        return this.http.request("POST", "/local-mock-commands", { workspaceId: ws, body });
+    }
+    getLocalMockCommand(ws, id) {
+        return this.http.request("GET", `/local-mock-commands/${encodeURIComponent(id)}`, { workspaceId: ws, retries: 0 });
+    }
     // ── local run bundle ────────────────────────────────────────────────
     pipelineBundle(ws, collectionId, environmentId) {
         return this.http.request("GET", "/pipeline/bundle", {

package/dist-cjs/client/errors.js

@@ -50,15 +50,17 @@ const SCOPE_HINT = "Create a token with that permission in the Callman desktop a
 const validationHint = (path) => {
     const doc = /\/(ui-test|import\/ui-tests|export\/ui-tests)/.test(path)
         ? "callman://docs/ui-tests (steps: callman://docs/ui-test-steps)"
-        : /\/(scenarios|scenario-folders)/.test(path)
-            ? "callman://docs/scenario-nodes"
-            : /\/diagrams/.test(path)
-                ? "callman://docs/diagram-schema"
-                : /\/(contract-rules|data-contracts)/.test(path)
-                    ? "callman://docs/contracts"
-                    : /\/(environments|variables)/.test(path)
-                        ? null
-                        : "callman://docs/request-schema";
+        : /\/(mocks|local-mock-)/.test(path)
+            ? "callman://docs/mocks"
+            : /\/(scenarios|scenario-folders)/.test(path)
+                ? "callman://docs/scenario-nodes"
+                : /\/diagrams/.test(path)
+                    ? "callman://docs/diagram-schema"
+                    : /\/(contract-rules|data-contracts)/.test(path)
+                        ? "callman://docs/contracts"
+                        : /\/(environments|variables)/.test(path)
+                            ? null
+                            : "callman://docs/request-schema";
     return `The server rejected the input — check the fields listed in details${doc ? ` against ${doc}` : " (keys 1–100 chars, values ≤ 5000)"}.`;
 };
 const hintFor = (error) => {
@@ -68,12 +70,17 @@ const hintFor = (error) => {
                 ? (error.details.required ?? []).join(" or ")
                 : "an additional scope";
             const uiTests = /ui_tests:/.test(required) ? " UI tests have their own permissions: ui_tests:read (list, read, reports), ui_tests:write (create, edit, folders, schedules, review), ui_tests:run (run, cancel), ui_tests:delete." : "";
-            return `The token lacks the permission ${required}.${uiTests} ${SCOPE_HINT}`;
+            const mocks = /mocks:/.test(required) ? " Mock APIs have their own permissions: mocks:read (list, read, logs, state), mocks:write (create, edit, routes, state, start/stop local mocks), mocks:delete." : "";
+            return `The token lacks the permission ${required}.${uiTests}${mocks} ${SCOPE_HINT}`;
         }
         case "PAT_ROUTE_FORBIDDEN":
             return /\/(ui-test|import\/ui-tests|export\/ui-tests)/.test(error.path)
                 ? "This server does not open UI tests to AI tools yet — update callman-backend to a version with the ui_tests:* token permissions."
-                : "This area of Callman is not available to AI tools (mocks, request history, API-scenario schedules, connection editing, admin). Use the desktop app for it.";
+                : /\/(mocks|local-mock-)/.test(error.path)
+                    ? "This server does not open mock APIs to AI tools yet — update callman-backend to a version with the mocks:* token permissions."
+                    : "This area of Callman is not available to AI tools (request history, API-scenario schedules, connection editing, admin). Use the desktop app for it.";
+        case "LOCAL_MOCK_DESKTOP_OFFLINE":
+            return "No Callman desktop app of yours is online to manage local mocks. Open the Callman desktop app, sign in, and turn on Settings → AI tools → \"Let AI tools manage local mock APIs on this computer\". Then try again — or use target: \"server\" for a mock on the Callman server with a public URL.";
         case "UI_TEST_DESKTOP_OFFLINE":
             return "No Callman desktop app of yours is online to run this. Open the Callman desktop app, sign in, and turn on Settings → AI tools → \"Let AI tools run UI tests on this computer\"; for Android/iOS connect a device or start an emulator/simulator. Then run again (list_ui_test_devices shows what is connected). Web flows can also run on the server runner when the installation has one.";
         case "UI_TEST_DESKTOP_PLATFORM_UNAVAILABLE":

package/dist-cjs/context.js

@@ -93,6 +93,7 @@ const createToolContext = (options) => {
         },
         invalidate: (prefix) => (prefix ? cache.delete(prefix) : cache.clear()),
         pollDelaysMs: options.pollDelaysMs ?? { fast: 2000, slow: 5000 },
+        localMockPoll: options.localMockPoll ?? { intervalMs: 1000, timeoutMs: 25_000 },
     };
 };
 exports.createToolContext = createToolContext;

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

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOCKS_DOC = void 0;
+exports.MOCKS_DOC = `# Mock APIs through MCP
+
+A mock API is a fake HTTP API that answers with the responses you describe. Use it when a user says
+*"I need an API that returns …"* — to build a front end before the backend exists, to test a client
+against errors and slow answers, or to give a test a stable dependency. You create it with a few tool
+calls and hand the user a URL.
+
+## Two places a mock can live (\`target\`)
+
+| | \`target: "server"\` (default) | \`target: "desktop"\` |
+|---|---|---|
+| Where | On the Callman server | Inside the user's Callman desktop app |
+| URL | \`<server>/mock/<slug>/…\` — public, reachable by anyone with the URL (or the token) | \`http://127.0.0.1:<port>/…\` — this computer only |
+| Responses | static, **template** ({{…}}), **builder** presets, **variants**, request validation, delay | **static only** + delay |
+| State | yes (builder routes read and write it) | no |
+| Lifetime | expires after 1 / 6 / 24 / 48 h (default 48) | until deleted; lives while the app is open |
+| Needs | token with \`mocks:*\` | token with \`mocks:*\` **and** the desktop app open, signed in, with Settings → AI tools → "Let AI tools manage local mock APIs on this computer" on |
+| Routes are edited with | add_mock_route / update_mock_route / delete_mock_route | \`update_mock { routes }\` — REPLACES all routes |
+| Always on? | yes (no start/stop) | start_mock / stop_mock |
+
+If the server's \`publicUrl\` does not answer from your machine (an installation that never set its public address announces a host nobody can reach), use \`alternativeUrl\` from the same result — it is the API address plus \`/mock/<slug>\`.
+
+Pick **server** unless the user wants it on their own machine, needs no network exposure, or a tool on
+their computer must call it at localhost. Desktop calls go through a relay: the app picks the request up
+within a few seconds. If it answers \`LOCAL_MOCK_DESKTOP_OFFLINE\`, tell the user to open the app and
+switch the setting on (or fall back to a server mock).
+
+## From a user's request to routes
+
+1. List first (\`list_mocks\`) — reuse or extend a mock that already fits instead of creating a duplicate.
+2. For each endpoint the user needs, decide: **method + path**, the **status code** and the **body**.
+   Use real-looking data; ask only when the contract is truly unknown.
+3. A fixed answer → a static response. Values taken from the request (the id in the path, a field of the
+   body) or random data → a template. A small CRUD API that remembers what was created → builder
+   routes over state. Different answers for different inputs (a 401 for a bad header, a 404 for one id)
+   → variants.
+4. Call \`create_mock\` with all routes at once. The result has the URL and a \`curl\` line per route —
+   give them to the user, and try one if you can.
+5. Iterate with \`update_mock_route\` / \`add_mock_route\`; read what real clients sent with \`get_mock_logs\`.
+
+\`\`\`json
+create_mock {
+  "name": "Orders API", "slug": "orders-api", "ttlHours": 24,
+  "routes": [
+    { "method": "GET", "path": "/orders", "statusCode": 200, "body": [{ "id": 1, "status": "NEW" }, { "id": 2, "status": "PAID" }] },
+    { "method": "GET", "path": "/orders/:id", "response": { "type": "template", "statusCode": 200, "body": { "id": "{{request.params.id}}", "status": "NEW", "createdAt": "{{now}}" } } },
+    { "method": "POST", "path": "/orders", "statusCode": 201, "body": { "id": "{{faker.uuid}}" }, "delay": { "mode": "fixed", "ms": 300 } }
+  ]
+}
+\`\`\`
+
+## A route
+
+\`\`\`
+{ method, path, name?, response | (statusCode?, headers?, body?), variants?, delay?, requestValidation? }
+\`\`\`
+
+- **method**: GET POST PUT DELETE PATCH or ANY (any method that no specific route takes).
+- **path**: starts with \`/\`; letters, digits and \`/ _ - : * .\`; no \`..\`; at most 256 characters.
+  \`:name\` is a path parameter (letters, digits, underscore: \`:userId\`, not \`:user-id\`). A trailing
+  \`/*\` (or a \`*\` segment) matches everything below. The most specific route wins (literal segment >
+  parameter > wildcard); a trailing slash is ignored. One route per method + path.
+- **response**: the full shape below. **Shorthand** for the common case: \`statusCode\` (default 200),
+  \`headers\`, \`body\` directly on the route = a static response. Don't mix the two.
+- **name**: a label (shown in lists; usable as a reference).
+- **delay**: \`{ mode: "none" }\`, \`{ mode: "fixed", ms }\` or \`{ mode: "random", minMs, maxMs }\` — the
+  answer is held back that long (server ≤ 60 000 ms, desktop ≤ 30 000 ms). Use it to test timeouts and spinners.
+
+### Responses (server)
+
+\`\`\`
+{ "type": "static",   "statusCode": 200, "headers": { "X-Foo": "1" }, "body": <any JSON> }
+{ "type": "template", "statusCode": 200, "headers": {}, "body": <JSON with {{expressions}}> }
+{ "type": "builder",  "preset": "list|detail|create|update|delete|echo|custom", "config": { "preset": <same>, … } }
+\`\`\`
+
+- **body**: any JSON value. An object/array is sent as JSON (\`content-type: application/json\` unless you
+  set one); a *string* is sent as is (\`text/plain\` unless you set a content type — for XML/HTML put
+  the text in \`body\` and set \`headers\`). No body = empty response (use for 204).
+- **template** — every string in the body may contain \`{{expression}}\`. A string that is *only* one
+  expression keeps its type (number, boolean, object); inside longer text the value becomes text.
+  Unknown expressions become \`null\` (whole) or empty (inline).
+  - \`request.params.<name>\`, \`request.query.<name>\`, \`request.headers.<name>\` (case-insensitive),
+    \`request.body.<dotted.path>\`, \`request.method\`
+  - \`state.<key>\` — the mock's state (see below)
+  - \`faker.email|uuid|fullName|firstName|lastName|phone|address|company|lorem|boolean|int\`
+  - \`random.int(min,max)\`, \`random.float(min,max)\`, \`random.boolean\`
+  - \`now\`, \`now+5m\`, \`now-2d\` (units s m h d) → ISO timestamps
+  - Example: \`{ "id": "{{request.params.id}}", "email": "{{faker.email}}", "age": "{{random.int(18,65)}}" }\`
+    (\`age\` becomes a number).
+
+### Builder presets (server)
+
+A builder route does the work of a REST endpoint over **state** (arrays of objects, stored per mock).
+\`config.preset\` must equal \`preset\`. Required keys are marked; the rest have defaults.
+
+| preset | config | what it does |
+|---|---|---|
+| \`list\` | **source**: \`{kind:"static",data:[…]}\` or \`{kind:"state",stateKey}\`; \`filtering:{enabled,rules:[{queryParam,field,operator:equals\\|contains\\|startsWith\\|in}]}\`; \`sorting:{enabled,sortByParam:"sortBy",orderParam:"order",allowedFields:[…]}\`; \`pagination:{enabled,strategy:page\\|offset\\|cursor,defaultPageSize:20,maxPageSize:100,envelope:standard\\|data-meta\\|raw}\`; \`statusCode\`, \`headers\` | filter by query params, sort, paginate (\`?page=&limit=\`, \`?offset=&limit=\`, \`?cursor=<last id>&limit=\`). Envelopes: standard \`{items,total,page,totalPages}\`, data-meta \`{data,meta:{total,page,limit}}\`, raw array |
+| \`detail\` | **source**, **notFoundBehavior**:\`{statusCode:404,body?}\`, \`paramName:"id"\`, \`lookupField:"id"\` | the item whose \`lookupField\` equals the path parameter; otherwise the not-found answer |
+| \`create\` | **stateKey**, \`autoGenerate:{id:"uuid"\\|"incremental",createdAt,updatedAt}\`, \`requiredFields:[…]\` (missing → 400), \`responseBehavior:return-created\\|return-id\\|status-only\`, \`statusCode:201\` | appends the request body (plus generated fields) to \`state[stateKey]\` |
+| \`update\` | **stateKey**, **notFoundBehavior**, \`paramName\`, \`lookupField\`, \`mergeStrategy:partial\\|full\`, \`autoUpdateUpdatedAt:true\`, \`statusCode:200\` | replaces/merges the matching item with the request body |
+| \`delete\` | **stateKey**, **notFoundBehavior**, \`paramName\`, \`lookupField\`, \`responseBehavior:204\\|return-deleted\\|success-message\`, \`statusCode:204\` | removes the matching item |
+| \`echo\` | \`statusCode\`, \`headers\` | answers with the request: \`{method,params,query,headers,body}\` — handy to see what a client sends |
+| \`custom\` | \`statusCode\`, \`headers\`, \`body\` | a fixed answer through the builder |
+
+A full CRUD mock over one \`users\` collection (the path parameter name must match \`paramName\`):
+
+\`\`\`json
+create_mock { "name": "Users", "slug": "users-api", "routes": [
+  { "method": "GET",    "path": "/users",     "response": { "type": "builder", "preset": "list",   "config": { "preset": "list", "source": { "kind": "state", "stateKey": "users" }, "pagination": { "enabled": true } } } },
+  { "method": "GET",    "path": "/users/:id", "response": { "type": "builder", "preset": "detail", "config": { "preset": "detail", "source": { "kind": "state", "stateKey": "users" }, "notFoundBehavior": { "statusCode": 404 } } } },
+  { "method": "POST",   "path": "/users",     "response": { "type": "builder", "preset": "create", "config": { "preset": "create", "stateKey": "users", "autoGenerate": { "id": "incremental", "createdAt": true }, "requiredFields": ["name"] } } },
+  { "method": "PATCH",  "path": "/users/:id", "response": { "type": "builder", "preset": "update", "config": { "preset": "update", "stateKey": "users", "notFoundBehavior": { "statusCode": 404 } } } },
+  { "method": "DELETE", "path": "/users/:id", "response": { "type": "builder", "preset": "delete", "config": { "preset": "delete", "stateKey": "users", "notFoundBehavior": { "statusCode": 404 } } } }
+] }
+set_mock_state { "mock": "users-api", "initialState": { "users": [{ "id": 1, "name": "Ada" }] }, "state": { "users": [{ "id": 1, "name": "Ada" }] } }
+\`\`\`
+
+### State
+
+State is a JSON object per mock (limit 1 MB). Builder \`create\`/\`update\`/\`delete\` change it as requests
+arrive (a missing array is created by the first \`create\`); \`list\`/\`detail\` with \`source.kind: "state"\` and
+\`{{state.key}}\` templates read it. \`get_mock_state\` shows \`state\` (live) and \`initialState\`;
+\`set_mock_state\` replaces either wholesale; \`reset_mock_state\` copies \`initialState\` back into \`state\`
+(do that between test runs). Seed *both* when you want a reset to return to the seed data.
+
+### Variants — different answers for different requests (server)
+
+A route can carry up to 20 variants. Each has \`priority\` (lower is checked first), a \`condition\` and a
+\`response\` (same shapes as above). The first variant whose condition matches answers; otherwise the
+route's own \`response\` does.
+
+\`\`\`json
+{ "method": "GET", "path": "/profile",
+  "response": { "type": "static", "statusCode": 200, "body": { "name": "Ada" } },
+  "variants": [
+    { "priority": 1, "condition": { "type": "all", "rules": [{ "field": "headers.authorization", "operator": "not-exists" }] },
+      "response": { "type": "static", "statusCode": 401, "body": { "error": "unauthorized" } } },
+    { "priority": 2, "condition": { "type": "any", "rules": [{ "field": "query.fail", "operator": "equals", "value": "1" }] },
+      "response": { "type": "static", "statusCode": 500, "body": { "error": "boom" } } } ] }
+\`\`\`
+
+- \`condition.type\`: \`all\` (every rule) or \`any\` (at least one); 1–20 rules.
+- \`field\`: \`headers.<name>\`, \`params.<name>\`, \`query.<name>\`, \`body.<dotted.path>\`.
+- \`operator\`: exists, not-exists (null and empty count as missing), equals, not-equals, contains,
+  starts-with, matches (a regular expression in \`value\`; an invalid one never matches). Values are compared as text.
+
+### Request validation (server)
+
+\`requestValidation: { "mode": "schema", "schema": { …JSON Schema draft-07… } }\` makes the route reject a
+body that does not match with **400** and the list of invalid fields — to let a client team verify what
+they send. Checked on POST, PUT and PATCH requests. \`mode: "any"\` (default) accepts anything. An invalid
+schema is refused when you save the route. \`update_mock_route\` with \`requestValidation: null\` removes the gate.
+
+### Auth (server)
+
+\`auth: "public"\` (default) — anyone with the URL. \`auth: "token"\` — callers must send
+\`X-Mock-Token: <token>\` (else 401). The token is generated by the server and returned **once**, in the
+create_mock / update_mock result; \`get_mock\` keeps it masked unless the token holds \`environments:reveal\`
+and you pass \`reveal: true\`. Never put it into places the user did not ask for.
+
+## Limits (server defaults; an installation may change them)
+
+20 mocks per workspace · 50 routes per mock · response body ≤ 100 KB · request body ≤ 1 MB ·
+state ≤ 1 MB · 20 000 requests in total per mock, then 429 · 30 requests per second per mock, then 429 ·
+the 500 newest request logs are kept · slugs: 3–48 chars, lowercase letters/digits/single dashes, start
+with a letter, a few reserved words (api, mock, admin …) refused · lifetime 1/6/24/48 h, then **410 Gone**.
+Local (desktop): response body ≤ 256 KB, ports 1024–65535 (omit \`port\` and the app picks a free one),
+the mock listens on 127.0.0.1 only.
+
+## Desktop (local) mocks
+
+\`create_mock { target: "desktop", name, port?, autoStart?, routes? }\` creates a local mock in the user's
+app and starts it (\`start: false\` to skip). Routes are static: \`{ method, path, name?, statusCode, headers, body, delay }\`
+(or \`response: { type: "static", … }\` — the same route object you would give a server mock works as
+long as it is static; \`variants\`, \`requestValidation\`, template and builder responses are refused
+with LOCAL_MOCK_FEATURE_UNSUPPORTED). \`body\` is text: a string is sent verbatim, anything else is
+sent as formatted JSON. \`:param\` segments and a trailing \`/*\` work; every request is logged
+(\`get_mock_logs { target: "desktop" }\`, the latest requests only, kept until the app quits).
+To change routes: \`get_mock { target: "desktop" }\`, edit, \`update_mock { routes: [...all of them] }\`.
+\`start_mock\` / \`stop_mock\` / \`delete_mock\` act on one by name or id. Mocks the AI created carry an "AI"
+badge in the app. The mock is only reachable from the user's computer — don't hand out the URL to others.
+
+## Tools
+
+| Tool | Scope | |
+|---|---|---|
+| list_mocks, get_mock, get_mock_logs | mocks:read | \`target\` server/desktop |
+| get_mock_stats, get_mock_state | mocks:read | server |
+| create_mock, update_mock | mocks:write | \`target\` server/desktop |
+| add_mock_route, update_mock_route, reorder_mock_routes, set_mock_state, reset_mock_state | mocks:write | server |
+| start_mock, stop_mock | mocks:write | desktop |
+| delete_mock | mocks:delete (+ \`confirm: true\`) | \`target\` server/desktop |
+| delete_mock_route | mocks:delete (+ \`confirm: true\`) | server |
+
+\`mock\` is the name, the slug or the id. A route is referenced by routeId, \`"GET /users/:id"\`, its path
+(when unique) or its name. If \`create_mock\` fails on a route, the new mock is deleted again (needs
+mocks:delete; otherwise the result says it is kept) and the error names the failing route and why.
+
+## Errors you may meet
+
+\`PAT_SCOPE_MISSING\` (token lacks mocks:read/write/delete) · \`FEATURE_DISABLED\` (mocks switched off for the
+account) · \`MOCK_SLUG_TAKEN\` (pick another slug) · \`MOCK_LIMIT_REACHED\` (delete an old mock) ·
+\`ROUTE_PATH_CONFLICT\` (the method + path exists) · \`MOCK_ROUTE_LIMIT_REACHED\` · \`VALIDATION_ERROR\`
+(details name the field) · \`LOCAL_MOCK_DESKTOP_OFFLINE\` (open the desktop app and switch the setting on) ·
+\`LOCAL_MOCK_TIMEOUT\` (the app did not answer; check with list_mocks before repeating a create) ·
+\`LOCAL_MOCK_FEATURE_UNSUPPORTED\` (use a server mock).
+`;

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

@@ -4,7 +4,7 @@ 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 API test scenarios, UI tests for web / Android / iOS, system-design diagrams). This
+multi-step API test scenarios, UI tests for web / Android / iOS, system-design diagrams, mock APIs). 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.
 
@@ -74,6 +74,12 @@ web without a runner) run on the user's own Callman desktop app, which must be o
 "Let AI tools run UI tests on this computer" on — \`list_ui_test_devices\` shows what is
 available. Runs return per-step results; screenshots come back as images on request.
 
+## Mock APIs
+When a user needs an API that does not exist (yet), create a mock: \`create_mock\` with its routes gives a
+public URL (\`target: "server"\`, default) or a local one on the user's computer (\`target: "desktop"\`, needs
+the desktop app open with "Let AI tools manage local mock APIs on this computer" on). Responses can be
+static, templated or backed by state; read \`callman://docs/mocks\` first. Server mocks expire (1–48 h).
+
 ## Diagrams
 System-design diagrams use a fixed component catalog — \`callman://diagram/components\`.
 Build with \`create_diagram\` (auto layout), edit with \`patch_diagram\`, share with

package/dist-cjs/resources/index.js

@@ -11,6 +11,7 @@ const lookups_js_1 = require("../tools/lookups.js");
 const uiTestShared_js_1 = require("../tools/uiTestShared.js");
 const contracts_js_1 = require("./docs/contracts.js");
 const diagramSchema_js_1 = require("./docs/diagramSchema.js");
+const mocks_js_1 = require("./docs/mocks.js");
 const overview_js_1 = require("./docs/overview.js");
 const requestSchema_js_1 = require("./docs/requestSchema.js");
 const collectionScripts_js_1 = require("./docs/collectionScripts.js");
@@ -49,6 +50,7 @@ const registerResources = (server, ctx) => {
         { name: "docs-scripting-sandbox", uri: "callman://docs/scripting/sandbox", title: "Scripting: sandbox and feature policy", description: "Globals available in the script sandbox and the feature policy for DB/Kafka capabilities.", body: () => `${aiPacks_js_1.AI_PACKS["sandbox-globals"] ?? ""}\n\n${aiPacks_js_1.AI_PACKS["feature-policy"] ?? ""}` },
         { name: "docs-ui-tests", uri: "callman://docs/ui-tests", title: "UI tests", description: "UI-test concepts: platforms, header, preconditions and sub-flows, datasets and DB sources, hybrid data steps, settings, where runs happen (server runner vs your desktop app), reports and screenshots, schedules, review, masked secrets, and the recommended workflow.", body: () => uiTests_js_1.UI_TESTS_DOC },
         { name: "docs-ui-test-steps", uri: "callman://docs/ui-test-steps", title: "UI-test step reference", description: "Every UI-test step (web / Android / iOS / hybrid data steps): aliases, platforms, forms, arguments and an example — generated from callman-core, the same catalog the linter uses.", body: () => (0, callman_core_1.renderUiTestCommandReference)() },
+        { name: "docs-mocks", uri: "callman://docs/mocks", title: "Mock APIs", description: "Mock APIs from an AI tool: server mocks (public URL; static, template and builder responses, variants, request validation, delay, state, auth) vs local mocks on the user's desktop app (static, 127.0.0.1), how to turn a user's request into routes, limits, errors.", body: () => mocks_js_1.MOCKS_DOC },
         { name: "docs-diagram-schema", uri: "callman://docs/diagram-schema", title: "Diagram schema", description: "Every node and edge field, styling (colors, borders, fonts), containers, edge semantics and colors, patch operations and merge rules, and the stored DiagramDocument.", body: () => diagramSchema_js_1.DIAGRAM_SCHEMA_DOC },
     ];
     for (const doc of staticDocs) {

package/dist-cjs/server.js

@@ -7,8 +7,8 @@ const index_js_1 = require("./prompts/index.js");
 const index_js_2 = require("./resources/index.js");
 const index_js_3 = require("./tools/index.js");
 exports.SERVER_NAME = "callman";
-exports.SERVER_INSTRUCTIONS = `Callman is an API client and test platform: collections of HTTP requests, environments with variables, multi-step API test scenarios, UI tests (web / Android / iOS flows), and system-design diagrams. You act as the user whose token is configured, within that token's permissions and the user's workspace role.
-Start with whoami. The token works in every workspace the user belongs to: lists and searches cover all of them unless you pass \`workspace\`, names are looked up in the default workspace first and then everywhere, and results say which workspace they come from; creating something needs a target (\`workspace\`, the collection it goes into, or the session default — use_workspace). Names work as references (collection, folder, request, environment, scenario, UI test, diagram, workspace); ambiguous names return candidates. List before creating — duplicate collection names are refused. Preview large writes with dryRun: true; deletions need confirm: true and the user's agreement. Environment values are masked unless the token holds environments:reveal and you pass reveal: true; never write a masked value back. Arguments are strict — an unknown key is an error listing the valid ones. Read callman://docs/overview for the conventions, callman://docs/request-schema before creating or editing requests, callman://docs/contracts before contract checks, callman://docs/scenario-nodes before scenarios, callman://docs/ui-tests (+ callman://docs/ui-test-steps) before UI tests — they run on the server runner (web) or the user's own desktop app (list_ui_test_devices), and callman://docs/diagram-schema + callman://diagram/components before diagrams.`;
+exports.SERVER_INSTRUCTIONS = `Callman is an API client and test platform: collections of HTTP requests, environments with variables, multi-step API test scenarios, UI tests (web / Android / iOS flows), mock APIs, and system-design diagrams. You act as the user whose token is configured, within that token's permissions and the user's workspace role.
+Start with whoami. The token works in every workspace the user belongs to: lists and searches cover all of them unless you pass \`workspace\`, names are looked up in the default workspace first and then everywhere, and results say which workspace they come from; creating something needs a target (\`workspace\`, the collection it goes into, or the session default — use_workspace). Names work as references (collection, folder, request, environment, scenario, UI test, diagram, workspace); ambiguous names return candidates. List before creating — duplicate collection names are refused. Preview large writes with dryRun: true; deletions need confirm: true and the user's agreement. Environment values are masked unless the token holds environments:reveal and you pass reveal: true; never write a masked value back. Arguments are strict — an unknown key is an error listing the valid ones. Read callman://docs/overview for the conventions, callman://docs/request-schema before creating or editing requests, callman://docs/contracts before contract checks, callman://docs/scenario-nodes before scenarios, callman://docs/ui-tests (+ callman://docs/ui-test-steps) before UI tests — they run on the server runner (web) or the user's own desktop app (list_ui_test_devices), callman://docs/mocks before mock APIs (create_mock: a public URL on the server, or target: "desktop" for a local mock in the user's desktop app), and callman://docs/diagram-schema + callman://diagram/components before diagrams.`;
 const createCallmanMcpServer = (options) => {
     const version = options.version ?? "0.0.0";
     const context = (0, context_js_1.createToolContext)({
@@ -18,6 +18,7 @@ const createCallmanMcpServer = (options) => {
         logger: options.logger,
         cacheTtlMs: options.cacheTtlMs,
         pollDelaysMs: options.pollDelaysMs,
+        localMockPoll: options.localMockPoll,
     });
     const server = new mcp_js_1.McpServer({ name: exports.SERVER_NAME, version, title: "Callman" }, { capabilities: { tools: {}, resources: {}, prompts: {} }, instructions: exports.SERVER_INSTRUCTIONS });
     const tools = (0, index_js_3.registerAllTools)(server, context);

package/dist-cjs/tools/catalog.js

@@ -99,6 +99,24 @@ exports.TOOL_CATALOG = [
     { name: "restore_ui_test_version", group: "uiTests", scopes: ["ui_tests:write"] },
     { name: "export_ui_tests", group: "uiTests", scopes: ["ui_tests:read"] },
     { name: "import_ui_tests", group: "uiTests", scopes: ["ui_tests:write"] },
+    // Mock APIs: mocks:* scopes. Server mocks (/api/mocks) and, with
+    // target: "desktop", the local mocks of the user's own desktop app.
+    { name: "list_mocks", group: "mocks", scopes: ["mocks:read"] },
+    { name: "get_mock", group: "mocks", scopes: ["mocks:read"] },
+    { name: "get_mock_logs", group: "mocks", scopes: ["mocks:read"] },
+    { name: "get_mock_stats", group: "mocks", scopes: ["mocks:read"] },
+    { name: "get_mock_state", group: "mocks", scopes: ["mocks:read"] },
+    { name: "create_mock", group: "mocks", scopes: ["mocks:write"] },
+    { name: "update_mock", group: "mocks", scopes: ["mocks:write"] },
+    { name: "add_mock_route", group: "mocks", scopes: ["mocks:write"] },
+    { name: "update_mock_route", group: "mocks", scopes: ["mocks:write"] },
+    { name: "reorder_mock_routes", group: "mocks", scopes: ["mocks:write"] },
+    { name: "set_mock_state", group: "mocks", scopes: ["mocks:write"] },
+    { name: "reset_mock_state", group: "mocks", scopes: ["mocks:write"] },
+    { name: "start_mock", group: "mocks", scopes: ["mocks:write"] },
+    { name: "stop_mock", group: "mocks", scopes: ["mocks:write"] },
+    { name: "delete_mock", group: "mocks", scopes: ["mocks:delete"], destructive: true },
+    { name: "delete_mock_route", group: "mocks", scopes: ["mocks:delete"], destructive: true },
     { name: "list_diagrams", group: "diagrams", scopes: ["diagrams:read"] },
     { name: "get_diagram", group: "diagrams", scopes: ["diagrams:read"] },
     { name: "create_diagram", group: "diagrams", scopes: ["diagrams:write"] },

package/dist-cjs/tools/index.js

@@ -9,6 +9,7 @@ const environments_js_1 = require("./environments.js");
 const import_js_1 = require("./import.js");
 const loadTest_js_1 = require("./loadTest.js");
 const meta_js_1 = require("./meta.js");
+const mocks_js_1 = require("./mocks.js");
 const requests_js_1 = require("./requests.js");
 const run_js_1 = require("./run.js");
 const scenarios_js_1 = require("./scenarios.js");
@@ -56,6 +57,7 @@ const registerAllTools = (host, ctx) => {
     (0, uiTests_js_1.registerUiTestTools)(server, ctx);
     (0, uiTestRuns_js_1.registerUiTestRunTools)(server, ctx);
     (0, uiTestAdmin_js_1.registerUiTestAdminTools)(server, ctx);
+    (0, mocks_js_1.registerMockTools)(server, ctx);
     (0, diagrams_js_1.registerDiagramTools)(server, ctx);
     if (ctx.config.allowLocalRun) {
         (0, run_js_1.registerRunTools)(server, ctx);

package/dist-cjs/tools/meta.js

@@ -8,6 +8,30 @@ const shared_js_1 = require("./shared.js");
 // 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.
+// Mock APIs at a glance: is the feature on, which of read / write / delete the
+// token holds, and whether a desktop app is online for target: "desktop".
+const mocksOverview = async (ctx, scopes, features, workspaceId) => {
+    const held = new Set(scopes);
+    const mine = catalog_js_1.TOOL_CATALOG.filter((entry) => entry.group === "mocks");
+    const usable = mine.filter((entry) => entry.scopes.every((scope) => held.has(scope)));
+    let desktopOnline = null;
+    if (held.has("mocks:read") && features.mocks !== false) {
+        try {
+            desktopOnline = (await ctx.api.listLocalMockAgents(workspaceId)).agents.length > 0;
+        }
+        catch {
+            desktopOnline = null;
+        }
+    }
+    return {
+        featureEnabled: features.mocks ?? null,
+        scopes: { read: held.has("mocks:read"), write: held.has("mocks:write"), delete: held.has("mocks:delete") },
+        toolsAvailable: usable.length,
+        toolsTotal: mine.length,
+        desktopAppOnline: desktopOnline,
+        ...(held.has("mocks:read") ? { desktopHint: 'target: "desktop" (local mocks on the user\'s computer) needs the Callman desktop app open and signed in, with Settings → AI tools → "Let AI tools manage local mock APIs on this computer" on. Read callman://docs/mocks.' } : {}),
+    };
+};
 const registerMetaTools = (server, ctx) => {
     server.registerTool("whoami", {
         title: "Who am I (connection check)",
@@ -52,6 +76,8 @@ const registerMetaTools = (server, ctx) => {
             : workspaces.length === 1
                 ? workspaces[0]
                 : null;
+        const tools = (0, catalog_js_1.toolAvailability)(me.token.scopes, ctx.config.allowLocalRun);
+        const mocks = await mocksOverview(ctx, me.token.scopes, features, defaultWorkspace?.id ?? workspaces[0]?.id ?? null);
         return (0, shared_js_1.ok)({
             apiUrl: ctx.config.apiUrl,
             connected: true,
@@ -79,7 +105,8 @@ const registerMetaTools = (server, ctx) => {
                 : {}),
             features,
             localRun: ctx.config.allowLocalRun,
-            tools: (0, catalog_js_1.toolAvailability)(me.token.scopes, ctx.config.allowLocalRun),
+            mocks,
+            tools,
         });
     }));
 };