mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
feat(mcp): ask an app's form questions in the task chat and send the answer back (MCP elicitation) (#21466)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents use connected MCP apps through the tool gateway. > - An MCP app can ask the person a question in the middle of a tool call (MCP elicitation). There are two kinds: a form, or a link to open. > - Today a form question is a dead end: > - A 2026-07-28 server's form `input_required` stops with "needs information Paperclip can't collect yet". > - An older server's `elicitation/create` makes a card, but the answer is never sent back, and the server waits on an open stream. > - Paperclip does not declare form support, so compliant servers never ask. > - This pull request shows the question as a card in the task chat. The card names the app, and only a person can answer it. When the person answers, the agent wakes. The agent's repeated call sends the answer to the app exactly once, for both protocol eras. > - The benefit: apps that need a choice or a detail from the person now finish their work. Restarts lose nothing, and no call is left waiting. ## Linked Issues or Issue Description Refs #21140 (stateless MCP client; this PR closes its "form elicitation" follow-up). Refs #21263 (MCP Tasks; this PR shares its card code). Refs #21389 (MCP Tasks follow-ups: the card answer validation item). **Is your feature request related to a problem?** When a connected MCP app asks the person a form question during a tool call, the call stops and cannot continue. A 2026-07-28 server gets a "needs input" error. An older server gets a card whose answer never reaches it. **Describe the solution you'd like** Show the question in the task chat. Let a person answer, skip, or leave it. Wake the agent when the question is resolved. Send the answer on the agent's repeated call, once, with the server's exact state. **Describe alternatives you've considered** Holding the tool call open until the person answers. We rejected this: it holds a stream and a run slot, and it does not survive deploys or restarts. The plan (`doc/plans/2026-11-13-mcp-elicitation.md`) records nine design decisions with their alternatives. ## What Changed - **Plan:** `doc/plans/2026-11-13-mcp-elicitation.md` covers the spec, the inventory, the decisions, the journey, tests, and risks. - **New module `server/src/services/mcp-elicitation.ts`.** It is the single mapping for direct calls and MCP Tasks: - It turns each spec form field into a real card field: text with defaults, number, yes/no, single choice (`enum` and `oneOf`), and multiple choice (`items.enum` and `items.anyOf`). - It turns card answers back into typed `content`. - Answered sends `accept`. Skip sends `decline`. Withdrawn, closed, or expired sends `cancel`. - It refuses forms that ask for passwords, keys, tokens, card numbers, or one-time codes. - It keeps app text plain, so links in it are not clickable. - It seals `requestState` with AES-256-GCM, bound to the company and connection. - **New table `tool_mcp_elicitations`** (migration 0479). It is company-scoped, with one row per question round. It holds a keyed call identity, the sealed state, the questions and their cards, a claim time, and a 24-hour expiry. - **Gateway, stateless servers:** - Paperclip declares `elicitation: {form, url}` on task tool calls. - A form-only `input_required` saves the round, makes the cards, and stops with a wait message. - A repeated call before the person answers stops again without contacting the app. - After the answer, the repeated call claims the round and sends `inputResponses` and the exact `requestState`, once. - A failed send releases the claim. A crash mid-send lets the claim lapse. - **Gateway, older servers:** - Paperclip declares form support at `initialize`. - The first question gets `cancel` at once, so the server never waits. - When the same question (same words and schema) arrives on the repeated call, Paperclip answers it from the card. - **Gateway, mixed rounds and retries:** - A form beside a URL step shows the link first. - A repeated call that stopped for a question runs again in the same run. It is no longer replayed by the per-run idempotency key. - **Cards:** the title is "*App* needs your input". The resolver policy is `human_only`. "Send to *App*" sends the answer. A user comment does not supersede the card. - **Activity log:** new events `tool_gateway.elicitation_sent`, `tool_gateway.elicitation_refused`, and `tool_gateway.elicitation_expired`. They record the action only, never the values. - **MCP Tasks:** task cards use the same mapping and gain the app name, real fields, and `human_only`. A secret or an unsupported form stays unsupported. - **Storybook:** `Tasks and conversations/Questions and approvals/MCP App Questions` has five states: Asking, Answered, Skipped, Expired, and TwoQuestions. The fixtures are generated from the server mapper's output. - **Docs:** `doc/connections/MCP-ELICITATION.md` (linked from the README) is new. `MCP-PROTOCOL-VERSIONS.md` and `MCP-TASKS.md` are updated. ## Verification - `server/src/__tests__/mcp-elicitation.test.ts` has 16 tests. They pass on the branch. - **Red/green:** 9 of the 9 gateway tests fail with master's `tool-gateway.ts` and `mcp-http.ts`. The 7 pure unit tests cover the new module. - The tests use a fake 2026-07-28 server and a fake 2025-06-18 server that asks over the open stream and waits for the reply. - Covered: answer, skip (`decline`), withdraw (`cancel`), two questions at once, a restart while waiting, a crash mid-send, another company with the same app and arguments, expiry, a refused password field, an agent that tries to answer (rejected), and capabilities. - Existing suites: `mcp-tasks`, `mcp-protocol-versions`, `tool-gateway-service`, `tool-gateway`, and `remote-mcp-connectors`. See the results comment below. - Storybook: the five stories render in headless Chromium, and the play tests pass. The only console errors are the 404s from the backend-less API calls that every story makes. - `tsc --noEmit` is clean for `server` and `ui`. `node scripts/storybook-catalog.mjs` passes. ## Risks - **Older servers may start asking questions.** Declaring form support at `initialize` can make older servers ask where they did not before. Mitigation: the first question always gets `cancel` at once, so no call hangs, and the agent gets a clear next step. - **Per-call cost.** Each 2026-07-28 HTTP tool call in a task makes one indexed lookup for a waiting round. Nothing is added before the first token or to agent boot. - **Migration.** One additive table with no backfill, so it is safe to apply online. - **Changed Tasks behavior.** A task card that is withdrawn or closed now sends `cancel` instead of `decline`, as the spec defines. A skipped card still sends `decline`. - **Stale cards.** Expiry is checked only when the agent calls again. A card can sit past 24 hours until the next call. Then it is withdrawn and the app asks again. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code with tool use (shell, file edits, headless browser), with extended reasoning. ## 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
4879a146fb
commit
a4c570aede
20 files changed
+3030
-218
No files matched your search
@@ -0,0 +1,218 @@
|
||||
import { questionSetToAskUserQuestionsPayload, type AskUserQuestionsInteraction, type PaperclipQuestionSetPayload } from "@paperclipai/shared";
|
||||
import { issueThreadInteractionFixtureMeta } from "./issueThreadInteractionFixtures";
|
||||
|
||||
/*
|
||||
* Question cards an MCP app's form question becomes (MCP elicitation). The
|
||||
* question sets are the exact output of the server's mapper
|
||||
* (server/src/services/mcp-elicitation.ts, buildElicitationQuestionSet) for
|
||||
* the schemas in doc/connections/MCP-ELICITATION.md, so these stories show
|
||||
* the card people really see.
|
||||
*/
|
||||
|
||||
/** Every spec field type: text with a default, titled single select, multi select, yes/no, integer. */
|
||||
export const mcpTicketQuestionSet: PaperclipQuestionSetPayload = {
|
||||
"schema": "paperclip.question_set.v1",
|
||||
"title": "Linear needs your input",
|
||||
"description": "Linear needs a few details to file this ticket.",
|
||||
"submitLabel": "Send to Linear",
|
||||
"questions": [
|
||||
{
|
||||
"id": "title",
|
||||
"prompt": "Ticket title",
|
||||
"required": true,
|
||||
"answerMode": "text",
|
||||
"initialText": "Login button does nothing",
|
||||
"textValidation": {
|
||||
"minLength": 3,
|
||||
"maxLength": 80
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "priority",
|
||||
"prompt": "Priority",
|
||||
"required": true,
|
||||
"answerMode": "single_select",
|
||||
"options": [
|
||||
{
|
||||
"id": "choice_1",
|
||||
"label": "Urgent"
|
||||
},
|
||||
{
|
||||
"id": "choice_2",
|
||||
"label": "Normal",
|
||||
"recommended": true
|
||||
},
|
||||
{
|
||||
"id": "choice_3",
|
||||
"label": "Later"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "labels",
|
||||
"prompt": "Labels",
|
||||
"required": false,
|
||||
"helpText": "Choose at most 2.",
|
||||
"answerMode": "multi_select",
|
||||
"options": [
|
||||
{
|
||||
"id": "choice_1",
|
||||
"label": "Bug",
|
||||
"recommended": true
|
||||
},
|
||||
{
|
||||
"id": "choice_2",
|
||||
"label": "Design"
|
||||
},
|
||||
{
|
||||
"id": "choice_3",
|
||||
"label": "Speed"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "page",
|
||||
"prompt": "Page the on-call engineer?",
|
||||
"required": false,
|
||||
"answerMode": "single_select",
|
||||
"options": [
|
||||
{
|
||||
"id": "choice_1",
|
||||
"label": "Yes"
|
||||
},
|
||||
{
|
||||
"id": "choice_2",
|
||||
"label": "No",
|
||||
"recommended": true
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "estimate",
|
||||
"prompt": "Estimate (points)",
|
||||
"required": false,
|
||||
"answerMode": "text",
|
||||
"textValidation": {
|
||||
"inputType": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 8
|
||||
}
|
||||
}
|
||||
]
|
||||
};
|
||||
|
||||
/** A plain single-choice question. */
|
||||
export const mcpTeamQuestionSet: PaperclipQuestionSetPayload = {
|
||||
"schema": "paperclip.question_set.v1",
|
||||
"title": "Linear needs your input",
|
||||
"description": "Which team should own this?",
|
||||
"submitLabel": "Send to Linear",
|
||||
"questions": [
|
||||
{
|
||||
"id": "team",
|
||||
"prompt": "Team",
|
||||
"required": true,
|
||||
"answerMode": "single_select",
|
||||
"options": [
|
||||
{
|
||||
"id": "choice_1",
|
||||
"label": "Platform"
|
||||
},
|
||||
{
|
||||
"id": "choice_2",
|
||||
"label": "Growth"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
|
||||
/** A form with no fields: the app asks to go ahead. */
|
||||
export const mcpConfirmQuestionSet: PaperclipQuestionSetPayload = {
|
||||
"schema": "paperclip.question_set.v1",
|
||||
"title": "Linear needs your input",
|
||||
"description": "Create the ticket now?",
|
||||
"submitLabel": "Send to Linear",
|
||||
"questions": [
|
||||
{
|
||||
"id": "continue",
|
||||
"prompt": "Create the ticket now?",
|
||||
"required": true,
|
||||
"answerMode": "single_select",
|
||||
"options": [
|
||||
{
|
||||
"id": "continue",
|
||||
"label": "Continue"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
|
||||
function mcpQuestionCard(id: string, questionSet: PaperclipQuestionSetPayload, overrides: Partial<AskUserQuestionsInteraction> = {}): AskUserQuestionsInteraction {
|
||||
return {
|
||||
id,
|
||||
companyId: issueThreadInteractionFixtureMeta.companyId,
|
||||
issueId: issueThreadInteractionFixtureMeta.issueId,
|
||||
kind: "ask_user_questions",
|
||||
title: questionSet.title ?? null,
|
||||
summary: questionSet.description ?? null,
|
||||
status: "pending",
|
||||
continuationPolicy: "wake_assignee",
|
||||
createdByAgentId: "agent-codex",
|
||||
createdByUserId: null,
|
||||
resolvedByAgentId: null,
|
||||
resolvedByUserId: null,
|
||||
createdAt: new Date("2026-11-13T15:02:00.000Z"),
|
||||
updatedAt: new Date("2026-11-13T15:02:00.000Z"),
|
||||
resolvedAt: null,
|
||||
payload: { ...questionSetToAskUserQuestionsPayload(questionSet), supersedeOnUserComment: false },
|
||||
result: null,
|
||||
...overrides,
|
||||
} as AskUserQuestionsInteraction;
|
||||
}
|
||||
|
||||
const resolvedAt = new Date("2026-11-13T15:06:00.000Z");
|
||||
|
||||
export const mcpAskingCard = mcpQuestionCard("mcp-elicit-asking", mcpTicketQuestionSet);
|
||||
|
||||
export const mcpAnsweredCard = mcpQuestionCard("mcp-elicit-answered", mcpTicketQuestionSet, {
|
||||
status: "answered",
|
||||
resolvedByUserId: issueThreadInteractionFixtureMeta.currentUserId,
|
||||
resolvedAt,
|
||||
updatedAt: resolvedAt,
|
||||
result: {
|
||||
version: 1,
|
||||
answers: [
|
||||
{ questionId: "title", optionIds: ["paperclip_text_answer"], otherText: "Login button does nothing on Safari" },
|
||||
{ questionId: "priority", optionIds: ["choice_1"] },
|
||||
{ questionId: "labels", optionIds: ["choice_1", "choice_3"] },
|
||||
{ questionId: "page", optionIds: ["choice_2"] },
|
||||
{ questionId: "estimate", optionIds: ["paperclip_text_answer"], otherText: "3" },
|
||||
],
|
||||
},
|
||||
});
|
||||
|
||||
/** Skip sends "decline" to the app. */
|
||||
export const mcpSkippedCard = mcpQuestionCard("mcp-elicit-skipped", mcpTeamQuestionSet, {
|
||||
status: "cancelled",
|
||||
resolvedByUserId: issueThreadInteractionFixtureMeta.currentUserId,
|
||||
resolvedAt,
|
||||
updatedAt: resolvedAt,
|
||||
result: { version: 1, answers: [], outcome: "skipped" },
|
||||
});
|
||||
|
||||
/** Nobody answered within a day: the card is withdrawn and the app is asked again. */
|
||||
export const mcpExpiredCard = mcpQuestionCard("mcp-elicit-expired", mcpConfirmQuestionSet, {
|
||||
status: "cancelled",
|
||||
resolvedByAgentId: "agent-codex",
|
||||
resolvedAt,
|
||||
updatedAt: resolvedAt,
|
||||
result: { version: 1, answers: [], outcome: "withdrawn", reason: "The app's question expired before it was answered." },
|
||||
});
|
||||
|
||||
/** Two questions in one round: each is its own card, and both answers go back together. */
|
||||
export const mcpTwoQuestionCards = [
|
||||
mcpQuestionCard("mcp-elicit-two-a", mcpTeamQuestionSet),
|
||||
mcpQuestionCard("mcp-elicit-two-b", mcpConfirmQuestionSet),
|
||||
];
|
||||
Reference in new issue
Block a user