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.
> - 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>
224 lines
8.5 KiB
TypeScript
224 lines
8.5 KiB
TypeScript
/**
|
|
* MCP Apps (SEP-1865, spec 2026-01-26): interactive `ui://` views that an MCP
|
|
* server attaches to a tool. Paperclip is the host: it keeps the tool's UI
|
|
* declaration, records each call whose tool has one, and renders the view in a
|
|
* sandboxed iframe in the task chat.
|
|
*
|
|
* https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
|
|
*/
|
|
|
|
import { z } from "zod";
|
|
|
|
export const MCP_APPS_EXTENSION_ID = "io.modelcontextprotocol/ui";
|
|
export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
|
|
export const MCP_APPS_PROTOCOL_VERSION = "2026-01-26";
|
|
/** Largest view document Paperclip renders. Larger documents fall back to the plain tool row. */
|
|
export const MCP_APP_MAX_HTML_BYTES = 4 * 1024 * 1024;
|
|
|
|
/** Client capability Paperclip advertises in `initialize` to MCP servers. */
|
|
export const MCP_APPS_CLIENT_CAPABILITY = {
|
|
[MCP_APPS_EXTENSION_ID]: { mimeTypes: [MCP_APP_MIME_TYPE] },
|
|
} as const;
|
|
|
|
export type McpAppToolVisibility = "model" | "app";
|
|
|
|
/**
|
|
* A tool's normalized `_meta.ui` declaration. `resourceUri` is null for a tool
|
|
* that only declares visibility, such as an app-only helper without a view.
|
|
*/
|
|
export interface McpAppToolUi {
|
|
resourceUri: string | null;
|
|
visibility: McpAppToolVisibility[];
|
|
}
|
|
|
|
export interface McpAppResourceCsp {
|
|
connectDomains?: string[];
|
|
resourceDomains?: string[];
|
|
frameDomains?: string[];
|
|
baseUriDomains?: string[];
|
|
}
|
|
|
|
export interface McpAppResourcePermissions {
|
|
camera?: boolean;
|
|
microphone?: boolean;
|
|
geolocation?: boolean;
|
|
clipboardWrite?: boolean;
|
|
}
|
|
|
|
/** The view document plus the resource's `_meta.ui` rendering hints. */
|
|
export interface McpAppResource {
|
|
uri: string;
|
|
html: string;
|
|
csp: McpAppResourceCsp;
|
|
permissions: McpAppResourcePermissions;
|
|
prefersBorder: boolean | null;
|
|
}
|
|
|
|
/** One recorded tool call whose tool declares a view. */
|
|
export interface McpAppViewSummary {
|
|
id: string;
|
|
issueId: string | null;
|
|
runId: string | null;
|
|
connectionId: string;
|
|
applicationName: string;
|
|
/** Name the agent called (the gateway tool name). */
|
|
toolName: string;
|
|
/** The provider's own tool name. */
|
|
upstreamToolName: string;
|
|
resourceUri: string;
|
|
toolInput: Record<string, unknown>;
|
|
createdAt: string;
|
|
}
|
|
|
|
export interface McpAppViewDetail extends McpAppViewSummary {
|
|
/** The MCP `CallToolResult` sent to the view as `ui/notifications/tool-result`. */
|
|
toolResult: McpAppCallToolResult;
|
|
resource: McpAppResource;
|
|
}
|
|
|
|
export interface McpAppCallToolResult {
|
|
content: unknown[];
|
|
structuredContent?: Record<string, unknown>;
|
|
_meta?: Record<string, unknown>;
|
|
isError?: boolean;
|
|
}
|
|
|
|
/** Body of `POST /api/issues/:issueId/mcp-app-views/:viewId/tool-calls`: a view's `tools/call`. */
|
|
export const mcpAppToolCallSchema = z.object({
|
|
name: z.string().min(1).max(256),
|
|
arguments: z.record(z.string(), z.unknown()).optional(),
|
|
}).strict();
|
|
|
|
export type McpAppToolCallRequest = z.infer<typeof mcpAppToolCallSchema>;
|
|
|
|
function record(value: unknown): Record<string, unknown> | null {
|
|
return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
|
|
}
|
|
|
|
function stringList(value: unknown): string[] | undefined {
|
|
if (!Array.isArray(value)) return undefined;
|
|
const list = value.filter((item): item is string => typeof item === "string" && item.trim().length > 0).map((item) => item.trim());
|
|
return list;
|
|
}
|
|
|
|
/**
|
|
* Reads a tool's UI declaration from its `_meta`. Accepts the deprecated flat
|
|
* `_meta["ui/resourceUri"]` key, which servers still emit during the
|
|
* transition. Visibility is kept even without a view, so an app-only helper
|
|
* stays hidden from agents. Returns null when the tool declares neither.
|
|
*/
|
|
export function readMcpAppToolUi(meta: unknown): McpAppToolUi | null {
|
|
const metaRecord = record(meta);
|
|
if (!metaRecord) return null;
|
|
const ui = record(metaRecord.ui);
|
|
const rawUri = typeof ui?.resourceUri === "string"
|
|
? ui.resourceUri
|
|
: typeof metaRecord["ui/resourceUri"] === "string" ? metaRecord["ui/resourceUri"] as string : null;
|
|
const resourceUri = rawUri && rawUri.startsWith("ui://") && rawUri.length <= 2048 ? rawUri : null;
|
|
const declared = Array.isArray(ui?.visibility)
|
|
? (ui.visibility as unknown[]).filter((item): item is McpAppToolVisibility => item === "model" || item === "app")
|
|
: null;
|
|
if (!resourceUri && declared === null) return null;
|
|
// An explicit list with no valid entries (for example `[]`) grants nothing.
|
|
const visibility = declared === null ? ["model", "app"] as McpAppToolVisibility[] : [...new Set(declared)];
|
|
return { resourceUri, visibility };
|
|
}
|
|
|
|
export function mcpAppToolVisibleToModel(ui: McpAppToolUi | null | undefined): boolean {
|
|
return !ui || ui.visibility.includes("model");
|
|
}
|
|
|
|
export function mcpAppToolCallableFromApp(ui: McpAppToolUi | null | undefined): boolean {
|
|
return !ui || ui.visibility.includes("app");
|
|
}
|
|
|
|
/**
|
|
* Picks the view document out of a `resources/read` result. The content must be
|
|
* the requested `ui://` resource with the MCP Apps mime type; `text` or base64
|
|
* `blob` content is accepted.
|
|
*/
|
|
export function readMcpAppResource(result: unknown, uri: string): McpAppResource | null {
|
|
const contents = record(result)?.contents;
|
|
if (!Array.isArray(contents)) return null;
|
|
for (const item of contents) {
|
|
const content = record(item);
|
|
if (!content) continue;
|
|
if (typeof content.uri === "string" && content.uri !== uri) continue;
|
|
const mimeType = typeof content.mimeType === "string" ? content.mimeType.replace(/\s+/g, "").toLowerCase() : "";
|
|
if (mimeType !== MCP_APP_MIME_TYPE) continue;
|
|
const html = typeof content.text === "string"
|
|
? content.text
|
|
: typeof content.blob === "string" ? decodeBase64Utf8(content.blob) : null;
|
|
if (html === null || html.length === 0) continue;
|
|
const ui = record(record(content._meta)?.ui);
|
|
const csp = record(ui?.csp);
|
|
const permissions = record(ui?.permissions);
|
|
return {
|
|
uri,
|
|
html,
|
|
csp: {
|
|
connectDomains: stringList(csp?.connectDomains),
|
|
resourceDomains: stringList(csp?.resourceDomains),
|
|
frameDomains: stringList(csp?.frameDomains),
|
|
baseUriDomains: stringList(csp?.baseUriDomains),
|
|
},
|
|
permissions: {
|
|
camera: permissions?.camera === true || record(permissions?.camera) !== null,
|
|
microphone: permissions?.microphone === true || record(permissions?.microphone) !== null,
|
|
geolocation: permissions?.geolocation === true || record(permissions?.geolocation) !== null,
|
|
clipboardWrite: permissions?.clipboardWrite === true || record(permissions?.clipboardWrite) !== null,
|
|
},
|
|
prefersBorder: typeof ui?.prefersBorder === "boolean" ? ui.prefersBorder : null,
|
|
};
|
|
}
|
|
return null;
|
|
}
|
|
|
|
function decodeBase64Utf8(value: string): string | null {
|
|
try {
|
|
const binary = globalThis.atob(value);
|
|
const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
|
|
return new TextDecoder().decode(bytes);
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* A CSP source is accepted only when it is an https origin (optionally with a
|
|
* leading `*.` subdomain wildcard). Anything else (keywords, schemes, paths,
|
|
* quotes) is dropped so a server cannot widen the policy beyond origins.
|
|
*/
|
|
export function sanitizeMcpAppCspSource(source: string): string | null {
|
|
const trimmed = source.trim();
|
|
const match = /^https:\/\/(\*\.)?([a-z0-9-]+(\.[a-z0-9-]+)+)(:\d{1,5})?\/?$/i.exec(trimmed);
|
|
if (!match) return null;
|
|
return `https://${match[1] ?? ""}${match[2]!.toLowerCase()}${match[4] ?? ""}`;
|
|
}
|
|
|
|
/**
|
|
* The CSP for a view: the spec's restrictive default plus only the origins the
|
|
* server declared in `_meta.ui.csp`.
|
|
*/
|
|
export function buildMcpAppCsp(csp: McpAppResourceCsp): string {
|
|
const list = (values: string[] | undefined) => (values ?? []).map(sanitizeMcpAppCspSource).filter((value): value is string => value !== null);
|
|
const resource = list(csp.resourceDomains);
|
|
const connect = list(csp.connectDomains);
|
|
const frame = list(csp.frameDomains);
|
|
const base = list(csp.baseUriDomains);
|
|
const join = (...parts: string[]) => parts.filter(Boolean).join(" ");
|
|
return [
|
|
"default-src 'none'",
|
|
`script-src ${join("'unsafe-inline'", ...resource)}`,
|
|
`style-src ${join("'unsafe-inline'", ...resource)}`,
|
|
`img-src ${join("data:", "blob:", ...resource)}`,
|
|
`font-src ${join("data:", ...resource)}`,
|
|
`media-src ${join("data:", "blob:", ...resource)}`,
|
|
`connect-src ${connect.length > 0 ? connect.join(" ") : "'none'"}`,
|
|
`frame-src ${frame.length > 0 ? frame.join(" ") : "'none'"}`,
|
|
`base-uri ${base.length > 0 ? base.join(" ") : "'none'"}`,
|
|
"object-src 'none'",
|
|
"form-action 'none'",
|
|
].join("; ");
|
|
}
|