mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents reach external apps through MCP connections. Paperclip
records each call and shows it as a tool row in the task chat.
> - MCP Apps (SEP-1865, extension `io.modelcontextprotocol/ui`, spec
2026-01-26) lets an MCP server attach an interactive `ui://` view to a
tool. Claude, Claude Code and VS Code render these views in chat.
Circleback uses them to show meeting cards.
> - Paperclip dropped the tool's `_meta.ui` at discovery and the
result's `_meta` at call time. Its gateway reported MCP App UI as
"unsupported". Circleback was reachable only through Composio, whose
toolkit has no `Display*` tools.
> - This pull request makes Paperclip an MCP Apps host. It also adds
Circleback as a native catalog connection.
> - The benefit is that a Circleback recap in a task shows the same
meeting cards as in Claude, and any other MCP server with views works
the same way.
## Linked Issues or Issue Description
**Subsystem affected**
Connections and apps (remote MCP gateway) and the task chat.
**Problem or motivation**
An agent that uses Circleback in Paperclip can only return text. The
same tools in Claude Code show interactive meeting cards
(`DisplayMeetings`). Paperclip discards the MCP Apps metadata, so it
cannot show them.
**Proposed solution**
Paperclip implements the host side of MCP Apps end to end. It keeps the
tool's view declaration and records each call that has a view. It
renders the view under the tool row in a sandboxed iframe that uses the
MCP Apps postMessage protocol. Circleback becomes a native catalog
connection, so its `Display*` tools are available.
**Alternatives considered**
Composio's `circleback_mcp` toolkit has 11 read tools and no `Display*`
tools, and its meta-tools return plain JSON, so it cannot carry views.
The spec's double-iframe sandbox proxy on a separate origin needs a
second origin that Paperclip does not have. A single opaque-origin
`srcdoc` frame with an injected CSP gives the same isolation.
**Roadmap alignment**
This extends the existing Apps catalog and MCP gateway. It adds no new
integration substrate (decision D4 in doc/connections/README.md).
**Additional context**
The standard, the design and the testing plan are in
`doc/connections/MCP-APPS.md`.
## What Changed
- **Shared:** `packages/shared/src/mcp-apps.ts` adds MCP Apps types,
`_meta.ui` and resource parsing (current and legacy keys), and a CSP
builder that keeps only well-formed `https` origins.
- **DB:** migration `0471` (`online_compatible`) adds
`tool_catalog_entries.ui_meta` and a new `tool_mcp_app_views` table.
- **Server, catalog:** discovery keeps each tool's `_meta.ui`. It is not
part of the version hash, so a view never quarantines a reviewed tool.
- **Server, gateway:**
- Paperclip advertises the MCP Apps client capability when it
initializes a session.
- App-only tools (`visibility: ["app"]`) are hidden from agents.
- The result `_meta` is kept for the view and is not sent to the agent.
- Each successful call to a tool with a view records a view row.
Recording is best effort.
- The gateway's `initialize` now reports `paperclip/mcp-app-ui:
host_rendered`.
- The context protocol (`resources/read`) now uses the injected test
transport, like the other remote calls.
- **Server, routes:** `server/src/routes/mcp-apps.ts`
- `GET /api/issues/:issueId/mcp-app-views` lists a task's views. It
needs task read access.
- `GET /api/issues/:issueId/mcp-app-views/:viewId` returns the view
document, read live through the agent's connection.
- `POST /api/issues/:issueId/mcp-app-views/:viewId/tool-calls` runs the
view's `tools/call`. It needs `tools:use` and reaches only tools of the
same connection that allow `app`. It uses the connection test-call path,
so policy, Ask first and audit apply.
- **UI:** `ui/src/components/mcp-app/`
- The host protocol: `ui/initialize` with theme, style variables and
size limits; tool-input; tool-result; size-changed; `tools/call`;
`ui/open-link` (http and https only); teardown.
- An opaque-origin iframe (`allow-scripts`, never `allow-same-origin`)
with the CSP placed before the view's markup.
- The views of a run render with that run's reply, in the live turn and
in settled history. They are keyed by the reply's run, so history needs
no transcript.
- **Circleback:** a native catalog app (`mcp-oauth`, DCR, `user
user:write`) with:
- the official logo;
- a reviewed risk classifier (Share* tools are writes, Delete* tools are
destructive, Display* tools are reads);
- warnings in the sign-in step;
- `doc/connections/CIRCLEBACK.md`.
Search now prefers a native app over an aggregator listing named "X
MCP".
- **Storybook:** `Tasks/MCP App views` shows the tool row with its view,
the ready state (Refresh calls a tool), loading, view unavailable, and a
tool call that needs approval.
## Verification
- `pnpm exec vitest run packages/shared/src/mcp-apps.test.ts
ui/src/components/mcp-app/`: 19 passed.
- `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts`: 3
passed, on embedded Postgres. The test connects Circleback through the
catalog with DCR OAuth against a fake Circleback MCP server. It checks:
- `ui_meta` is stored;
- an app-only tool is hidden from the agent;
- an agent call records one view with arguments, structured content and
`_meta`;
- a call without a view records nothing;
- the routes serve the view's HTML and CSP;
- the view's tool call works and a model-only tool is refused;
- another task, another company and an agent actor are refused.
- Circleback connector: 13 focused files, 645 tests passed. These are
the app definitions, search, aggregator fallback, connection intents,
tool policy, `AppsConnect` and `Browse`.
- Typecheck passed for `@paperclipai/shared`, `@paperclipai/server` and
`@paperclipai/ui`. `node scripts/storybook-catalog.mjs` and the
migration compatibility check also passed.
- Storybook check in the browser:
- In both themes, the view runs the handshake, renders the meeting cards
from `structuredContent`, picks up the theme variables, and resizes to
its content.
- Refresh sends `tools/call` and re-renders the cards.
- **Live Circleback end to end** on a local instance, with a real
Circleback account:
- Connected through the catalog entry with Circleback's dynamic client
registration and OAuth.
- Discovery stored the real view declarations:
- `DisplayMeetings` uses `ui://circleback/meetings.v2.html`.
- `DisplayActionItems` and `DisplayCalendarEvents` also have views.
- `ListAssigneeOptions` and `SetCalendarEventRecording` are app-only
helpers with no view. They are hidden from agents.
- A `claude_local` agent called `DisplayMeetings` on two tasks.
- The real 3.5 MB Circleback view rendered the meeting cards with the
agent's reply.
- Clicking a card opened that meeting in Circleback through
`ui/open-link`.
- The live run found two bugs, both fixed in this PR, each with a
regression test:
- The 1 MB tool-result limit blocked the view document.
- Views were hidden inside the folded tool history.
## Risks
- **New migration:** a new table and a nullable column. It is
`online_compatible`.
- **Existing connections:** tools get `ui_meta` on the next catalog
refresh. Until then, no view shows and the tool row is unchanged.
- **Untrusted provider HTML:** the view runs as provider HTML in an
opaque-origin sandbox. It cannot reach Paperclip's session, DOM or API.
Its network access is limited to the origins its server declared. A
view's tool calls use the viewer's permissions and the normal policy and
Ask-first path.
- **Agent tool lists:** app-only tools are removed from them. No current
provider marks tools app-only, so no listed tool disappears.
- **Search:** the change that prefers a native app over an "X MCP"
aggregator listing affects every app.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
subagents (one subagent authored the Circleback catalog connector).
## 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>
329 lines
13 KiB
TypeScript
329 lines
13 KiB
TypeScript
import { groupImageResources } from "./image-resources";
|
|
import { McpAppTurnViews, mcpAppRunRefreshKey } from "@/components/mcp-app/McpAppTurnViews";
|
|
import { useRef, type ReactNode } from "react";
|
|
import type { ExecutionProjection } from "@paperclipai/shared";
|
|
import { useSecondTick } from "@/hooks/useSecondTick";
|
|
import { cn } from "@/lib/utils";
|
|
import type {
|
|
TaskChatItem,
|
|
TaskChatMessageItem,
|
|
TaskChatRuntimeRequestDecision,
|
|
TaskChatRuntimeRequestItem,
|
|
} from "./task-chat-model";
|
|
import { TaskChatAgentIdentity, TaskChatBubble } from "./TaskChatBubble";
|
|
import { TaskChatBubbleActions } from "./TaskChatBubbleActions";
|
|
import { formatTaskChatTimestamp } from "./task-chat-adapter";
|
|
import { TaskChatRunnerActivityGroup } from "./TaskChatRunnerActivityGroup";
|
|
import { TaskChatSubagentTree } from "./TaskChatSubagentCard";
|
|
import { TaskChatRunHealthBanner, partitionRunHealthItems } from "./TaskChatRunHealthBanner";
|
|
import { TaskChatProtocolCard } from "./TaskChatProtocolCard";
|
|
import { TaskChatPlanPreviewCard } from "./TaskChatPlanPreviewCard";
|
|
import { TaskChatMarker } from "./TaskChatMarker";
|
|
import { TaskChatShimmerScope, useTaskChatShimmer } from "./TaskChatShimmer";
|
|
import {
|
|
buildTurnTimelineRows,
|
|
isTerminalRunStatus,
|
|
omitProgressRepeatedByResponse,
|
|
paperclipRunnerFinalResponse,
|
|
paperclipRunnerTimelineItems,
|
|
} from "./transcript-adapter";
|
|
|
|
function currentActivityStatusItems(
|
|
items: readonly TaskChatItem[],
|
|
): readonly TaskChatItem[] {
|
|
let boundaryIndex = -1;
|
|
for (let index = items.length - 1; index >= 0; index -= 1) {
|
|
const item = items[index];
|
|
if (
|
|
item.kind === "message" ||
|
|
item.kind === "plan_document" ||
|
|
(item.kind === "protocol" &&
|
|
(item.surface === "runtime_request" ||
|
|
item.surface === "run_result" ||
|
|
item.surface === "run_terminal"))
|
|
) {
|
|
boundaryIndex = index;
|
|
break;
|
|
}
|
|
}
|
|
return items.slice(boundaryIndex + 1);
|
|
}
|
|
|
|
function formatCompactDuration(ms: number | null): string | null {
|
|
if (ms == null || !Number.isFinite(ms)) return null;
|
|
const totalSeconds = Math.max(0, Math.floor(ms / 1000));
|
|
if (totalSeconds < 60) return `${totalSeconds}s`;
|
|
const minutes = Math.floor(totalSeconds / 60);
|
|
const seconds = totalSeconds % 60;
|
|
return seconds === 0 ? `${minutes}m` : `${minutes}m ${seconds}s`;
|
|
}
|
|
|
|
function terminalStatusFailed(status: string): boolean {
|
|
return (
|
|
status === "failed" ||
|
|
status === "cancelled" ||
|
|
status === "timed_out" ||
|
|
status === "interrupted"
|
|
);
|
|
}
|
|
|
|
function RunnerTurnStatus({
|
|
status,
|
|
startedAtMs,
|
|
finishedAtMs,
|
|
continuedAfterSteering = false,
|
|
waitingLabel,
|
|
}: {
|
|
status: string;
|
|
startedAtMs: number | null;
|
|
finishedAtMs?: number | null;
|
|
continuedAfterSteering?: boolean;
|
|
waitingLabel?: string | null;
|
|
}) {
|
|
const terminal = isTerminalRunStatus(status);
|
|
useSecondTick(!terminal && startedAtMs != null);
|
|
const elapsedMs =
|
|
startedAtMs == null
|
|
? null
|
|
: Math.max(
|
|
0,
|
|
(terminal ? (finishedAtMs ?? Date.now()) : Date.now()) - startedAtMs,
|
|
);
|
|
const elapsed = formatCompactDuration(elapsedMs);
|
|
|
|
const failed = terminalStatusFailed(status);
|
|
const label = terminal ? (failed ? "Stopped" : "Worked") : waitingLabel ?? "Working";
|
|
const suffix = terminal
|
|
? elapsed ? ` ${failed ? "after" : "for"} ${elapsed}` : ""
|
|
: elapsed ? `${waitingLabel ? " · " : " for "}${elapsed}` : "";
|
|
|
|
return (
|
|
<span
|
|
className="min-w-0 truncate text-sm font-normal text-muted-foreground"
|
|
data-testid="task-chat-turn-status-header"
|
|
data-turn-position="identity"
|
|
aria-live="polite"
|
|
aria-atomic="true"
|
|
>
|
|
{continuedAfterSteering ? <span data-conversation-meta="">Continued after steering · </span> : null}
|
|
{label}<span data-conversation-meta="">{suffix}</span>
|
|
</span>
|
|
);
|
|
}
|
|
|
|
function RunnerCurrentActivityTail({ status, waitingLabel }: { status: string; waitingLabel?: string | null }) {
|
|
const shimmer = useTaskChatShimmer("working");
|
|
if (isTerminalRunStatus(status)) return null;
|
|
return <div className="mt-2 flex min-h-8 min-w-0 items-center gap-2 px-1 py-1 text-xs text-muted-foreground" data-testid="task-chat-current-activity" data-turn-position="tail">
|
|
<span className={cn(!waitingLabel && shimmer && "shimmer-text shimmer-text-muted")} aria-live="polite" data-testid="task-chat-current-activity-label">{waitingLabel ?? "Thinking"}</span>
|
|
</div>;
|
|
}
|
|
|
|
interface RunnerHeaderProps {
|
|
runId?: string | null;
|
|
agentName?: string | null;
|
|
agentIcon?: string | null;
|
|
agent?: import("../AgentAvatar").AvatarAgent;
|
|
status: string;
|
|
execution?: ExecutionProjection | null;
|
|
preparationLabel?: string;
|
|
startedAtMs: number | null;
|
|
finishedAtMs?: number | null;
|
|
continuedAfterSteering?: boolean;
|
|
}
|
|
|
|
function runnerWaitingLabel({ runId, status, execution, preparationLabel }: RunnerHeaderProps) {
|
|
if (isTerminalRunStatus(status)) return null;
|
|
if (execution?.phase === "waiting_for_provider") return execution.label;
|
|
if (!runId && preparationLabel) return preparationLabel;
|
|
return status === "queued" && execution?.cause ? execution.label : null;
|
|
}
|
|
|
|
/** One identity stays mounted while admission discovers the run's renderer. */
|
|
export function TaskChatRunnerHeader({ statusContent, ...props }: RunnerHeaderProps & { statusContent?: ReactNode }) {
|
|
return <div className="flex min-h-8 min-w-0 items-center gap-2 pb-1 pt-2" data-testid="task-chat-runner-identity-row">
|
|
{props.agentName ? <TaskChatAgentIdentity agentName={props.agentName} agentIcon={props.agentIcon} agent={props.agent} /> : null}
|
|
{statusContent ?? <RunnerTurnStatus status={props.status} startedAtMs={props.startedAtMs} finishedAtMs={props.finishedAtMs}
|
|
continuedAfterSteering={props.continuedAfterSteering} waitingLabel={runnerWaitingLabel(props)} />}
|
|
</div>;
|
|
}
|
|
|
|
export function TaskChatRunnerTurn({
|
|
runId,
|
|
agentName,
|
|
agentIcon,
|
|
agent,
|
|
items,
|
|
status,
|
|
execution,
|
|
preparationLabel,
|
|
startedAtMs,
|
|
finishedAtMs,
|
|
activityUnavailable = false,
|
|
allowSummaryFallback = true,
|
|
awaitingContinuation = false,
|
|
waitSummary = null,
|
|
continuedAfterSteering = false,
|
|
showHeader = true,
|
|
onRuntimeRequestDecision,
|
|
}: {
|
|
/** Stable identity used to clear replay-latched final text for the next turn. */
|
|
runId?: string | null;
|
|
agentName?: string | null;
|
|
agentIcon?: string | null;
|
|
agent?: import("../AgentAvatar").AvatarAgent;
|
|
items: readonly TaskChatItem[];
|
|
status: string;
|
|
execution?: ExecutionProjection | null;
|
|
/** Presentation only while Send/Retry admission has no run yet. */
|
|
preparationLabel?: string;
|
|
startedAtMs: number | null;
|
|
finishedAtMs?: number | null;
|
|
activityUnavailable?: boolean;
|
|
allowSummaryFallback?: boolean;
|
|
/**
|
|
* Accepted wait/interaction authority: the turn is waiting, so an early
|
|
* provider final that only restates the wait is not presented as a reply.
|
|
* Prose the agent wrote for the user stays visible.
|
|
*/
|
|
awaitingContinuation?: boolean;
|
|
/** The accepted yielded result's wait summary, when known. */
|
|
waitSummary?: string | null;
|
|
/** The visible tail resumes the same native run after an accepted steer. */
|
|
continuedAfterSteering?: boolean;
|
|
/** The task thread keeps a shared header across native and legacy discovery. */
|
|
showHeader?: boolean;
|
|
onRuntimeRequestDecision?: (
|
|
item: TaskChatRuntimeRequestItem,
|
|
decision: TaskChatRuntimeRequestDecision,
|
|
) => void | Promise<void>;
|
|
}) {
|
|
const { failures: mcpStartupFailures, rest: turnItems } = partitionRunHealthItems(items);
|
|
const terminal = isTerminalRunStatus(status);
|
|
const waitingLabel = runnerWaitingLabel({ runId, status, execution, preparationLabel, startedAtMs });
|
|
const yielded = turnItems.some(
|
|
(item) =>
|
|
item.kind === "protocol" &&
|
|
item.surface === "run_result" &&
|
|
item.disposition === "yielded",
|
|
);
|
|
const observedFinal = paperclipRunnerFinalResponse(turnItems, awaitingContinuation
|
|
? { allowFallback: false, yielded: true, waitSummary }
|
|
: { allowFallback: terminal && allowSummaryFallback });
|
|
const observedProviderText = Boolean(
|
|
observedFinal &&
|
|
turnItems.some(
|
|
(item) =>
|
|
item.kind === "message" &&
|
|
item.id === observedFinal.id &&
|
|
item.channel !== "progress",
|
|
),
|
|
);
|
|
// A reconnect/replay can briefly rebuild the transcript without the final
|
|
// item (or with an earlier, shorter prefix). Provider-authored final text
|
|
// always replaces a structured summary fallback, even when it is shorter;
|
|
// within either class, displayed answer text remains monotonic.
|
|
const finalRef = useRef<{
|
|
runId?: string | null;
|
|
item?: TaskChatMessageItem;
|
|
providerText?: boolean;
|
|
}>({ runId });
|
|
if (finalRef.current.runId !== runId) finalRef.current = { runId };
|
|
// A provider final can arrive before the accepted yielded result. Clear any
|
|
// replay latch once the control plane establishes that this turn is waiting
|
|
// for continuation; only an authored (non-wait) final is re-latched below.
|
|
if (yielded || awaitingContinuation) finalRef.current = { runId };
|
|
if (
|
|
observedFinal &&
|
|
(!finalRef.current.item ||
|
|
(observedProviderText && !finalRef.current.providerText) ||
|
|
(observedProviderText === Boolean(finalRef.current.providerText) &&
|
|
observedFinal.text.length >= finalRef.current.item.text.length))
|
|
) {
|
|
finalRef.current.item = observedFinal;
|
|
finalRef.current.providerText = observedProviderText;
|
|
}
|
|
const final = finalRef.current.item;
|
|
const timelineItems = paperclipRunnerTimelineItems(turnItems);
|
|
const currentActivityItems = currentActivityStatusItems(timelineItems);
|
|
const timelineRows = groupImageResources(buildTurnTimelineRows(
|
|
omitProgressRepeatedByResponse(timelineItems, final?.text),
|
|
!terminal,
|
|
));
|
|
|
|
return (
|
|
<TaskChatShimmerScope items={items}><div
|
|
className="flex min-w-0 flex-col"
|
|
data-testid="task-chat-runner-turn"
|
|
data-phase={status === "queued" ? "startup" : undefined}
|
|
>
|
|
{showHeader ? <TaskChatRunnerHeader runId={runId} agentName={agentName} agentIcon={agentIcon} agent={agent}
|
|
status={status} execution={execution} preparationLabel={preparationLabel} startedAtMs={startedAtMs}
|
|
finishedAtMs={finishedAtMs} continuedAfterSteering={continuedAfterSteering} /> : null}
|
|
<TaskChatRunHealthBanner failures={mcpStartupFailures} />
|
|
{activityUnavailable ? (
|
|
<div
|
|
className="px-1 py-1 text-xs text-muted-foreground"
|
|
role="status"
|
|
data-testid="task-chat-activity-unavailable"
|
|
>
|
|
Live runner activity is temporarily unavailable. Retrying…
|
|
</div>
|
|
) : null}
|
|
{timelineRows.length > 0 ? (
|
|
<div
|
|
className="flex min-w-0 flex-col gap-2 py-1"
|
|
data-testid="task-chat-turn-timeline"
|
|
>
|
|
{timelineRows.map((row) => (
|
|
<div
|
|
className="min-w-0"
|
|
key={`${runId ?? "run"}:${row.id}`}
|
|
data-testid="task-chat-turn-timeline-row"
|
|
data-timeline-row-id={row.id}
|
|
data-thread-anchor={row.id}
|
|
>
|
|
{row.kind === "activity_phase" ? (
|
|
<TaskChatRunnerActivityGroup item={row} />
|
|
) : row.kind === "plan_document" ? (
|
|
<TaskChatPlanPreviewCard
|
|
source={{ kind: "saved", document: row.document }}
|
|
testId={
|
|
row.placement === "fallback"
|
|
? "task-chat-plan-preview-fallback"
|
|
: "task-chat-plan-preview"
|
|
}
|
|
/>
|
|
) : row.kind === "marker" ? (
|
|
<TaskChatMarker item={row} />
|
|
) : row.kind === "subagent_group" ? (
|
|
<TaskChatSubagentTree subagents={row.subagents} />
|
|
) : row.kind === "protocol" ? (
|
|
<TaskChatProtocolCard
|
|
item={row}
|
|
onRuntimeRequestDecision={onRuntimeRequestDecision}
|
|
/>
|
|
) : null}
|
|
</div>
|
|
))}
|
|
</div>
|
|
) : null}
|
|
<McpAppTurnViews runId={runId} refreshKey={mcpAppRunRefreshKey(turnItems, status)} />
|
|
{final ? (
|
|
<div
|
|
className="w-full"
|
|
data-testid="task-chat-final-response"
|
|
>
|
|
<TaskChatBubble
|
|
item={{ ...final, authorName: agentName ?? undefined, agentIcon, agent, timestamp: final.timestamp ?? formatTaskChatTimestamp(final.atMs) }}
|
|
animateEntry={false}
|
|
hideAgentIdentity={!continuedAfterSteering}
|
|
actions={<TaskChatBubbleActions copyText={final.text} />}
|
|
/>
|
|
</div>
|
|
) : null}
|
|
{!final && currentActivityItems.length === 0 ? <RunnerCurrentActivityTail status={status} waitingLabel={waitingLabel} /> : null}
|
|
</div></TaskChatShimmerScope>
|
|
);
|
|
}
|