mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - MCP Apps (#21119) show interactive widgets from MCP servers, such as Circleback meeting cards, with the agent's reply in the task chat. > - The first version deferred three parts of the MCP Apps spec. A widget could not propose a chat message (`ui/message`). It could not give the agent context (`ui/update-model-context`). It could not go full screen. > - Paperclip also ignored the `icons` that MCP servers declare on tools (SEP-973). > - The security review of #21119 showed what these features need from day one: explicit consent, untrusted-data labels and strict icon sanitizing. > - This pull request adds the three host features and provider tool icons, with those protections built in. > - The benefit is that widgets can now work with the person and the agent, not only display data. ## Linked Issues or Issue Description Refs #21119 **Subsystem affected** MCP Apps host (task chat widgets), tool catalog, run wake prompt. **Problem or motivation** The MCP Apps host refused `ui/message` (-32601), dropped `ui/update-model-context` and kept every view inline. MCP tool `icons` were not parsed or shown. So widgets could not ask the agent a follow-up, the agent could not see what the person selected in a widget, large widgets were cramped, and tool rows used only generic icons. **Proposed solution** Add consent-gated view messages, per-view app context delivered to the task's next run as untrusted data, a full-screen dialog, and sanitized provider icons. Details are under "What Changed". **Alternatives considered** - Send view messages with a new server route that creates the comment itself. Rejected: comment creation has many rules (agent chat ownership, paused conversations, queued delivery, wakeups, receipts). The widget's Send button uses the same send path as the composer. A small route then records which view the comment came from. - Keep the iframe in place for full screen with CSS. Rejected: chat containers can create containing blocks that break `position: fixed`. A moved iframe always reloads, so the dialog hosts a new frame instead. **Roadmap alignment** Continues the MCP feature work after #21119, #21140 and #21219. It does not touch the MCP Tasks work (gateway `tools/call` polling and elicitation). ## What Changed - **`ui/message`.** The host shows "<App> wants to send: …" with **Send** and **Dismiss** under the widget (and inside the full-screen dialog). Nothing is sent before the click. Send posts the text as the viewer's own comment through the chat's normal send path (`handleThreadAdd`). `POST /api/issues/:issueId/mcp-app-views/:viewId/messages` then logs `issue.mcp_app_message_sent`. It accepts only the caller's own comment on the same task, matched by `clientRequestId`, from the last 10 minutes. One proposal per view can wait at a time. The view gets `{}` after the send, or -32000 "Message sending denied" after Dismiss. Only `user` text up to 8,000 characters is accepted. - **`ui/update-model-context`.** `PUT /api/issues/:issueId/mcp-app-views/:viewId/model-context` stores the latest context per view in `tool_mcp_app_views.model_context` (text blocks and `structuredContent`, 16 KB at most). Updates are applied in order and deduped in the browser and on the server. A change logs `issue.mcp_app_context_updated`, and an empty update clears the context. The task's next run gets the three most recently updated contexts as an `## App context (untrusted)` wake-prompt section. The section quotes the data as JSON and says it is third-party data, not instructions. The read runs in parallel with the other run preparation and never fails the run. CLI adapters and the native runner render it through the same `renderPaperclipWakePrompt`. - **Who may do this.** Messages and context need a signed-in person with `issue:comment` on the task. Agents and API keys get 403. Other tasks and companies get 404. `message` and `updateModelContext` are advertised in `hostCapabilities` only where the viewer can send messages. - **Full screen.** The host advertises `availableDisplayModes: ["inline","fullscreen"]` and handles `ui/request-display-mode`. It honors the view's declared modes and answers with the resulting mode. It sends `host-context-changed` with `displayMode` and the container (fixed `height`/`width` in full screen), and again when that container resizes. A new **Open full screen** control sits next to "Widget from …". Full screen is a Paperclip dialog that closes with Exit, Escape or the view's own request. - **Provider tool icons.** `icons` on MCP tool descriptors are sanitized into the new `tool_catalog_entries.icons` column, outside the version hash, so a new icon never quarantines a reviewed tool. Only `https:` URLs and `data:image/*` URIs are kept, and SVG only as `data:`. A `data:` icon is at most 32 KB, a URL at most 2,048 characters, with at most 4 icons per tool. `GET /api/companies/:companyId/tool-icons` lists them keyed by gateway tool name, in one cached request per chat. Task chat tool rows and the app's actions list show them through `ProviderToolIcon`. It renders `<img referrerPolicy="no-referrer">` at a fixed size and never inlines markup. It checks the source again before rendering and falls back to the taxonomy icon. - **Schema.** Migration `0477` adds `tool_catalog_entries.icons`, `tool_mcp_app_views.model_context` and `model_context_updated_at`, all nullable. - **Docs and stories.** `doc/connections/MCP-APPS.md` documents the new behavior, and the finished items are removed from "Limits and follow-ups". `Tasks/MCP App views` has new stories: "View asks to send a message", "Full screen" and "Tool rows with provider icons". The fixture view now uses `ui/message`, `ui/request-display-mode` and `ui/update-model-context`. ## Verification - `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts server/src/__tests__/tool-catalog-publication.test.ts server/src/__tests__/openapi-routes.test.ts packages/shared/src/mcp-icons.test.ts packages/shared/src/mcp-apps.test.ts`: pass (embedded Postgres). These tests cover: - Context: stored, deduped, logged once, 413 when too large, cleared, scoped to the task and company, refused for agents (403), and rendered into the wake prompt as untrusted data. - Messages: attributed only to the viewer's own recent comment on the same task. A teammate's comment, an unknown request id or an old comment gets 404. An agent gets 403. - Icons: stored sanitized, and the version hash and status do not change. Another company sees nothing. - `cd ui && pnpm exec vitest run src/components/mcp-app/ src/components/ProviderToolIcon.test.tsx src/pages/apps/app-detail/`: 69 pass. These tests cover: - The host protocol for each new method: capabilities, consent wait, one proposal at a time, invalid input, ordered and deduped context, the size limit, and the display-mode rules. - The consent card (nothing sent without Send). - The full-screen dialog (one frame at a time). - Icon rendering (no-referrer `img`, no inline SVG, fallback). - `cd ui && pnpm typecheck` (including Storybook) and `tsc --noEmit` for the server: clean. - Red/green: the new route and host tests fail on `master`, where the routes do not exist and the host answers -32601 or drops updates. The icon descriptor test failed when the publication write was removed. - Not run locally: the full suite, and `packages/adapter-utils/src/server-utils.test.ts › runChildProcess › does not crash when the child closes stdin before a delayed write`. That test times out on this Mac with or without this change, so it is a local platform issue. CI covers both. ## Risks - Migration risk is low: three nullable columns, no backfill. - Every run on a task now does one extra indexed read, in parallel with the other preparation. Errors are logged and the run continues without app context. - If the attribution request fails after the comment is sent, the comment stays without the `mcp_app_message_sent` activity row. This is documented. - Switching between inline and full screen restarts the view, so state inside the widget resets. This is documented as a limit. - Icon names shortened with a hash by the gateway (very long names) do not match, and those rows keep the taxonomy icon. > 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 and code execution. One subagent (the same model) built the provider-icon part. ## 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 - [ ] 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>
171 lines
6.9 KiB
TypeScript
171 lines
6.9 KiB
TypeScript
import { useTaskChatExpansion } from "./expansion-state";
|
||
import { cn } from "@/lib/utils";
|
||
import {
|
||
Check,
|
||
ChevronRight,
|
||
Loader2,
|
||
ShieldCheck,
|
||
ShieldX,
|
||
X,
|
||
} from "lucide-react";
|
||
import type { TaskChatToolItem } from "./task-chat-model";
|
||
import { toolTaxonomy } from "./tool-taxonomy";
|
||
import { useTaskChatShimmer } from "./TaskChatShimmer";
|
||
import { TaskChatDiffCounts, TaskChatDiffView } from "./TaskChatDiffView";
|
||
import { useTaskReferenceLabel, withTaskReference } from "./task-reference";
|
||
import { ProviderToolIcon, useProviderToolIcons } from "@/components/ProviderToolIcon";
|
||
|
||
const STATUS_ICON = {
|
||
pending: { Icon: Loader2, spin: false, tone: "text-muted-foreground" },
|
||
in_progress: {
|
||
Icon: Loader2,
|
||
spin: true,
|
||
tone: "text-(--status-agent-running)",
|
||
},
|
||
completed: { Icon: Check, spin: false, tone: "text-muted-foreground" },
|
||
failed: { Icon: X, spin: false, tone: "text-destructive" },
|
||
interrupted: { Icon: X, spin: false, tone: "text-muted-foreground" },
|
||
} as const;
|
||
|
||
function ToolTarget({ text }: { text: string }) {
|
||
return (
|
||
<span className="task-chat-collapsed-line-fade min-w-0 flex-1 font-mono text-(length:--text-micro) leading-4">
|
||
{text}
|
||
</span>
|
||
);
|
||
}
|
||
|
||
/** Names the task a call is about by identifier; its UUID is never shown. */
|
||
function TaskReferenceToolTarget({ taskRefId, target }: { taskRefId: string; target?: string }) {
|
||
const taskLabel = useTaskReferenceLabel(taskRefId);
|
||
return <ToolTarget text={withTaskReference(target, taskLabel)!} />;
|
||
}
|
||
|
||
/**
|
||
* Tool invocation as a flat activity row (v7): [glyph] [name] [mono target] …
|
||
* [hover chevron] [status]. No card chrome — activity is metadata, not
|
||
* content. Clicking toggles a compact result/change summary (left-rail
|
||
* inset). An edit row carries its `+N −M` counts and opens to a compact,
|
||
* height-capped diff of that one edit.
|
||
*/
|
||
export function TaskChatToolCard({ item }: { item: TaskChatToolItem }) {
|
||
const { Icon, spin, tone } = STATUS_ICON[item.status];
|
||
const shimmer = useTaskChatShimmer(item.id);
|
||
const RowIcon = toolTaxonomy(item.rawName ?? item.name).icon;
|
||
const providerIcons = useProviderToolIcons(item.rawName ?? item.name);
|
||
const [showDetail, setShowDetail] = useTaskChatExpansion(item.id, false);
|
||
const expandable = Boolean(item.target || item.detail || item.diff);
|
||
|
||
return (
|
||
<div data-testid="task-chat-tool-card" className="flex min-w-0 max-w-full flex-col text-xs">
|
||
<button
|
||
type="button"
|
||
onClick={expandable ? () => setShowDetail((v) => !v) : undefined}
|
||
aria-expanded={expandable ? showDetail : undefined}
|
||
className={cn(
|
||
"group/tool -mx-1.5 flex min-h-6 w-full min-w-0 max-w-full items-center gap-2 overflow-hidden rounded-sm px-1.5 py-1 text-left leading-none text-muted-foreground",
|
||
expandable
|
||
? "cursor-pointer transition-colors hover:bg-muted/60 hover:text-foreground"
|
||
: "cursor-default",
|
||
)}
|
||
>
|
||
<span className="flex w-5 shrink-0 items-center justify-center">
|
||
<ProviderToolIcon
|
||
icons={providerIcons}
|
||
fallback={RowIcon}
|
||
className="h-3.5 w-3.5 shrink-0"
|
||
testId="task-chat-tool-icon"
|
||
/>
|
||
</span>
|
||
<span data-conversation-tool-running={item.status === "in_progress" && shimmer ? "true" : undefined} className="flex min-w-0 flex-1 items-baseline gap-2 overflow-hidden">
|
||
<span className="shrink-0 font-medium leading-4">{item.name}</span>
|
||
{item.taskRefId ? (
|
||
<TaskReferenceToolTarget taskRefId={item.taskRefId} target={item.target} />
|
||
) : item.target ? (
|
||
<ToolTarget text={item.target} />
|
||
) : null}
|
||
</span>
|
||
<span className="ml-auto flex shrink-0 items-center gap-2">
|
||
{item.diff && (item.diff.added > 0 || item.diff.removed > 0) ? (
|
||
<TaskChatDiffCounts
|
||
added={item.diff.added}
|
||
removed={item.diff.removed}
|
||
className="text-(length:--text-micro)"
|
||
/>
|
||
) : null}
|
||
{item.decision ? (
|
||
<span
|
||
className={cn(
|
||
"flex items-center gap-1 text-(length:--text-micro)",
|
||
item.decision === "allowed"
|
||
? "text-(--status-task-icon-done)"
|
||
: "text-destructive",
|
||
)}
|
||
>
|
||
{item.decision === "allowed" ? (
|
||
<ShieldCheck className="h-3 w-3" />
|
||
) : (
|
||
<ShieldX className="h-3 w-3" />
|
||
)}
|
||
{item.decision}
|
||
</span>
|
||
) : null}
|
||
{expandable ? (
|
||
<ChevronRight
|
||
className={cn(
|
||
"h-3 w-3 opacity-0 transition-[opacity,transform] group-hover/tool:opacity-80",
|
||
showDetail ? "rotate-90" : null,
|
||
)}
|
||
aria-hidden
|
||
/>
|
||
) : null}
|
||
<Icon
|
||
className={cn("h-3.5 w-3.5", tone, spin && "animate-spin")}
|
||
aria-hidden
|
||
/>
|
||
{item.status === "interrupted" ? (
|
||
<span className="text-(length:--text-micro) text-muted-foreground">
|
||
Interrupted
|
||
</span>
|
||
) : null}
|
||
</span>
|
||
</button>
|
||
{item.target && showDetail && !item.diff?.lines?.length ? (
|
||
<div
|
||
className="task-chat-expanded-line-wrap ml-1.5 mt-0.5 min-w-0 max-w-full overflow-hidden border-l-2 border-border py-1 pl-2.5 font-mono text-(length:--text-micro) leading-relaxed text-muted-foreground"
|
||
data-testid="task-chat-tool-target-detail"
|
||
>
|
||
{item.target}
|
||
</div>
|
||
) : null}
|
||
{item.detail && showDetail ? (
|
||
<pre className="task-chat-expanded-line-wrap ml-1.5 mt-0.5 min-w-0 max-w-full overflow-hidden whitespace-pre-wrap border-l-2 border-border py-1 pl-2.5 font-mono text-(length:--text-micro) leading-relaxed text-muted-foreground">
|
||
{item.detail}
|
||
</pre>
|
||
) : null}
|
||
{item.diff && showDetail ? (
|
||
item.diff.lines && item.diff.lines.length > 0 ? (
|
||
<div className="ml-1.5 mt-1 min-w-0 max-w-full" data-testid="task-chat-tool-diff">
|
||
<TaskChatDiffView lines={item.diff.lines} truncated={item.diff.truncated} />
|
||
</div>
|
||
) : (
|
||
<div
|
||
className="ml-1.5 mt-0.5 border-l-2 border-border py-1 pl-2.5"
|
||
data-testid="task-chat-tool-change-summary"
|
||
>
|
||
<div className="flex min-w-0 items-center gap-2 text-(length:--text-micro) text-muted-foreground">
|
||
<span className="shrink-0">Changed</span>
|
||
{item.diff.path ? (
|
||
<span className="min-w-0 truncate font-mono text-foreground">
|
||
{item.diff.path}
|
||
</span>
|
||
) : null}
|
||
<TaskChatDiffCounts added={item.diff.added} removed={item.diff.removed} className="ml-auto" />
|
||
</div>
|
||
</div>
|
||
)
|
||
) : null}
|
||
</div>
|
||
);
|
||
}
|