mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
feat(mcp-tasks): add a demo MCP server that uses Tasks, test against it, and keep audit records out of agent errors (#21464)
## 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 <noreply@anthropic.com>
This commit is contained in:
1 parent
1f388ed385
commit
81d06cfc97
13 files changed
+1375
-4
No files matched your search
@@ -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-<id>-<hash>: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`.
|
||||
@@ -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 <token>`. |
|
||||
|
||||
See "Try it yourself" in [MCP-TASKS.md](../../doc/connections/MCP-TASKS.md) for
|
||||
the full walkthrough with Paperclip.
|
||||
@@ -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": {
|
||||
".": {
|
||||
|
||||
@@ -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";
|
||||
@@ -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<string, unknown> = {}, 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<string, any>; error?: { code: number; message: string; data?: any } } };
|
||||
}
|
||||
|
||||
const call = (url: string, name: string, args: Record<string, unknown> = {}, 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");
|
||||
});
|
||||
});
|
||||
@@ -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<number>;
|
||||
close: () => Promise<void>;
|
||||
}
|
||||
|
||||
type RpcRequest = { jsonrpc?: string; id?: string | number | null; method?: unknown; params?: Record<string, unknown> };
|
||||
type Reply = { status: number; body: unknown } | null;
|
||||
|
||||
function record(value: unknown): Record<string, unknown> | null {
|
||||
return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
|
||||
}
|
||||
|
||||
function ok(id: unknown, result: Record<string, unknown>): 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<string, unknown> {
|
||||
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<string> {
|
||||
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<number>((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<void>((resolve, reject) => {
|
||||
server.closeAllConnections();
|
||||
server.close((error) => (error ? reject(error) : resolve()));
|
||||
}),
|
||||
};
|
||||
}
|
||||
@@ -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<void> {
|
||||
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);
|
||||
});
|
||||
@@ -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, """).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
|
||||
? `<p>This server requires a token, so its state is not shown here. Read <code>/api/state</code> with the token instead.</p>`
|
||||
: `
|
||||
<h2>Tasks</h2>
|
||||
<table>
|
||||
<thead><tr><th>Tool</th><th>Status</th><th>Created</th><th>Checks</th><th>TTL left</th><th>Task ID</th></tr></thead>
|
||||
<tbody>${state.tasks.length === 0
|
||||
? `<tr><td colspan="6">No tasks yet. Ask an agent to call <code>slow_report</code>.</td></tr>`
|
||||
: [...state.tasks].reverse().map((task) => `<tr>
|
||||
<td>${escapeHtml(task.tool)}</td>
|
||||
<td class="status ${escapeHtml(task.status)}">${escapeHtml(task.status)}</td>
|
||||
<td>${time(task.createdAt)}</td>
|
||||
<td>${task.polls}</td>
|
||||
<td>${Math.max(0, Math.round((task.createdAt + task.ttlMs - now) / 1000))} s</td>
|
||||
<td><code>${escapeHtml(task.taskId)}</code></td>
|
||||
</tr>`).join("")}</tbody>
|
||||
</table>
|
||||
<h2>Times each tool was started (<code>tools/call</code>)</h2>
|
||||
<p>${Object.entries(state.toolCalls).map(([tool, count]) => `<code>${escapeHtml(tool)}</code>: ${count}`).join(" · ") || "none yet"}</p>
|
||||
<h2>Latest events</h2>
|
||||
<table>
|
||||
<thead><tr><th>Time</th><th>Event</th><th>Tool</th><th>Detail</th></tr></thead>
|
||||
<tbody>${[...state.events].reverse().slice(0, 60).map((event) => `<tr>
|
||||
<td>${time(event.at)}</td><td><code>${escapeHtml(event.method)}</code></td><td>${escapeHtml(event.tool ?? "")}</td><td>${escapeHtml(event.detail)}</td>
|
||||
</tr>`).join("")}</tbody>
|
||||
</table>`;
|
||||
return `<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta http-equiv="refresh" content="2">
|
||||
<title>MCP Tasks demo</title>
|
||||
<style>
|
||||
body { font: 14px/1.4 system-ui, sans-serif; margin: 24px; color: #1a1a1a; background: #fff; }
|
||||
table { border-collapse: collapse; width: 100%; margin-bottom: 16px; }
|
||||
th, td { text-align: left; padding: 4px 8px; border-bottom: 1px solid #e5e5e5; }
|
||||
.status.completed { color: #15803d; } .status.failed { color: #b91c1c; }
|
||||
.status.cancelled { color: #6b7280; } .status.input_required { color: #b45309; }
|
||||
@media (prefers-color-scheme: dark) { body { color: #eee; background: #111; } th, td { border-color: #333; } }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>MCP Tasks demo server</h1>
|
||||
<p>MCP endpoint: <code>/mcp</code> (protocol 2026-07-28, extension <code>io.modelcontextprotocol/tasks</code>). This page reloads every 2 seconds.</p>
|
||||
${body}
|
||||
</body>
|
||||
</html>`;
|
||||
}
|
||||
@@ -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<string, unknown> };
|
||||
|
||||
export interface DemoTask {
|
||||
taskId: string;
|
||||
tool: string;
|
||||
arguments: Record<string, unknown>;
|
||||
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<string, DemoInputRequest>;
|
||||
/** The person's answer from `tasks/update`, kept for the result. */
|
||||
answer?: Record<string, unknown>;
|
||||
result?: Record<string, unknown>;
|
||||
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<string, number>;
|
||||
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<DemoState>;
|
||||
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<DemoEvent, "at">): 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, "taskId" | "createdAt" | "lastUpdatedAt" | "polls">): 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>): DemoTask {
|
||||
Object.assign(task, patch, { lastUpdatedAt: this.now() });
|
||||
this.save();
|
||||
return task;
|
||||
}
|
||||
|
||||
touch(): void {
|
||||
this.save();
|
||||
}
|
||||
|
||||
snapshot(): DemoState {
|
||||
return structuredClone(this.state);
|
||||
}
|
||||
}
|
||||
@@ -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<string, unknown>, 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<string, unknown>, isError = false): Record<string, unknown> {
|
||||
return { content: [{ type: "text", text: value }], ...(structured ? { structuredContent: structured } : {}), isError };
|
||||
}
|
||||
|
||||
export type ToolCallOutcome =
|
||||
| { kind: "result"; result: Record<string, unknown> }
|
||||
| { 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<string, unknown>, 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<string, unknown> {
|
||||
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<string, unknown>): 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<string, unknown> } | 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" });
|
||||
}
|
||||
@@ -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<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
||||
let db: ReturnType<typeof createDb>;
|
||||
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<string, unknown> = {}, 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<void>) => {
|
||||
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([]);
|
||||
});
|
||||
});
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -56,6 +56,16 @@ function callerHeaders(req: { headers: Record<string, string | string[] | undefi
|
||||
return headers;
|
||||
}
|
||||
|
||||
/**
|
||||
* Error details an HTTP caller may see. `execution` is the call's audit record
|
||||
* (request IDs, timings, the server-side stack of an error); the audit keeps
|
||||
* it, and callers never need it. Agents paste errors into task comments.
|
||||
*/
|
||||
function callerErrorDetails(details: Record<string, unknown>): Record<string, unknown> {
|
||||
const { execution: _auditOnly, ...rest } = details;
|
||||
return rest;
|
||||
}
|
||||
|
||||
async function cancellableRequest<T>(req: Request, res: Response, work: (signal: AbortSignal) => Promise<T>) {
|
||||
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;
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user