From 81d06cfc97a6f9fb9726fc4443f6278bc2e982e2 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 19:47:58 -0600 Subject: [PATCH] feat(mcp-tasks): add a demo MCP server that uses Tasks, test against it, and keep audit records out of agent errors (#21464) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents call tools in connected apps through the tool gateway, which speaks MCP to each app > - MCP Tasks (#21263) lets an app answer a long tool call with a durable task. It shipped behind the experimental setting `enableMcpTasks`, off by default > - No public app returns tasks without credentials, so nobody had seen the feature work against a real server, and it was hard to understand > - This pull request adds a small demo app that uses Tasks, tests the gateway against it over HTTP, and records a live end-to-end run > - The live run found one bug: every task stop sent the call's audit record, with a server stack trace, to the agent. This pull request fixes it > - The benefit is a repeatable way to try and test Tasks, plain-language docs, and evidence for the decision to turn the setting on ## Linked Issues or Issue Description Refs #21389 Refs #21263 ## What Changed - Add an MCP Tasks demo server to `packages/kv-demo-mcp-server` (new bin `paperclip-tasks-demo-mcp-server`; run `node packages/kv-demo-mcp-server/dist/tasks/main.js` after a build). It is stateless MCP 2026-07-28 with `server/discover`, and it declares `io.modelcontextprotocol/tasks`. It has six tools: `slow_report`, `needs_approval` (form question), `will_fail`, `cancellable`, `expires`, and `quick_echo`. It saves task state to a file, so it can restart mid-task. It needs no credentials. It has a status page at `/` and JSON at `/api/state`. - I put it in the existing demo package, so there is no new workspace package and no `pnpm-lock.yaml` change. - Add `server/src/__tests__/mcp-tasks-demo-server.test.ts`. It runs the real gateway against the real demo server over HTTP, with one test per tool plus a restart. - Fix: `server/src/routes/tool-gateway.ts` no longer sends `details.execution` to callers. That record has request IDs and the server-side error stack. The audit still keeps it. Add `server/src/__tests__/tool-gateway-agent-errors.test.ts` (red before the fix, green after). - Docs: `doc/connections/MCP-TASKS.md` now has "In plain words", "What a person sees", "Try it yourself", the live-run results, and a recommendation. The package README documents the demo server. - `enableMcpTasks` stays off by default. ## Verification - `packages/kv-demo-mcp-server`: `npx vitest run` gives 25/25 pass (13 new demo-server tests). `tsc -p tsconfig.test.json` is clean. - `server`: `mcp-tasks-demo-server.test.ts` gives 8/8 pass. `tool-gateway-agent-errors.test.ts` gives 2/2 pass, and it failed 2/2 before the fix. - Existing suites that cover the changed route and Tasks: `mcp-tasks.test.ts` and `tool-gateway-discovery-http.test.ts` (results in a comment below). - `pnpm verify` exits 2, because the doc is a global CI input. Required CI gives the broad coverage. - Live end-to-end run on a local `test-drive` instance with `enableMcpTasks` on. The agent was Codex `gpt-6-luna` at low effort. The demo was connected through "Connect your own MCP server": | Behaviour | Result | `tools/call` count at the app | | --- | --- | --- | | Polling (`slow_report`, 45 s) | Delivered after 22 polls | 1 | | Question (`needs_approval`) | The card was answered in the UI. `tasks/update` was sent, and the task finished | 1 | | Failure (`will_fail`) | `provider_task_failed` with the app's message | 1 | | Cancel (`cancellable`) | Stop on the run sent `tasks/cancel` | 1 | | Expiry (`expires`, 15 s) | `provider_task_expired`, no hang | 1 | | Restart (`slow_report`, 120 s) | The server was down for 2 min 23 s. The result was delivered once, and the agent was woken once | 1 | After the run, all 6 `tool_mcp_tasks` rows were settled and none had a next poll. ## Risks - Low risk. The demo server is new code in a demo package, and the bin is additive. - The route change removes `execution` from tool-gateway error responses. No UI code or test reads that field from these responses. The audit and tool-call events still record it. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- doc/connections/MCP-TASKS.md | 118 ++++++++ packages/kv-demo-mcp-server/README.md | 50 ++++ packages/kv-demo-mcp-server/package.json | 6 +- packages/kv-demo-mcp-server/src/index.ts | 4 + .../kv-demo-mcp-server/src/tasks/http.test.ts | 220 +++++++++++++++ packages/kv-demo-mcp-server/src/tasks/http.ts | 257 ++++++++++++++++++ packages/kv-demo-mcp-server/src/tasks/main.ts | 34 +++ .../kv-demo-mcp-server/src/tasks/render.ts | 64 +++++ .../kv-demo-mcp-server/src/tasks/store.ts | 157 +++++++++++ .../kv-demo-mcp-server/src/tasks/tools.ts | 207 ++++++++++++++ .../__tests__/mcp-tasks-demo-server.test.ts | 197 ++++++++++++++ .../tool-gateway-agent-errors.test.ts | 51 ++++ server/src/routes/tool-gateway.ts | 14 +- 13 files changed, 1375 insertions(+), 4 deletions(-) create mode 100644 packages/kv-demo-mcp-server/src/tasks/http.test.ts create mode 100644 packages/kv-demo-mcp-server/src/tasks/http.ts create mode 100644 packages/kv-demo-mcp-server/src/tasks/main.ts create mode 100644 packages/kv-demo-mcp-server/src/tasks/render.ts create mode 100644 packages/kv-demo-mcp-server/src/tasks/store.ts create mode 100644 packages/kv-demo-mcp-server/src/tasks/tools.ts create mode 100644 server/src/__tests__/mcp-tasks-demo-server.test.ts create mode 100644 server/src/__tests__/tool-gateway-agent-errors.test.ts diff --git a/doc/connections/MCP-TASKS.md b/doc/connections/MCP-TASKS.md index bf2219916bc..bc1e4da5148 100644 --- a/doc/connections/MCP-TASKS.md +++ b/doc/connections/MCP-TASKS.md @@ -7,6 +7,65 @@ hands the agent the final result exactly as a quick call would return it. If the call outlives its timeout, or Paperclip restarts or deploys mid-call, the work is not lost and is never started a second time. +## In plain words + +Without Tasks, an agent that asks an app to do something slow has to hold the +line until the app finishes. If the wait is too long, or Paperclip restarts, +the answer is lost, and calling again may start the work a second time. + +With Tasks, the app answers straight away with a ticket ("task") and does the +work in the background. Paperclip keeps the ticket and checks on it every few +seconds. When the work is done, the agent gets the result as if the call had +simply been slow. If Paperclip restarts, it picks the ticket up again. It never +asks the app to start the same work twice. + +A task can also stop and ask a question ("approve this deploy?"). Paperclip +turns that into a question card on the task, and the person's answer goes back +to the app. + +### What a person sees + +| Situation | In the task chat | +| --- | --- | +| A long action is running | The agent's turn shows the tool as running. The agent keeps waiting, or is told to call again later. | +| The app asks a question | A **Tool needs input** card with the app's question. Answering it wakes the agent, which carries on. | +| The app reports a failure | The agent receives a tool error with the app's message. | +| Someone presses **Stop** on the run | Paperclip tells the app to cancel the work. | +| The app no longer has the task | The agent is told the result is gone and to run the action again. | +| Paperclip restarts mid-action | Nothing to do. The run resumes and the result arrives once. | + +### Try it yourself + +The repository includes a demo app that uses Tasks. It needs no accounts or +keys, and its "work" is a timer. The steps take about 10 minutes. + +1. Start the demo app: + + ```sh + pnpm --filter @paperclipai/kv-demo-mcp-server build + node packages/kv-demo-mcp-server/dist/tasks/main.js + ``` + + Open `http://127.0.0.1:8849/` to watch its tasks live. +2. In Paperclip, open **Instance settings โ†’ Experimental** and turn on + **Durable app actions (MCP Tasks)**. +3. Open **Apps โ†’ Connect your own MCP server**, paste + `http://127.0.0.1:8849/mcp`, and choose **Check link**. Six actions appear. +4. Give an agent a task such as: *"Call the connected app tool `slow_report` + with `{"topic": "uptime", "seconds": 45}`. If it says the app is still + working, call it again with the same arguments. Post the report."* The + agent must be one that receives app tools: a Paperclip runner agent or a + Codex agent. Plain local OpenCode and Claude agents do not get app tools + yet. +5. Try the other tools the same way: `needs_approval` (answer the card), + `will_fail`, `cancellable` (press **Stop** while it runs), and `expires`. +6. To see a restart, start `slow_report` with `"seconds": 120`, stop the + Paperclip server, and start it again. The report still arrives once. On the + demo's status page, `slow_report` was started one time. + +The package [README](../../packages/kv-demo-mcp-server/README.md) lists the +demo's options. + ## Turning it on MCP Tasks are behind the experimental setting **Durable app actions (MCP @@ -121,6 +180,60 @@ returns to approved, and its next execution attaches to the same task. - Showing a long-running provider action's progress (`statusMessage`) in the task chat. +## Live check with the demo app (2026-11-13) + +One local Paperclip (`test-drive`, embedded database, `enableMcpTasks` on), the +demo app connected through **Connect your own MCP server**, and a Codex agent +on a small model. Each behaviour was one task given to the agent in plain +words. + +| Behaviour | Result | Demo app `tools/call` count | Stored task row | +| --- | --- | --- | --- | +| Polling (`slow_report`, 45 s) | Report delivered; 22 `tasks/get` at the app's 2 s interval | 1 | `completed`, delivered | +| Question (`needs_approval`) | Card shown; the person's answer woke the agent; `tasks/update` sent; result delivered | 1 | `completed`, delivered | +| Failure (`will_fail`) | Tool error with the app's message (`provider_task_failed`) | 1 | `failed` | +| Cancel (`cancellable`) | **Stop** on the run sent `tasks/cancel`; the app stopped the work | 1 | `cancelled` (`run_cancelled`) | +| Expiry (`expires`, 15 s TTL) | Clear "run the action again" error (`provider_task_expired`), no hang | 1 | `expired` (`ttl_expired`) | +| Restart (`slow_report`, 120 s) | Server killed 6 s into the task and down for 2 min 23 s. On start it polled the stored task, woke the agent once, and the new run collected the report | 1 | `completed`, delivered, woken once | + +Afterwards no task row had a next poll, so background polling stopped. + +The run found one bug, fixed with the demo: every task stop (still working, +expired, failed, cancelled) returned the call's audit record to the agent, +including the server-side stack trace and request IDs. The agent pasted it into +the task. Agent-facing errors now leave that record out; the audit keeps it. + +What the run also showed, outside Tasks itself: + +- Only Paperclip runner and Codex agents receive app tools. A plain local + OpenCode agent did not see the demo's tools and called the app directly with + `curl`, bypassing Paperclip. +- The running-tool row and the agent's error text show the internal tool name + of a custom connection, including the connection ID + (`mcp.app-gallery-link--:slow-report`). +- Pressing **Stop** shows "Couldn't finish this attempt", which reads as a + failure. +- The running row shows no progress for a long action (`statusMessage` is not + displayed; listed under Follow-ups). + +## Is it ready to be on by default? + +**Not yet.** The demo showed every behaviour working with a real HTTP server, +including a restart, with each action started exactly once. Three of the four +findings in [#21389](https://github.com/paperclipai/paperclip/issues/21389) +still stand, and the demo does not exercise them: + +1. Turning the setting off and on again leaves stored tasks idle until the + next unrelated wake. +2. A cloud instance that turns it on through managed configuration does not + count pending tasks as an idle-sleep blocker. +3. A failed settings read counts as "off". A retry can then skip its stored + task and send `tools/call` again, which breaks the "never started twice" + promise. + +Fix those three and turn it on by default. Validating question-card answers +(the fourth finding) and showing progress can follow. + ## Tests `server/src/__tests__/mcp-tasks.test.ts` runs a fake 2026-07-28 server that @@ -129,3 +242,8 @@ attaching call, a keyed retry, a restart mid-task (fresh gateway, no second `tools/call`, one wake, one delivery), URL and form input, cancellation by the run and by closing the task, failure, an unknown task, TTL expiry, another agent never attaching, and synchronous calls left unchanged. + +`server/src/__tests__/mcp-tasks-demo-server.test.ts` runs the same gateway +against the real demo app (`packages/kv-demo-mcp-server/src/tasks`) over HTTP, +one test per demo tool, plus a restart. The demo's own tests are in +`packages/kv-demo-mcp-server/src/tasks/http.test.ts`. diff --git a/packages/kv-demo-mcp-server/README.md b/packages/kv-demo-mcp-server/README.md index 7934bd25b4c..ea1daaa90e1 100644 --- a/packages/kv-demo-mcp-server/README.md +++ b/packages/kv-demo-mcp-server/README.md @@ -205,3 +205,53 @@ records stay intact unless you also archive the connection. The KV demo is a fixture, not a piece of infrastructure. Treat each session as disposable: start it, run the demo, kill it. + +## MCP Tasks demo server + +The same package ships a second server, `paperclip-tasks-demo-mcp-server`, for +trying [MCP Tasks](../../doc/connections/MCP-TASKS.md): long tool calls that +return a task, which the client polls until it finishes. It speaks the +stateless MCP revision 2026-07-28 (`server/discover`, no session) and declares +the `io.modelcontextprotocol/tasks` extension. It needs no credentials and +calls nothing outside its own process: the "work" is a timer. + +| Tool | What it shows | +| --- | --- | +| `slow_report` | Returns a task, then a report after `seconds` (default 20). Polling. | +| `needs_approval` | Asks a form question (approve or reject); finishes after the answer arrives with `tasks/update`. | +| `will_fail` | Fails after `seconds` (default 5). A failed task. | +| `cancellable` | Runs for `seconds` (default 600) and stops on `tasks/cancel`. | +| `expires` | Its TTL (`ttlSeconds`, default 15) passes before it finishes, so the server forgets it. | +| `quick_echo` | Answers at once, without a task. | + +It returns a task only to a request that declares the extension. Without it, +the long tools answer with an error that says the client does not support +MCP Tasks. + +Start it from the repo root: + +```sh +pnpm --filter @paperclipai/kv-demo-mcp-server build +node packages/kv-demo-mcp-server/dist/tasks/main.js +``` + +It listens on `http://127.0.0.1:8849`: + +- **MCP endpoint**: `POST /mcp` +- **Status page**: `GET /`, which lists every task, how many times each tool was + started, and the latest protocol events. It reloads every 2 seconds. +- **JSON state**: `GET /api/state`, the same data for scripts. + +Task state is saved to a file (by default `~/.paperclip-tasks-demo/state.json`), +so you can stop and start the server mid-task. A task's progress is worked out +from the clock, so a restart neither resets nor repeats it. + +| Variable | Default | Purpose | +| --- | --- | --- | +| `TASKS_DEMO_PORT` (or `PORT`) | `8849` | Port to listen on. | +| `TASKS_DEMO_HOST` | `127.0.0.1` | Interface to bind. | +| `TASKS_DEMO_STATE_FILE` | `~/.paperclip-tasks-demo/state.json` | Where task state is saved. Its folder must be yours and not writable by others. `memory` keeps it in memory only. | +| `TASKS_DEMO_TOKEN` | unset | When set, `/mcp` and `/api/state` require `Authorization: Bearer `. | + +See "Try it yourself" in [MCP-TASKS.md](../../doc/connections/MCP-TASKS.md) for +the full walkthrough with Paperclip. diff --git a/packages/kv-demo-mcp-server/package.json b/packages/kv-demo-mcp-server/package.json index 2a39a1c6b89..f7a28baa5c3 100644 --- a/packages/kv-demo-mcp-server/package.json +++ b/packages/kv-demo-mcp-server/package.json @@ -13,7 +13,8 @@ }, "type": "module", "bin": { - "paperclip-kv-demo-mcp-server": "./dist/main.js" + "paperclip-kv-demo-mcp-server": "./dist/main.js", + "paperclip-tasks-demo-mcp-server": "./dist/tasks/main.js" }, "exports": { ".": "./src/index.ts" @@ -21,7 +22,8 @@ "publishConfig": { "access": "public", "bin": { - "paperclip-kv-demo-mcp-server": "./dist/main.js" + "paperclip-kv-demo-mcp-server": "./dist/main.js", + "paperclip-tasks-demo-mcp-server": "./dist/tasks/main.js" }, "exports": { ".": { diff --git a/packages/kv-demo-mcp-server/src/index.ts b/packages/kv-demo-mcp-server/src/index.ts index 98710d03880..a67a5fb8ed9 100644 --- a/packages/kv-demo-mcp-server/src/index.ts +++ b/packages/kv-demo-mcp-server/src/index.ts @@ -40,3 +40,7 @@ export { createKvDemoHttpServer } from "./http.js"; export type { KvDemoHttpServer, KvDemoHttpOptions } from "./http.js"; export { readConfigFromEnv } from "./config.js"; export type { KvDemoConfig } from "./config.js"; +export { createTasksDemoHttpServer, handleTasksDemoRpc, PROTOCOL_VERSION as TASKS_DEMO_PROTOCOL_VERSION, TASKS_EXTENSION_ID } from "./tasks/http.js"; +export type { TasksDemoHttpServer, TasksDemoHttpOptions } from "./tasks/http.js"; +export { DemoTaskStore } from "./tasks/store.js"; +export type { DemoTask, DemoTaskStatus, DemoState } from "./tasks/store.js"; diff --git a/packages/kv-demo-mcp-server/src/tasks/http.test.ts b/packages/kv-demo-mcp-server/src/tasks/http.test.ts new file mode 100644 index 00000000000..c66293d4b79 --- /dev/null +++ b/packages/kv-demo-mcp-server/src/tasks/http.test.ts @@ -0,0 +1,220 @@ +import { chmodSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import { PROTOCOL_VERSION, TASKS_EXTENSION_ID, createTasksDemoHttpServer, type TasksDemoHttpServer } from "./http.js"; +import { DemoTaskStore } from "./store.js"; + +let clock = Date.parse("2026-11-13T12:00:00Z"); +const now = () => clock; +const servers: TasksDemoHttpServer[] = []; +const dirs: string[] = []; + +afterEach(async () => { + await Promise.all(servers.splice(0).map((server) => server.close())); + for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }); +}); + +async function start(store = new DemoTaskStore({ now })) { + const server = createTasksDemoHttpServer({ store }); + servers.push(server); + const port = await server.listen(0); + return { server, url: `http://127.0.0.1:${port}` }; +} + +/** Send one request the way Paperclip's stateless client does. */ +async function rpc(url: string, method: string, params: Record = {}, options: { tasks?: boolean; name?: string; version?: string } = {}) { + const name = options.name ?? (typeof params.taskId === "string" ? params.taskId : typeof params.name === "string" ? params.name : undefined); + const response = await fetch(`${url}/mcp`, { + method: "POST", + headers: { + "content-type": "application/json", + "mcp-protocol-version": options.version ?? PROTOCOL_VERSION, + "mcp-method": method, + ...(name !== undefined ? { "mcp-name": name } : {}), + }, + body: JSON.stringify({ + jsonrpc: "2.0", id: 1, method, + params: { + ...params, + _meta: { + "io.modelcontextprotocol/protocolVersion": options.version ?? PROTOCOL_VERSION, + "io.modelcontextprotocol/clientCapabilities": { extensions: options.tasks === false ? {} : { [TASKS_EXTENSION_ID]: {} } }, + }, + }, + }), + }); + return { status: response.status, body: await response.json() as { result?: Record; error?: { code: number; message: string; data?: any } } }; +} + +const call = (url: string, name: string, args: Record = {}, tasks = true) => rpc(url, "tools/call", { name, arguments: args }, { tasks }); +const get = (url: string, taskId: string) => rpc(url, "tasks/get", { taskId }); + +describe("MCP Tasks demo server", () => { + it("advertises the Tasks extension on a stateless server and refuses the old handshake", async () => { + const { url } = await start(); + const discover = await rpc(url, "server/discover"); + expect(discover.body.result).toMatchObject({ resultType: "complete", supportedVersions: [PROTOCOL_VERSION], capabilities: { extensions: { [TASKS_EXTENSION_ID]: {} } } }); + const legacy = await rpc(url, "initialize", {}, { version: "2025-11-25" }); + expect(legacy.status).toBe(400); + expect(legacy.body.error).toMatchObject({ code: -32022, data: { supported: [PROTOCOL_VERSION] } }); + const tools = await rpc(url, "tools/list"); + expect(tools.body.result!.tools.map((tool: { name: string }) => tool.name)).toEqual(["slow_report", "needs_approval", "will_fail", "cancellable", "expires", "quick_echo"]); + }); + + it("returns a task only to a request that declared the extension", async () => { + const { url } = await start(); + const plain = await call(url, "slow_report", {}, false); + expect(plain.body.result).toMatchObject({ resultType: "complete", isError: true }); + const quick = await call(url, "quick_echo", { text: "hi" }); + expect(quick.body.result).toMatchObject({ resultType: "complete", content: [{ type: "text", text: "echo: hi" }] }); + const tasks = await rpc(url, "tasks/get", { taskId: "anything" }, { tasks: false }); + expect(tasks.body.error?.code).toBe(-32021); + }); + + it("slow_report: works, then completes with its result after the delay", async () => { + const { url, server } = await start(); + const created = await call(url, "slow_report", { topic: "uptime", seconds: 30 }); + expect(created.body.result).toMatchObject({ resultType: "task", status: "working", ttlMs: 30_000 + 3_600_000, pollIntervalMs: 2_000 }); + const taskId = created.body.result!.taskId as string; + clock += 15_000; + expect((await get(url, taskId)).body.result).toMatchObject({ resultType: "complete", status: "working", statusMessage: "50% done (15 of 30 s)" }); + clock += 15_000; + const done = await get(url, taskId); + expect(done.body.result).toMatchObject({ status: "completed", result: { isError: false, structuredContent: { topic: "uptime", seconds: 30 } } }); + expect(server.store.snapshot().toolCalls).toEqual({ slow_report: 1 }); + }); + + it("requires Mcp-Name to carry the task ID", async () => { + const { url } = await start(); + const taskId = (await call(url, "slow_report")).body.result!.taskId as string; + const wrong = await rpc(url, "tasks/get", { taskId }, { name: "other" }); + expect(wrong.body.error?.code).toBe(-32020); + }); + + it("needs_approval: asks a form question, then finishes after tasks/update", async () => { + const { url } = await start(); + const created = await call(url, "needs_approval", { action: "deploy" }); + const taskId = created.body.result!.taskId as string; + const waiting = await get(url, taskId); + expect(waiting.body.result).toMatchObject({ + status: "input_required", + inputRequests: { approval: { method: "elicitation/create", params: { mode: "form", requestedSchema: { required: ["decision"] } } } }, + }); + // An answer the form does not allow asks again, under a new key: a client + // treats a key it already answered as done and would never show it again. + await rpc(url, "tasks/update", { taskId, inputResponses: { approval: { action: "accept", content: { decision: "maybe" } } } }); + const again = (await get(url, taskId)).body.result!; + expect(again).toMatchObject({ status: "input_required", inputRequests: { "approval-2": { params: { message: "Please choose approve or reject." } } } }); + expect(again.inputRequests).not.toHaveProperty("approval"); + // An answer to the old key is ignored. + await rpc(url, "tasks/update", { taskId, inputResponses: { approval: { action: "accept", content: { decision: "approve" } } } }); + expect((await get(url, taskId)).body.result).toMatchObject({ status: "input_required" }); + await rpc(url, "tasks/update", { taskId, inputResponses: { "approval-2": { action: "accept", content: { decision: "approve", note: "ship it" } } } }); + expect((await get(url, taskId)).body.result).toMatchObject({ status: "working" }); + clock += 3_000; + expect((await get(url, taskId)).body.result).toMatchObject({ status: "completed", result: { structuredContent: { approved: true, action: "deploy", note: "ship it" } } }); + }); + + it("needs_approval: a rejection or decline completes without doing anything", async () => { + const { url } = await start(); + for (const response of [{ action: "accept", content: { decision: "reject" } }, { action: "decline" }]) { + const taskId = (await call(url, "needs_approval")).body.result!.taskId as string; + await rpc(url, "tasks/update", { taskId, inputResponses: { approval: response } }); + expect((await get(url, taskId)).body.result).toMatchObject({ status: "completed", result: { structuredContent: { approved: false } } }); + } + }); + + it("keeps even the longest jobs long enough to collect their result", async () => { + const { url } = await start(); + const report = (await call(url, "slow_report", { seconds: 3600 })).body.result!.taskId as string; + const failure = (await call(url, "will_fail", { seconds: 3600 })).body.result!.taskId as string; + clock += 3_600_000 + 60_000; + expect((await get(url, report)).body.result).toMatchObject({ status: "completed" }); + expect((await get(url, failure)).body.result).toMatchObject({ status: "failed" }); + }); + + it("shows what finished or expired while no client was polling", async () => { + const { url } = await start(); + await call(url, "slow_report", { seconds: 10 }); + await call(url, "expires", { ttlSeconds: 5 }); + clock += 10_000; + const state = await (await fetch(`${url}/api/state`)).json() as { tasks: Array<{ tool: string; status: string }> }; + expect(state.tasks.map((task) => [task.tool, task.status])).toEqual([["slow_report", "completed"]]); + expect(await (await fetch(url)).text()).toContain("completed"); + }); + + it("does not record calls to tools it does not have", async () => { + const { url, server } = await start(); + for (const name of ["nope-1", "nope-2"]) expect((await call(url, name)).body.error?.code).toBe(-32602); + expect(server.store.snapshot().toolCalls).toEqual({}); + }); + + it("will_fail: ends failed with a JSON-RPC error", async () => { + const { url } = await start(); + const taskId = (await call(url, "will_fail", { seconds: 2 })).body.result!.taskId as string; + clock += 2_000; + expect((await get(url, taskId)).body.result).toMatchObject({ status: "failed", error: { code: -32603, message: expect.stringContaining("on purpose") } }); + }); + + it("cancellable: tasks/cancel stops it, and a second cancel is refused", async () => { + const { url } = await start(); + const taskId = (await call(url, "cancellable")).body.result!.taskId as string; + expect((await rpc(url, "tasks/cancel", { taskId })).body.result).toEqual({ resultType: "complete" }); + // Past when the work would have finished: it stays cancelled. + clock += 600_000; + expect((await get(url, taskId)).body.result).toMatchObject({ status: "cancelled" }); + expect((await rpc(url, "tasks/cancel", { taskId })).body.error?.code).toBe(-32602); + }); + + it("expires: is forgotten once its TTL passes, before it finishes", async () => { + const { url } = await start(); + const created = await call(url, "expires", { ttlSeconds: 5 }); + expect(created.body.result).toMatchObject({ ttlMs: 5_000 }); + const taskId = created.body.result!.taskId as string; + clock += 4_000; + expect((await get(url, taskId)).body.result).toMatchObject({ status: "working" }); + clock += 1_000; + expect((await get(url, taskId)).body.error).toMatchObject({ code: -32602, message: expect.stringContaining("not found") }); + }); + + it("keeps tasks across a restart when given a state file", async () => { + const dir = mkdtempSync(join(tmpdir(), "tasks-demo-")); + dirs.push(dir); + const file = join(dir, "state.json"); + const first = await start(new DemoTaskStore({ file, now })); + const taskId = (await call(first.url, "slow_report", { seconds: 10 })).body.result!.taskId as string; + await first.server.close(); + servers.splice(servers.indexOf(first.server), 1); + clock += 10_000; + const second = await start(new DemoTaskStore({ file, now })); + expect((await get(second.url, taskId)).body.result).toMatchObject({ status: "completed" }); + expect(second.server.store.snapshot().toolCalls).toEqual({ slow_report: 1 }); + }); + + it("refuses a state directory other users can write to, and writes through no planted file", async () => { + const shared = mkdtempSync(join(tmpdir(), "tasks-demo-shared-")); + dirs.push(shared); + chmodSync(shared, 0o777); + expect(() => new DemoTaskStore({ file: join(shared, "state.json"), now })).toThrow(/others cannot write/); + + const dir = mkdtempSync(join(tmpdir(), "tasks-demo-")); + dirs.push(dir); + const victim = join(dir, "victim.txt"); + writeFileSync(victim, "keep me"); + // A link at the old predictable temp name must not be followed. + symlinkSync(victim, join(dir, `state.json.${process.pid}.tmp`)); + const store = new DemoTaskStore({ file: join(dir, "state.json"), now }); + store.countToolCall("slow_report"); + expect(readFileSync(victim, "utf8")).toBe("keep me"); + expect(JSON.parse(readFileSync(join(dir, "state.json"), "utf8")).toolCalls).toEqual({ slow_report: 1 }); + }); + + it("shows tasks on its status page", async () => { + const { url } = await start(); + await call(url, "slow_report"); + const html = await (await fetch(url)).text(); + expect(html).toContain("slow_report"); + expect(html).toContain("working"); + }); +}); diff --git a/packages/kv-demo-mcp-server/src/tasks/http.ts b/packages/kv-demo-mcp-server/src/tasks/http.ts new file mode 100644 index 00000000000..cd0f9dd6973 --- /dev/null +++ b/packages/kv-demo-mcp-server/src/tasks/http.ts @@ -0,0 +1,257 @@ +import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"; +import { DemoTaskStore, type DemoTask } from "./store.js"; +import { DEMO_TOOLS, advanceDemoTask, answerDemoTask, callDemoTool, statusMessageFor } from "./tools.js"; +import { renderTasksPage } from "./render.js"; + +/** + * A stateless MCP server (protocol 2026-07-28) that supports the MCP Tasks + * extension. It speaks JSON-RPC over plain HTTP POST: no session, no SSE, and + * every request carries its protocol version and client capabilities in + * `params._meta`, as the 2026-07-28 revision requires. + */ +export const PROTOCOL_VERSION = "2026-07-28"; +export const TASKS_EXTENSION_ID = "io.modelcontextprotocol/tasks"; +const META_VERSION = "io.modelcontextprotocol/protocolVersion"; +const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities"; + +const HEADER_MISMATCH = -32020; +const MISSING_CAPABILITY = -32021; +const UNSUPPORTED_VERSION = -32022; +const INVALID_PARAMS = -32602; +const METHOD_NOT_FOUND = -32601; + +export interface TasksDemoHttpOptions { + store?: DemoTaskStore; + /** Optional shared secret required on every route except the status page. */ + token?: string | null; +} + +export interface TasksDemoHttpServer { + server: Server; + store: DemoTaskStore; + listen: (port: number, host?: string) => Promise; + close: () => Promise; +} + +type RpcRequest = { jsonrpc?: string; id?: string | number | null; method?: unknown; params?: Record }; +type Reply = { status: number; body: unknown } | null; + +function record(value: unknown): Record | null { + return value && typeof value === "object" && !Array.isArray(value) ? value as Record : null; +} + +function ok(id: unknown, result: Record): Reply { + return { status: 200, body: { jsonrpc: "2.0", id, result: { resultType: "complete", ...result } } }; +} + +function fail(status: number, id: unknown, code: number, message: string, data?: unknown): Reply { + return { status, body: { jsonrpc: "2.0", id: id ?? null, error: { code, message, ...(data !== undefined ? { data } : {}) } } }; +} + +/** `Mcp-Name` may be RFC 2047-style base64 (`=?base64?...?=`) for non-ASCII values. */ +function decodeHeaderValue(value: string | undefined): string | null { + if (value === undefined) return null; + const match = /^=\?base64\?(.*)\?=$/i.exec(value); + return match ? Buffer.from(match[1]!, "base64").toString("utf8") : value; +} + +function taskView(store: DemoTaskStore, task: DemoTask): Record { + const statusMessage = statusMessageFor(store, task); + return { + taskId: task.taskId, + status: task.status, + ...(statusMessage ? { statusMessage } : {}), + createdAt: new Date(task.createdAt).toISOString(), + lastUpdatedAt: new Date(task.lastUpdatedAt).toISOString(), + ttlMs: task.ttlMs, + pollIntervalMs: task.pollIntervalMs, + ...(task.status === "completed" ? { result: task.result } : {}), + ...(task.status === "failed" ? { error: task.error } : {}), + ...(task.status === "input_required" ? { inputRequests: task.inputRequests } : {}), + }; +} + +/** Handle one JSON-RPC request. Exported for tests. */ +export function handleTasksDemoRpc(store: DemoTaskStore, message: RpcRequest, headers: IncomingMessage["headers"]): Reply { + if (!record(message) || typeof message.method !== "string") return fail(400, null, -32600, "Invalid JSON-RPC request."); + const { id, method } = message; + if (id === undefined) return null; // A notification: nothing to answer. + const params = record(message.params) ?? {}; + const meta = record(params._meta) ?? {}; + const headerVersion = typeof headers["mcp-protocol-version"] === "string" ? headers["mcp-protocol-version"] : null; + + // A handshake-era client: tell it which version this server speaks. + if (method === "initialize") return fail(400, id, UNSUPPORTED_VERSION, "This server speaks only stateless MCP.", { supported: [PROTOCOL_VERSION] }); + if (headerVersion !== PROTOCOL_VERSION || meta[META_VERSION] !== PROTOCOL_VERSION) { + if (headerVersion && headerVersion !== PROTOCOL_VERSION) return fail(400, id, UNSUPPORTED_VERSION, `Unsupported protocol version ${headerVersion}.`, { supported: [PROTOCOL_VERSION] }); + return fail(400, id, HEADER_MISMATCH, "MCP-Protocol-Version header and params._meta protocolVersion must both be 2026-07-28."); + } + const mcpMethod = headers["mcp-method"]; + if (typeof mcpMethod === "string" && mcpMethod !== method) return fail(400, id, HEADER_MISMATCH, "Mcp-Method does not match the request."); + const declaredTasks = Boolean(record(record(record(meta[META_CAPABILITIES])?.extensions)?.[TASKS_EXTENSION_ID])); + const clientInfo = record(meta["io.modelcontextprotocol/clientInfo"]); + const client = typeof clientInfo?.name === "string" ? clientInfo.name : "unknown client"; + + switch (method) { + case "server/discover": + return ok(id, { + supportedVersions: [PROTOCOL_VERSION], + capabilities: { tools: {}, extensions: { [TASKS_EXTENSION_ID]: {} } }, + serverInfo: { name: "paperclip-tasks-demo", version: "0.1.0" }, + instructions: "Demo tools for MCP Tasks. Each long tool returns a task; nothing here touches real systems.", + }); + case "ping": + return ok(id, {}); + case "tools/list": + return ok(id, { tools: DEMO_TOOLS }); + case "tools/call": { + const name = params.name; + if (typeof name !== "string") return fail(200, id, INVALID_PARAMS, "tools/call needs a tool name."); + const mcpName = decodeHeaderValue(headers["mcp-name"] as string | undefined); + if (mcpName !== null && mcpName !== name) return fail(400, id, HEADER_MISMATCH, "Mcp-Name does not match the tool name."); + // Only known tools are counted, so made-up names cannot grow the saved state. + if (!DEMO_TOOLS.some((tool) => tool.name === name)) return fail(200, id, INVALID_PARAMS, `Unknown tool: ${name.slice(0, 64)}`); + store.countToolCall(name); + const outcome = callDemoTool(store, name, record(params.arguments) ?? {}, declaredTasks); + if (!outcome) return fail(200, id, INVALID_PARAMS, `Unknown tool: ${name.slice(0, 64)}`); + if (outcome.kind === "result") { + store.log({ method, tool: name, detail: declaredTasks ? "answered without a task" : `answered without a task: ${client} did not declare ${TASKS_EXTENSION_ID}` }); + return ok(id, outcome.result); + } + store.log({ method, tool: name, taskId: outcome.task.taskId, detail: `returned task (${outcome.task.status}) to ${client}` }); + const view = taskView(store, outcome.task); + return { status: 200, body: { jsonrpc: "2.0", id, result: { resultType: "task", ...view } } }; + } + case "tasks/get": + case "tasks/update": + case "tasks/cancel": { + if (!declaredTasks) return fail(400, id, MISSING_CAPABILITY, `${method} requires the ${TASKS_EXTENSION_ID} extension.`); + const taskId = params.taskId; + if (typeof taskId !== "string") return fail(200, id, INVALID_PARAMS, `${method} needs a taskId.`); + if (decodeHeaderValue(headers["mcp-name"] as string | undefined) !== taskId) return fail(400, id, HEADER_MISMATCH, "Mcp-Name must carry the task ID."); + const found = store.get(taskId); + if (!found) { + store.log({ method, taskId, detail: "task not found" }); + return fail(200, id, INVALID_PARAMS, "Failed to retrieve task: Task not found"); + } + const task = advanceDemoTask(store, found); + if (method === "tasks/get") { + task.polls += 1; + store.touch(); + store.log({ method, tool: task.tool, taskId, detail: task.status }); + return ok(id, taskView(store, task)); + } + if (method === "tasks/update") { + answerDemoTask(store, task, record(params.inputResponses) ?? {}); + store.log({ method, tool: task.tool, taskId, detail: `now ${task.status}` }); + return ok(id, {}); + } + if (task.status === "completed" || task.status === "failed" || task.status === "cancelled") { + store.log({ method, tool: task.tool, taskId, detail: `already ${task.status}` }); + return fail(200, id, INVALID_PARAMS, `Cannot cancel a task that is already ${task.status}.`); + } + store.update(task, { status: "cancelled", inputRequests: undefined, settlesAt: null }); + store.log({ method, tool: task.tool, taskId, detail: "cancelled; work stopped" }); + return ok(id, {}); + } + default: + return fail(404, id, METHOD_NOT_FOUND, `Method not found: ${method}`); + } +} + +/** + * State as of now: settle tasks whose time has come and forget expired ones, + * so the views show what finished while no client was polling. + */ +function refreshedSnapshot(store: DemoTaskStore) { + for (const { taskId } of store.snapshot().tasks) { + const task = store.get(taskId); + if (task) advanceDemoTask(store, task); + } + return store.snapshot(); +} + +function send(res: ServerResponse, status: number, body: unknown, type = "application/json"): void { + const payload = typeof body === "string" ? body : JSON.stringify(body); + res.writeHead(status, { "content-type": type, "content-length": Buffer.byteLength(payload) }); + res.end(payload); +} + +async function readBody(req: IncomingMessage): Promise { + const chunks: Buffer[] = []; + let size = 0; + for await (const chunk of req) { + size += (chunk as Buffer).length; + if (size > 1_000_000) throw new Error("Request body too large."); + chunks.push(chunk as Buffer); + } + return Buffer.concat(chunks).toString("utf8"); +} + +export function createTasksDemoHttpServer(options: TasksDemoHttpOptions = {}): TasksDemoHttpServer { + const store = options.store ?? new DemoTaskStore(); + const token = options.token?.trim() || null; + + const server = createServer((req, res) => { + void (async () => { + try { + const url = new URL(req.url ?? "/", "http://localhost"); + if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/index.html")) { + send(res, 200, renderTasksPage(token ? null : refreshedSnapshot(store), store.now()), "text/html; charset=utf-8"); + return; + } + if (token && req.headers.authorization !== `Bearer ${token}`) { + send(res, 401, { error: "Unauthorized. Provide the TASKS_DEMO_TOKEN as a Bearer token." }); + return; + } + if (req.method === "GET" && url.pathname === "/api/state") { + send(res, 200, refreshedSnapshot(store)); + return; + } + if (url.pathname === "/mcp") { + if (req.method !== "POST") { + res.writeHead(405, { allow: "POST" }).end(); + return; + } + let message: RpcRequest; + try { + message = JSON.parse(await readBody(req)) as RpcRequest; + } catch { + send(res, 400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }); + return; + } + const reply = handleTasksDemoRpc(store, message, req.headers); + if (!reply) { + res.writeHead(202).end(); + return; + } + send(res, reply.status, reply.body); + return; + } + send(res, 404, { error: "Not found." }); + } catch (error) { + if (!res.headersSent) send(res, 500, { error: error instanceof Error ? error.message : "Internal error." }); + else res.end(); + } + })(); + }); + + return { + server, + store, + listen: (port, host = "127.0.0.1") => + new Promise((resolve, reject) => { + server.once("error", reject); + server.listen(port, host, () => { + server.off("error", reject); + const address = server.address(); + resolve(typeof address === "object" && address ? address.port : port); + }); + }), + close: () => + new Promise((resolve, reject) => { + server.closeAllConnections(); + server.close((error) => (error ? reject(error) : resolve())); + }), + }; +} diff --git a/packages/kv-demo-mcp-server/src/tasks/main.ts b/packages/kv-demo-mcp-server/src/tasks/main.ts new file mode 100644 index 00000000000..d1cdadff5db --- /dev/null +++ b/packages/kv-demo-mcp-server/src/tasks/main.ts @@ -0,0 +1,34 @@ +#!/usr/bin/env node +import { homedir } from "node:os"; +import { join } from "node:path"; +import { createTasksDemoHttpServer } from "./http.js"; +import { DemoTaskStore } from "./store.js"; + +function port(raw: string | undefined): number { + if (!raw) return 8849; + const value = Number.parseInt(raw, 10); + if (!Number.isInteger(value) || value < 0 || value > 65535) throw new Error(`Invalid port: ${raw}`); + return value; +} + +async function main(): Promise { + const env = process.env; + // State lives in a file by default so the server can be stopped and started mid-task. + const stateFile = env.TASKS_DEMO_STATE_FILE === "memory" ? null : env.TASKS_DEMO_STATE_FILE || join(homedir(), ".paperclip-tasks-demo", "state.json"); + const host = env.TASKS_DEMO_HOST?.trim() || "127.0.0.1"; + const token = env.TASKS_DEMO_TOKEN?.trim() || null; + const { listen } = createTasksDemoHttpServer({ store: new DemoTaskStore({ file: stateFile }), token }); + const bound = await listen(port(env.PORT ?? env.TASKS_DEMO_PORT), host); + const base = `http://${host}:${bound}`; + console.error(`MCP Tasks demo server listening on ${base}`); + console.error(` MCP endpoint: ${base}/mcp`); + console.error(` Status page: ${base}/`); + console.error(` JSON state: ${base}/api/state`); + console.error(` Task state: ${stateFile ?? "in memory (lost on restart)"}`); + console.error(` Auth: ${token ? "TASKS_DEMO_TOKEN required (Bearer header)" : "none (set TASKS_DEMO_TOKEN to require one)"}`); +} + +void main().catch((error) => { + console.error("Failed to start the MCP Tasks demo server:", error instanceof Error ? error.message : error); + process.exit(1); +}); diff --git a/packages/kv-demo-mcp-server/src/tasks/render.ts b/packages/kv-demo-mcp-server/src/tasks/render.ts new file mode 100644 index 00000000000..3e509db50ed --- /dev/null +++ b/packages/kv-demo-mcp-server/src/tasks/render.ts @@ -0,0 +1,64 @@ +import type { DemoState } from "./store.js"; + +function escapeHtml(value: string): string { + return value.replace(/&/g, "&").replace(//g, ">").replace(/"/g, """).replace(/'/g, "'"); +} + +function time(ms: number): string { + return new Date(ms).toISOString().slice(11, 19); +} + +/** + * A plain status page: every task, how many times each tool was started, and + * the latest protocol events. It reloads itself every two seconds. + */ +export function renderTasksPage(state: DemoState | null, now: number): string { + const body = state === null + ? `

This server requires a token, so its state is not shown here. Read /api/state with the token instead.

` + : ` +

Tasks

+ + + ${state.tasks.length === 0 + ? `` + : [...state.tasks].reverse().map((task) => ` + + + + + + + `).join("")} +
ToolStatusCreatedChecksTTL leftTask ID
No tasks yet. Ask an agent to call slow_report.
${escapeHtml(task.tool)}${escapeHtml(task.status)}${time(task.createdAt)}${task.polls}${Math.max(0, Math.round((task.createdAt + task.ttlMs - now) / 1000))} s${escapeHtml(task.taskId)}
+

Times each tool was started (tools/call)

+

${Object.entries(state.toolCalls).map(([tool, count]) => `${escapeHtml(tool)}: ${count}`).join(" ยท ") || "none yet"}

+

Latest events

+ + + ${[...state.events].reverse().slice(0, 60).map((event) => ` + + `).join("")} +
TimeEventToolDetail
${time(event.at)}${escapeHtml(event.method)}${escapeHtml(event.tool ?? "")}${escapeHtml(event.detail)}
`; + return ` + + + + + +MCP Tasks demo + + + +

MCP Tasks demo server

+

MCP endpoint: /mcp (protocol 2026-07-28, extension io.modelcontextprotocol/tasks). This page reloads every 2 seconds.

+${body} + +`; +} diff --git a/packages/kv-demo-mcp-server/src/tasks/store.ts b/packages/kv-demo-mcp-server/src/tasks/store.ts new file mode 100644 index 00000000000..9c43c7afbd0 --- /dev/null +++ b/packages/kv-demo-mcp-server/src/tasks/store.ts @@ -0,0 +1,157 @@ +import { randomUUID } from "node:crypto"; +import { lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"; +import { basename, dirname, join } from "node:path"; + +/** Task states from the MCP Tasks extension (2026-07-28). */ +export type DemoTaskStatus = "working" | "input_required" | "completed" | "failed" | "cancelled"; + +export type DemoInputRequest = { method: string; params: Record }; + +export interface DemoTask { + taskId: string; + tool: string; + arguments: Record; + status: DemoTaskStatus; + /** Epoch ms. */ + createdAt: number; + lastUpdatedAt: number; + ttlMs: number; + pollIntervalMs: number; + /** When a `working` task settles on its own (epoch ms). */ + settlesAt: number | null; + /** How a `working` task settles at `settlesAt`. */ + outcome: "complete" | "fail"; + inputRequests?: Record; + /** The person's answer from `tasks/update`, kept for the result. */ + answer?: Record; + result?: Record; + error?: { code: number; message: string }; + /** How many `tasks/get` requests this task has answered. */ + polls: number; +} + +export interface DemoEvent { + at: number; + method: string; + tool?: string; + taskId?: string; + detail: string; +} + +export interface DemoState { + tasks: DemoTask[]; + /** Every `tools/call` received, by tool name. Proves "started exactly once". */ + toolCalls: Record; + events: DemoEvent[]; +} + +const MAX_EVENTS = 200; +const MAX_TASKS = 500; + +/** + * In-memory task state, optionally mirrored to a JSON file so the server can + * be stopped and started again mid-task. A task's progress is derived from the + * clock (`settlesAt`), so a restart never resets or repeats work. + */ +/** + * The state directory must be a real directory owned by this user and not + * writable by anyone else, so no other local user can plant files in it. + */ +function assertPrivateDirectory(dir: string): void { + mkdirSync(dir, { recursive: true, mode: 0o700 }); + const info = lstatSync(dir); + const uid = process.getuid?.(); + if (!info.isDirectory() || (uid !== undefined && info.uid !== uid) || (info.mode & 0o022) !== 0) { + throw new Error(`Task state directory ${dir} must be a directory you own that others cannot write to. Choose another TASKS_DEMO_STATE_FILE.`); + } +} + +export class DemoTaskStore { + private state: DemoState = { tasks: [], toolCalls: {}, events: [] }; + + constructor( + private readonly options: { file?: string | null; now?: () => number } = {}, + ) { + if (options.file) { + assertPrivateDirectory(dirname(options.file)); + this.load(options.file); + } + } + + now(): number { + return this.options.now ? this.options.now() : Date.now(); + } + + private load(file: string): void { + try { + const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial; + this.state = { + tasks: Array.isArray(parsed.tasks) ? parsed.tasks : [], + toolCalls: parsed.toolCalls && typeof parsed.toolCalls === "object" ? parsed.toolCalls : {}, + events: Array.isArray(parsed.events) ? parsed.events : [], + }; + } catch { + // No file yet, or unreadable: start empty. + } + } + + private save(): void { + const file = this.options.file; + if (!file) return; + // A fresh, unguessable temp name, created exclusively: nothing another + // user placed in the directory (such as a symlink) is ever written through. + const temp = join(dirname(file), `.${basename(file)}.${randomUUID()}.tmp`); + writeFileSync(temp, JSON.stringify(this.state, null, 2), { flag: "wx", mode: 0o600 }); + renameSync(temp, file); + } + + log(event: Omit): void { + this.state.events.push({ at: this.now(), ...event }); + if (this.state.events.length > MAX_EVENTS) this.state.events.splice(0, this.state.events.length - MAX_EVENTS); + this.save(); + } + + countToolCall(tool: string): void { + this.state.toolCalls[tool] = (this.state.toolCalls[tool] ?? 0) + 1; + this.save(); + } + + create(input: Omit): DemoTask { + const now = this.now(); + const task: DemoTask = { ...input, taskId: `demo-${randomUUID()}`, createdAt: now, lastUpdatedAt: now, polls: 0 }; + this.state.tasks.push(task); + if (this.state.tasks.length > MAX_TASKS) this.state.tasks.splice(0, this.state.tasks.length - MAX_TASKS); + this.save(); + return task; + } + + /** + * The task as it is now, or null when unknown or past its TTL. An expired + * task is forgotten, as the specification allows. + */ + get(taskId: string): DemoTask | null { + const task = this.state.tasks.find((candidate) => candidate.taskId === taskId); + if (!task) return null; + const now = this.now(); + if (now >= task.createdAt + task.ttlMs) { + this.state.tasks = this.state.tasks.filter((candidate) => candidate !== task); + this.log({ method: "expired", tool: task.tool, taskId, detail: `TTL of ${Math.round(task.ttlMs / 1000)} s passed; task forgotten` }); + return null; + } + return task; + } + + update(task: DemoTask, patch: Partial): DemoTask { + Object.assign(task, patch, { lastUpdatedAt: this.now() }); + this.save(); + return task; + } + + touch(): void { + this.save(); + } + + snapshot(): DemoState { + return structuredClone(this.state); + } +} diff --git a/packages/kv-demo-mcp-server/src/tasks/tools.ts b/packages/kv-demo-mcp-server/src/tasks/tools.ts new file mode 100644 index 00000000000..9f8b126abb8 --- /dev/null +++ b/packages/kv-demo-mcp-server/src/tasks/tools.ts @@ -0,0 +1,207 @@ +import type { DemoTask, DemoTaskStore } from "./store.js"; + +/** + * The demo tools. Each one shows one MCP Tasks behaviour. None of them touch + * anything outside this process: the "work" is the clock running. + */ +export const DEMO_TOOLS = [ + { + name: "slow_report", + description: "Writes a short report after a delay (default 20 seconds). Returns a task right away, then the report when the delay has passed. Shows polling.", + inputSchema: { + type: "object", + properties: { + topic: { type: "string", description: "What the report is about." }, + seconds: { type: "integer", minimum: 1, maximum: 3600, description: "How long the report takes. Default 20." }, + }, + }, + annotations: { readOnlyHint: true, title: "Slow report" }, + }, + { + name: "needs_approval", + description: "Pretends to perform an action that a person must approve first. The task asks a question (approve or reject) and finishes after the person answers. Shows input_required and tasks/update.", + inputSchema: { + type: "object", + properties: { action: { type: "string", description: "The action that needs approval." } }, + }, + annotations: { readOnlyHint: true, title: "Needs approval" }, + }, + { + name: "will_fail", + description: "Starts work that fails after a few seconds (default 5). Shows a failed task.", + inputSchema: { + type: "object", + properties: { seconds: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before it fails. Default 5." } }, + }, + annotations: { readOnlyHint: true, title: "Will fail" }, + }, + { + name: "cancellable", + description: "Starts long work (default 10 minutes) that stops cleanly when cancelled. Shows tasks/cancel.", + inputSchema: { + type: "object", + properties: { seconds: { type: "integer", minimum: 1, maximum: 86400, description: "How long the work runs. Default 600." } }, + }, + annotations: { readOnlyHint: true, title: "Cancellable" }, + }, + { + name: "expires", + description: "Starts work that outlives its own short TTL (default 15 seconds), so the server forgets the task before it finishes. Shows an expired task.", + inputSchema: { + type: "object", + properties: { ttlSeconds: { type: "integer", minimum: 1, maximum: 3600, description: "The task's TTL. Default 15." } }, + }, + annotations: { readOnlyHint: true, title: "Expires" }, + }, + { + name: "quick_echo", + description: "Answers immediately, without a task. Shows that ordinary calls are unchanged.", + inputSchema: { + type: "object", + properties: { text: { type: "string" } }, + }, + annotations: { readOnlyHint: true, title: "Quick echo" }, + }, +] as const; + +export type DemoToolName = (typeof DEMO_TOOLS)[number]["name"]; + +const HOUR_MS = 60 * 60_000; +const POLL_INTERVAL_MS = 2_000; +/** How long `needs_approval` keeps working after the person answers. */ +export const APPROVAL_FOLLOW_UP_MS = 3_000; + +export const APPROVAL_FORM = { + method: "elicitation/create", + params: { + mode: "form", + message: "Approve this demo action?", + requestedSchema: { + type: "object", + properties: { + decision: { type: "string", title: "Decision", enum: ["approve", "reject"] }, + note: { type: "string", title: "Note for the agent (optional)" }, + }, + required: ["decision"], + }, + }, +} as const; + +function intArg(args: Record, key: string, fallback: number, max: number): number { + const value = args[key]; + return typeof value === "number" && Number.isInteger(value) && value >= 1 ? Math.min(value, max) : fallback; +} + +function text(value: string, structured?: Record, isError = false): Record { + return { content: [{ type: "text", text: value }], ...(structured ? { structuredContent: structured } : {}), isError }; +} + +export type ToolCallOutcome = + | { kind: "result"; result: Record } + | { kind: "task"; task: DemoTask }; + +/** + * Run a tool. `tasks` says whether this request declared the Tasks extension; + * a server must never return a task to a request that did not. + */ +export function callDemoTool(store: DemoTaskStore, name: string, args: Record, tasks: boolean): ToolCallOutcome | null { + const now = store.now(); + const base = { tool: name, arguments: args, ttlMs: HOUR_MS, pollIntervalMs: POLL_INTERVAL_MS, outcome: "complete" as const }; + switch (name) { + case "quick_echo": + return { kind: "result", result: text(`echo: ${typeof args.text === "string" ? args.text : ""}`) }; + case "slow_report": { + const seconds = intArg(args, "seconds", 20, 3600); + if (!tasks) return { kind: "result", result: text(`This client does not support MCP Tasks, so the ${seconds}-second report was skipped.`, undefined, true) }; + return { kind: "task", task: store.create({ ...base, status: "working", settlesAt: now + seconds * 1000, ttlMs: seconds * 1000 + HOUR_MS }) }; + } + case "needs_approval": + if (!tasks) return { kind: "result", result: text("This action needs a person's approval, which requires a client that supports MCP Tasks.", undefined, true) }; + return { kind: "task", task: store.create({ ...base, status: "input_required", settlesAt: null, inputRequests: { approval: structuredClone(APPROVAL_FORM) as never } }) }; + case "will_fail": { + const seconds = intArg(args, "seconds", 5, 3600); + if (!tasks) return { kind: "result", result: text("The demo failure needs a client that supports MCP Tasks.", undefined, true) }; + return { kind: "task", task: store.create({ ...base, status: "working", settlesAt: now + seconds * 1000, outcome: "fail", ttlMs: seconds * 1000 + HOUR_MS }) }; + } + case "cancellable": { + const seconds = intArg(args, "seconds", 600, 86400); + if (!tasks) return { kind: "result", result: text("The cancellable demo needs a client that supports MCP Tasks.", undefined, true) }; + return { kind: "task", task: store.create({ ...base, status: "working", settlesAt: now + seconds * 1000, ttlMs: Math.max(HOUR_MS, seconds * 2000) }) }; + } + case "expires": { + const ttlSeconds = intArg(args, "ttlSeconds", 15, 3600); + if (!tasks) return { kind: "result", result: text("The expiry demo needs a client that supports MCP Tasks.", undefined, true) }; + // Works ten times longer than it is kept, so it is always forgotten first. + return { kind: "task", task: store.create({ ...base, status: "working", ttlMs: ttlSeconds * 1000, settlesAt: now + ttlSeconds * 10_000 }) }; + } + default: + return null; + } +} + +/** Settle a `working` task whose time has come. Called on every read. */ +export function advanceDemoTask(store: DemoTaskStore, task: DemoTask): DemoTask { + if (task.status !== "working" || task.settlesAt === null || store.now() < task.settlesAt) return task; + if (task.outcome === "fail") { + store.update(task, { status: "failed", error: { code: -32603, message: "The demo job crashed on purpose (will_fail)." } }); + store.log({ method: "settled", tool: task.tool, taskId: task.taskId, detail: "failed" }); + return task; + } + store.update(task, { status: "completed", result: resultFor(task) }); + store.log({ method: "settled", tool: task.tool, taskId: task.taskId, detail: "completed" }); + return task; +} + +function resultFor(task: DemoTask): Record { + const seconds = Math.round(((task.settlesAt ?? task.createdAt) - task.createdAt) / 1000); + if (task.tool === "needs_approval") { + const note = typeof task.answer?.note === "string" && task.answer.note ? ` Note: ${task.answer.note}` : ""; + const action = typeof task.arguments.action === "string" ? task.arguments.action : "the demo action"; + return text(`Approved: ${action} was carried out.${note}`, { approved: true, action, note: task.answer?.note ?? null }); + } + if (task.tool === "slow_report") { + const topic = typeof task.arguments.topic === "string" && task.arguments.topic ? task.arguments.topic : "nothing in particular"; + return text(`Report on ${topic}: finished after ${seconds} seconds and ${task.polls} status checks.`, { topic, seconds }); + } + return text(`${task.tool} finished after ${seconds} seconds.`, { seconds }); +} + +/** A human-readable progress line for `statusMessage`. */ +export function statusMessageFor(store: DemoTaskStore, task: DemoTask): string | undefined { + if (task.status === "input_required") return "Waiting for a person to approve or reject."; + if (task.status !== "working" || task.settlesAt === null) return undefined; + const total = Math.max(1, task.settlesAt - task.createdAt); + const done = Math.min(total, Math.max(0, store.now() - task.createdAt)); + return `${Math.floor((done / total) * 100)}% done (${Math.round(done / 1000)} of ${Math.round(total / 1000)} s)`; +} + +/** + * Apply a person's answer from `tasks/update`. Answers the task is not + * waiting for are ignored, as the specification requires. + */ +export function answerDemoTask(store: DemoTaskStore, task: DemoTask, inputResponses: Record): void { + if (task.status !== "input_required" || !task.inputRequests) return; + const key = Object.keys(task.inputRequests)[0]; + const response = key ? inputResponses[key] as { action?: unknown; content?: Record } | undefined : undefined; + if (!response || typeof response !== "object") return; + const content = response.content && typeof response.content === "object" ? response.content : {}; + if (response.action !== "accept" || content.decision === "reject") { + store.update(task, { + status: "completed", + inputRequests: undefined, + answer: content, + result: text("Rejected: nothing was done.", { approved: false }), + }); + store.log({ method: "answered", tool: task.tool, taskId: task.taskId, detail: `rejected (${String(response.action)})` }); + return; + } + if (content.decision !== "approve") { + // Ask again under a new key: a client treats an answered key as done. + const attempt = Number(/^approval-(\d+)$/.exec(key!)?.[1] ?? 1) + 1; + store.update(task, { inputRequests: { [`approval-${attempt}`]: { ...structuredClone(APPROVAL_FORM), params: { ...structuredClone(APPROVAL_FORM.params), message: "Please choose approve or reject." } } as never } }); + store.log({ method: "answered", tool: task.tool, taskId: task.taskId, detail: "invalid answer; asked again" }); + return; + } + store.update(task, { status: "working", inputRequests: undefined, answer: content, settlesAt: store.now() + APPROVAL_FOLLOW_UP_MS }); + store.log({ method: "answered", tool: task.tool, taskId: task.taskId, detail: "approved" }); +} diff --git a/server/src/__tests__/mcp-tasks-demo-server.test.ts b/server/src/__tests__/mcp-tasks-demo-server.test.ts new file mode 100644 index 00000000000..48cdc91519e --- /dev/null +++ b/server/src/__tests__/mcp-tasks-demo-server.test.ts @@ -0,0 +1,197 @@ +import { randomUUID } from "node:crypto"; +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; +import { + agents, + companies, + companyMemberships, + createDb, + heartbeatRuns, + issueThreadInteractions, + issues, + projects, + toolMcpTasks, +} from "@paperclipai/db"; +import { and, eq, lte, ne } from "drizzle-orm"; +import { forgetMcpHttpSessions } from "../services/mcp-http.js"; +import { createToolGatewayService } from "../services/tool-gateway.js"; +import { toolAccessService } from "../services/tool-access.js"; +import { instanceSettingsService } from "../services/instance-settings.js"; +import { adapterExecutionControls, createAdapterExecutionControl } from "../services/adapter-execution-control.js"; +import { + createTasksDemoHttpServer, + DemoTaskStore, + type TasksDemoHttpServer, +} from "../../../packages/kv-demo-mcp-server/src/index.js"; +import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js"; + +/** + * MCP Tasks end to end against the real demo server + * (`packages/kv-demo-mcp-server/src/tasks`) over HTTP. The demo's clock is + * moved by hand, so a "30-second" job finishes the moment the test says so. + */ +const support = await getEmbeddedPostgresTestSupport(); +(support.supported ? describe : describe.skip)("MCP Tasks with the demo server", () => { + const actor = { actorType: "user" as const, actorId: "mcp-tasks-demo-user", actorSource: "local_implicit" as const }; + let fixture: Awaited>; + let db: ReturnType; + let keyDir: string; + let demo: TasksDemoHttpServer; + let demoUrl: string; + let clock = Date.now(); + + beforeAll(async () => { + keyDir = await mkdtemp(join(tmpdir(), "mcp-tasks-demo-secrets-")); + vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(keyDir, "key")); + fixture = await startEmbeddedPostgresTestDatabase("mcp-tasks-demo-"); + db = createDb(fixture.connectionString); + await instanceSettingsService(db).updateExperimental({ enableMcpTasks: true }); + demo = createTasksDemoHttpServer({ store: new DemoTaskStore({ now: () => clock }) }); + demoUrl = `http://127.0.0.1:${await demo.listen(0)}/mcp`; + }, 30_000); + afterAll(async () => { + await demo?.close(); + await fixture?.cleanup(); + vi.unstubAllEnvs(); + if (keyDir) await rm(keyDir, { recursive: true, force: true }); + }); + + const starts = (tool: string) => demo.store.snapshot().toolCalls[tool] ?? 0; + const demoTask = (tool: string) => demo.store.snapshot().tasks.filter((task) => task.tool === tool).at(-1); + const polled = (tool: string) => demoTask(tool)?.polls ?? 0; + + async function setup() { + const [org] = await db.insert(companies).values({ name: `Demo ${randomUUID()}`, issuePrefix: `D${randomUUID().slice(0, 5)}` }).returning(); + await db.insert(companyMemberships).values({ companyId: org.id, principalType: "user", principalId: actor.actorId, status: "active", membershipRole: "admin" }); + const [agent] = await db.insert(agents).values({ companyId: org.id, name: "Demo agent", role: "engineer", adapterType: "process", adapterConfig: {}, runtimeConfig: {} }).returning(); + const [project] = await db.insert(projects).values({ companyId: org.id, name: "Demo project" }).returning(); + const [issue] = await db.insert(issues).values({ companyId: org.id, projectId: project.id, title: "Try the demo", status: "in_progress", assigneeAgentId: agent.id }).returning(); + const [run] = await db.insert(heartbeatRuns).values({ companyId: org.id, agentId: agent.id, invocationSource: "assignment", status: "running", contextSnapshot: { issueId: issue.id, projectId: project.id } }).returning(); + // A public-looking link, forwarded to the local demo server. + const options = { deploymentMode: "local_trusted" as const, deploymentExposure: "private" as const, + remoteHttpEndpointLookup: async () => [{ address: "8.8.8.8", family: 4 as const }], + remoteHttpRequest: (_url: string, init: RequestInit) => fetch(demoUrl, init) }; + const service = toolAccessService(db, options); + const connected = await service.connectGalleryApp(org.id, { link: `https://tasks-demo-${randomUUID().slice(0, 8)}.example.com/mcp`, name: "Tasks demo" }, actor); + await service.finishGalleryAppConnection(org.id, connected.connectionId, { + enabledCatalogEntryIds: connected.catalog.map((entry) => entry.id), askFirstCatalogEntryIds: [], access: "all_agents", + }, actor); + const gatewayOptions = { ...options, toolActionSigningSecret: "tasks-demo-signing-key" }; + let gateway = createToolGatewayService(db, gatewayOptions); + const session = await gateway.createSession({ companyId: org.id, agentId: agent.id, runId: run.id }); + const names = (await gateway.listToolsForSession(session.token)).map((tool) => tool.name); + const toolName = (name: string) => names.find((candidate) => candidate.endsWith(`:${name.replace(/_/g, "-")}`))!; + const call = (name: string, parameters: Record = {}, timeoutMs = 10_000, sessionToken = session.token) => + gateway.executeTool({ sessionToken, tool: toolName(name), parameters, timeoutMs }); + const rows = () => db.select().from(toolMcpTasks).where(eq(toolMcpTasks.companyId, org.id)); + return { + org, agent, issue, run, call, rows, names, + gateway: () => gateway, + restart: () => { forgetMcpHttpSessions(connected.connectionId); gateway = createToolGatewayService(db, gatewayOptions); return gateway; }, + /** Background poll for this company only. */ + poll: async (wake: (input: unknown) => Promise) => { + await db.update(toolMcpTasks).set({ nextPollAt: new Date(Date.now() + 60 * 60_000) }) + .where(and(ne(toolMcpTasks.companyId, org.id), lte(toolMcpTasks.nextPollAt, new Date()))); + return gateway.pollDueMcpTasks({ wake }); + }, + }; + } + + it("lists every demo tool", async () => { + const { names } = await setup(); + expect(names.map((name) => name.split(":")[1]).sort()).toEqual(["cancellable", "expires", "needs-approval", "quick-echo", "slow-report", "will-fail"]); + }); + + it("slow_report: polls the task and returns the report like a direct result", async () => { + const { call, rows } = await setup(); + const before = starts("slow_report"); + const pending = call("slow_report", { topic: "uptime", seconds: 30 }); + await vi.waitFor(() => expect(polled("slow_report")).toBeGreaterThan(0), { timeout: 5_000 }); + clock += 30_000; + const result = await pending; + expect(result).toMatchObject({ status: "completed", result: { content: expect.stringContaining("Report on uptime"), data: { structuredContent: { topic: "uptime", seconds: 30 } } } }); + expect(starts("slow_report") - before).toBe(1); + expect((await rows())[0]).toMatchObject({ status: "completed" }); + }); + + it("slow_report: outlives the timeout and a Paperclip restart, then is delivered once without starting again", async () => { + const ctx = await setup(); + const before = starts("slow_report"); + await expect(ctx.call("slow_report", { topic: "restart", seconds: 60 }, 400)).rejects.toMatchObject({ reasonCode: "provider_task_pending" }); + const fresh = ctx.restart(); + await db.update(heartbeatRuns).set({ status: "failed" }).where(eq(heartbeatRuns.id, ctx.run.id)); + const [row] = await ctx.rows(); + await db.update(toolMcpTasks).set({ nextPollAt: new Date(Date.now() - 1_000), leaseExpiresAt: null, leaseOwner: null }).where(eq(toolMcpTasks.id, row!.id)); + clock += 60_000; + const wake = vi.fn(async () => undefined); + await ctx.poll(wake); + expect(wake).toHaveBeenCalledTimes(1); + const [recovered] = await db.insert(heartbeatRuns).values({ companyId: ctx.org.id, agentId: ctx.agent.id, invocationSource: "assignment", status: "running", contextSnapshot: { issueId: ctx.issue.id } }).returning(); + const session = await fresh.createSession({ companyId: ctx.org.id, agentId: ctx.agent.id, runId: recovered!.id }); + expect(await ctx.call("slow_report", { topic: "restart", seconds: 60 }, 5_000, session.token)) + .toMatchObject({ status: "completed", result: { content: expect.stringContaining("Report on restart") } }); + expect(starts("slow_report") - before).toBe(1); + // Asking again is new work: the first result was delivered exactly once. + const [delivered] = await ctx.rows(); + expect(delivered!.deliveredAt).toBeInstanceOf(Date); + }); + + it("needs_approval: the question becomes a card, and the person's choice is sent with tasks/update", async () => { + const { call, org, issue } = await setup(); + const first = await call("needs_approval", { action: "rotate the demo key" }).catch((error) => error); + expect(first).toMatchObject({ reasonCode: "elicitation_required" }); + const [card] = await db.select().from(issueThreadInteractions).where(and(eq(issueThreadInteractions.companyId, org.id), eq(issueThreadInteractions.issueId, issue.id))); + expect(card).toMatchObject({ kind: "ask_user_questions", status: "pending" }); + await db.update(issueThreadInteractions).set({ status: "answered", result: { version: 1, answers: [ + { questionId: "decision", optionIds: ["approve"] }, + { questionId: "note", optionIds: [], otherText: "go ahead" }, + ] } }).where(eq(issueThreadInteractions.id, card!.id)); + const pending = call("needs_approval", { action: "rotate the demo key" }); + await vi.waitFor(() => expect(demoTask("needs_approval")?.status).toBe("working"), { timeout: 5_000 }); + clock += 3_000; + expect(await pending).toMatchObject({ status: "completed", result: { content: "Approved: rotate the demo key was carried out. Note: go ahead" } }); + }); + + it("will_fail: becomes a tool error with the app's message", async () => { + const { call } = await setup(); + const pending = call("will_fail", { seconds: 5 }).catch((error) => error); + await vi.waitFor(() => expect(polled("will_fail")).toBeGreaterThan(0), { timeout: 5_000 }); + clock += 5_000; + const failure = await pending; + expect(failure).toMatchObject({ reasonCode: "provider_task_failed" }); + expect(failure.message).toContain("crashed on purpose"); + }); + + it("cancellable: stopping the run cancels the task in the app", async () => { + const { call, run, rows } = await setup(); + const control = createAdapterExecutionControl(); + adapterExecutionControls.set(run.id, control); + try { + const pending = call("cancellable").catch((error) => error); + await vi.waitFor(() => expect(polled("cancellable")).toBeGreaterThan(0), { timeout: 5_000 }); + control.controller.abort(); + expect(await pending).toMatchObject({ reasonCode: "provider_task_cancelled" }); + } finally { + adapterExecutionControls.delete(run.id); + } + expect(demoTask("cancellable")?.status).toBe("cancelled"); + expect((await rows())[0]).toMatchObject({ status: "cancelled", errorCode: "run_cancelled" }); + }); + + it("expires: a task the app forgets ends with a clear error, never a hang", async () => { + const { call, rows } = await setup(); + const pending = call("expires", { ttlSeconds: 15 }).catch((error) => error); + await vi.waitFor(() => expect(polled("expires")).toBeGreaterThan(0), { timeout: 5_000 }); + clock += 15_000; + expect(await pending).toMatchObject({ reasonCode: "provider_task_expired" }); + expect((await rows())[0]).toMatchObject({ status: "expired" }); + }); + + it("quick_echo: an ordinary call stays synchronous", async () => { + const { call, rows } = await setup(); + expect(await call("quick_echo", { text: "hi" })).toMatchObject({ status: "completed", result: { content: "echo: hi" } }); + expect(await rows()).toEqual([]); + }); +}); diff --git a/server/src/__tests__/tool-gateway-agent-errors.test.ts b/server/src/__tests__/tool-gateway-agent-errors.test.ts new file mode 100644 index 00000000000..9fa066e5fe3 --- /dev/null +++ b/server/src/__tests__/tool-gateway-agent-errors.test.ts @@ -0,0 +1,51 @@ +import express from "express"; +import request from "supertest"; +import { describe, expect, it } from "vitest"; +import type { Db } from "@paperclipai/db"; +import { mcpGatewayProtocolRoutes, toolGatewayRoutes } from "../routes/tool-gateway.js"; +import { ToolGatewayHttpError, type ToolGatewayService } from "../services/tool-gateway.js"; + +/** + * A tool error carries the call's execution record (request IDs, timings, and + * the server-side stack of the error) so the audit can store it. Agents get + * the message and reason, never that record: they paste errors into task + * comments, where a person would read Paperclip's internals. + */ +function failingGateway() { + const error = new ToolGatewayHttpError(410, + "The app no longer has this action's result: it expired or was removed. Run the action again to start it over.", + "provider_task_expired", + { + connectionId: "connection-1", + execution: { + transport: "mcp_remote", + request: { requestId: "paperclip-tool-123" }, + error: { name: "Error", message: "expired", code: null, stack: "Error: expired\n at mcpTaskExpiredError (/srv/paperclip/server/src/services/tool-gateway.ts:6823:12)", cause: null }, + }, + }); + return { executeTool: async () => { throw error; } } as unknown as ToolGatewayService; +} + +describe("tool errors returned to agents", () => { + it("leave out the execution record on the MCP gateway", async () => { + const app = express().use(express.json()).use(mcpGatewayProtocolRoutes(failingGateway())); + const response = await request(app).post("/mcp/gateways/gateway-1").set("Authorization", "Bearer token") + .send({ jsonrpc: "2.0", id: 7, method: "tools/call", params: { name: "mcp.demo:expires", arguments: {} } }); + expect(response.body.error).toMatchObject({ + message: expect.stringContaining("Run the action again"), + data: { reasonCode: "provider_task_expired", connectionId: "connection-1" }, + }); + expect(response.body.error.data).not.toHaveProperty("execution"); + expect(JSON.stringify(response.body)).not.toContain("tool-gateway.ts"); + }); + + it("leave out the execution record on the session tool call route", async () => { + const app = express().use(express.json()).use(toolGatewayRoutes({} as Db, failingGateway())); + const response = await request(app).post("/tool-gateway/tools/call").set("x-paperclip-tool-gateway-token", "token") + .send({ tool: "mcp.demo:expires", parameters: {} }); + expect(response.status).toBe(410); + expect(response.body).toMatchObject({ reasonCode: "provider_task_expired", connectionId: "connection-1" }); + expect(response.body).not.toHaveProperty("execution"); + expect(JSON.stringify(response.body)).not.toContain("tool-gateway.ts"); + }); +}); diff --git a/server/src/routes/tool-gateway.ts b/server/src/routes/tool-gateway.ts index b73c834dbd4..4837ad62bfd 100644 --- a/server/src/routes/tool-gateway.ts +++ b/server/src/routes/tool-gateway.ts @@ -56,6 +56,16 @@ function callerHeaders(req: { headers: Record): Record { + const { execution: _auditOnly, ...rest } = details; + return rest; +} + async function cancellableRequest(req: Request, res: Response, work: (signal: AbortSignal) => Promise) { const controller = new AbortController(); const aborted = () => controller.abort(); @@ -244,7 +254,7 @@ async function handleMcpGatewayProtocol( res.status(err.status).json({ jsonrpc: "2.0", id, - error: { code: err.status >= 500 ? -32603 : -32000, message: err.message, data: { reasonCode: err.reasonCode, ...err.details } }, + error: { code: err.status >= 500 ? -32603 : -32000, message: err.message, data: { reasonCode: err.reasonCode, ...callerErrorDetails(err.details) } }, }); return; } @@ -340,7 +350,7 @@ function sendGatewayError(res: import("express").Response, err: unknown) { res.status(err.status).json({ error: err.message, reasonCode: err.reasonCode, - ...err.details, + ...callerErrorDetails(err.details), }); return; }