Files
PaperClipAI/server/src/services/tool-access/catalog/descriptors.ts
T
DottaandClaude Opus 5.5 8ff45c0fa9 feat(connections): render MCP Apps views in the task chat, starting with Circleback (#21119)
## 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>
2026-11-12 13:28:05 -06:00

301 lines
12 KiB
TypeScript

import { nativeProviderCatalogFor } from "../../native-provider-catalogs.js";
import { restConnectorFor } from "../../connectors/rest-registry.js";
import { googleWorkspaceToolTarget } from "@paperclipai/shared";
import { BROWSER_USE_TOOLS } from "@paperclipai/shared";
import { isMemoryConnectorId } from "@paperclipai/shared";
import { readMcpAppToolUi, type McpAppToolUi } from "@paperclipai/shared";
import { toolConnections } from "@paperclipai/db";
import type { ToolRiskLevel } from "@paperclipai/shared";
import { GOOGLE_WORKSPACE_CONNECTOR_PROFILES, type GoogleWorkspaceConnectorProfileId } from "@paperclipai/shared";
import { connectorToolPolicy } from "../../connectors/tool-policy.js";
function asRecord(value: unknown): Record<string, unknown> {
if (value && typeof value === "object" && !Array.isArray(value))
return value as Record<string, unknown>;
return {};
}
export type McpToolDescriptor = {
name: string;
title?: string | null;
description?: string | null;
inputSchema?: Record<string, unknown>;
annotations?: Record<string, unknown>;
/** MCP Apps view declaration from the tool's `_meta.ui`. */
ui?: McpAppToolUi | null;
};
export function normalizeToolDescriptor(tool: unknown): McpToolDescriptor | null {
const record = asRecord(tool);
if (typeof record.name !== "string" || record.name.trim().length === 0)
return null;
return {
name: record.name.trim(),
title: typeof record.title === "string" ? record.title : null,
description:
typeof record.description === "string" ? record.description : null,
inputSchema: asRecord(record.inputSchema ?? record.input_schema),
annotations: asRecord(record.annotations),
ui: readMcpAppToolUi(record._meta),
};
}
// Match a verb anywhere it forms a name segment, not just at the leading edge.
// Real MCP servers namespace and style tool names many ways:
// "github:create_issue", "notion:update_page", "slack:postMessage", "set_value".
// A leading-anchor regex (/^(create|...)/) misses every namespaced/camelCase
// form and silently classifies writes as read-only. We normalise camelCase to
// snake_case first so "postMessage" -> "post_message", then match the verb when
// it is delimiter- or word-bounded. This mirrors the gateway classifier in
// tool-gateway.ts (inferToolRisk) so the two stay consistent.
function verbMatches(toolName: string, verbs: string): boolean {
const normalized = toolName
.replace(/([a-z0-9])([A-Z])/g, "$1_$2")
.toLowerCase();
return new RegExp(`\\b(${verbs})\\b|(^|[:._-])(${verbs})([:._-]|$)`).test(
normalized,
);
}
const NOTION_READ_TOOLS = new Set([
"notion-fetch",
"notion-get-async-task",
"notion-get-comments",
"notion-get-teams",
"notion-get-users",
"notion-query-data-sources",
"notion-query-database-view",
"notion-query-meeting-notes",
"notion-search",
]);
const NOTION_WRITE_TOOLS = new Set([
"notion-convert-page-to-skill",
"notion-create-comment",
"notion-create-database",
"notion-create-folder",
"notion-create-pages",
"notion-create-view",
"notion-duplicate-page",
"notion-move-pages",
"notion-update-data-source",
"notion-update-page",
"notion-update-view",
]);
const SHOPIFY_DESTRUCTIVE_TOOLS = new Set([
"cancel-cart",
"cancel-checkout",
"complete-checkout",
]);
function normalizedProviderToolName(toolName: string): string {
return toolName
.replace(/([a-z0-9])([A-Z])/g, "$1-$2")
.toLowerCase()
.replace(/[:._-]+/g, "-");
}
// Aggregators can add arbitrarily powerful tools without changing their MCP
// endpoint. Only these reviewed, exact capabilities are read-only. Unknown or
// renamed actions remain enabled by the usual access rules, but have write risk.
const AGGREGATOR_READ_TOOLS = new Map<string, ReadonlySet<string>>([
["executor", new Set(["skills"])],
["composio", new Set(["COMPOSIO_SEARCH_TOOLS", "COMPOSIO_GET_TOOL_SCHEMAS", "COMPOSIO_SEARCH_SKILLS", "COMPOSIO_USE_SKILL"])],
["arcade", new Set(["Github.GetRepository"])],
["zapier", new Set()],
]);
export function classifyRisk(
tool: McpToolDescriptor,
sourceTemplateKey?: string | null,
): ToolRiskLevel {
if (sourceTemplateKey === "google-workspace") {
const target = googleWorkspaceToolTarget(tool.name);
if (!target) return "destructive";
const risk = classifyRisk({ ...tool, name: target.upstreamName }, target.appSlug);
if (risk === "destructive" || target.leaf === "delete_event" || target.leaf === "send_message") return "destructive";
if (target.write) return "write";
return risk;
}
const annotations = tool.annotations ?? {};
if (annotations.destructiveHint === true || annotations.destructive === true)
return "destructive";
const reviewedRisk = connectorToolPolicy(sourceTemplateKey).classifyRisk?.(tool);
if (reviewedRisk) return reviewedRisk;
const normalizedToolName = normalizedProviderToolName(tool.name);
if (isMemoryConnectorId(sourceTemplateKey)) {
if (verbMatches(tool.name, "delete|remove|destroy|forget|prune|reset")) return "destructive";
// Supermemory uses one add_memory tool for both save and forget.
if (sourceTemplateKey === "supermemory" && normalizedToolName === "add-memory") return "destructive";
if (verbMatches(tool.name, "add|remember|save|record|ingest|cognify|update|create|set|upload|select|rename|share")) return "write";
if (annotations.readOnlyHint === false || annotations.writeHint === true) return "write";
const reads = ["get", "list", "search", "recall", "query", "retrieve", "who"];
return verbMatches(tool.name, reads.join("|")) ? "read" : "write";
}
const reviewedReads = AGGREGATOR_READ_TOOLS.get(sourceTemplateKey ?? "");
if (reviewedReads) {
if (verbMatches(tool.name, "delete|remove|destroy|unpublish")) return "destructive";
if (annotations.readOnlyHint === false || annotations.writeHint === true) return "write";
return reviewedReads.has(tool.name) ? "read" : "write";
}
if (sourceTemplateKey === "browser-use-cloud") {
return BROWSER_USE_TOOLS.find(t => t.name === tool.name)?.annotations.readOnlyHint ? "read" : "destructive";
}
// Fireflies sharing, moving, and access revocation are mutations even when
// a provider omits annotations or mistakenly advertises a read hint.
if (sourceTemplateKey === "fireflies" && [
"fireflies-share-meeting", "fireflies-revoke-meeting-access", "fireflies-move-meeting",
].includes(normalizedToolName)) return "write";
// Gmail archive removes a system label. Keep it behind the archive method's
// destructive Ask-first default even when the preview provider omits hints.
if (sourceTemplateKey === "gmail" && normalizedToolName === "unlabel-thread")
return "destructive";
if (sourceTemplateKey === "posthog" && normalizedToolName === "exec")
return "destructive";
// Superagent mirrors its REST API, and several mutations use verbs the
// generic classifier reads as reads: billable triage_finding, scans,
// restore_agent_builtin_rule, and credential-revoking revoke_agent_client.
// Only list/get tools and tools the provider marks read-only are reads.
if (sourceTemplateKey === "superagent") {
if (verbMatches(tool.name, "delete|remove|destroy|revoke")) return "destructive";
if (annotations.readOnlyHint === false || annotations.writeHint === true) return "write";
return /^(list|get)-/.test(normalizedToolName) || annotations.readOnlyHint === true ? "read" : "write";
}
// Ditto's translate, link and unlink tools replace saved text or developer
// IDs, but the generic classifier reads those verbs as reads. Only
// list/get/search tools, suggest_edit, and tools Ditto marks read-only are
// reads.
if (sourceTemplateKey === "ditto") {
if (verbMatches(tool.name, "delete|remove|destroy")) return "destructive";
if (annotations.readOnlyHint === false || annotations.writeHint === true) return "write";
return /^(list|get|search)-/.test(normalizedToolName) ||
normalizedToolName === "suggest-edit" ||
annotations.readOnlyHint === true
? "read"
: "write";
}
if (
sourceTemplateKey === "shopify" &&
SHOPIFY_DESTRUCTIVE_TOOLS.has(normalizedToolName)
)
return "destructive";
// Notion's hosted MCP catalog contains mutations whose names do not use one
// of the generic create/update/delete verbs (move, duplicate, and convert).
// Keep all reviewed tools explicit so provider changes are visible in code,
// while an annotation may still escalate a known read to a write.
if (
sourceTemplateKey === "notion" &&
NOTION_WRITE_TOOLS.has(normalizedToolName)
)
return "write";
if (annotations.readOnlyHint === false || annotations.writeHint === true)
return "write";
if (
sourceTemplateKey === "notion" &&
NOTION_READ_TOOLS.has(normalizedToolName)
)
return "read";
if (verbMatches(tool.name, "delete|remove|destroy|unpublish"))
return "destructive";
if (
verbMatches(
tool.name,
"create|update|write|set|send|publish|post|mutate|mark|archive",
)
)
return "write";
// PostHog exposes a broad and evolving catalog. Unknown tools must never be
// silently treated as reads; provider annotations can opt known reads in.
if (sourceTemplateKey === "posthog")
return annotations.readOnlyHint === true ? "read" : "write";
return "read";
}
export function isGmailToolPermanentlyBlocked(
tool: McpToolDescriptor,
): boolean {
if (googleWorkspaceToolLeafName(tool.name) === "unlabel-thread") return false;
const riskLevel = classifyRisk(tool, "gmail");
return (
verbMatches(
tool.name,
"send|trash|spam|delete|remove|destroy|execute|run",
) ||
(normalizedProviderToolName(tool.name).includes("label") &&
riskLevel !== "read")
);
}
const GOOGLE_WORKSPACE_READ_TOOLS: Record<string, ReadonlySet<string>> = {
gmail: new Set([
"get-message",
"get-thread",
"get-draft",
"list-drafts",
"list-labels",
"search-threads",
"list-threads",
"search-messages",
]),
"google-drive": new Set([
"download-file-content",
"get-file-metadata",
"get-file-permissions",
"list-recent-files",
"read-file-content",
"search-files",
]),
"google-docs": new Set(["read-doc"]),
"google-sheets": new Set(["get-values", "get-spreadsheet"]),
"google-slides": new Set(["read-presentation"]),
"google-calendar": new Set([
"get-event",
"list-calendars",
"list-events",
"search-events",
"suggest-time",
]),
"google-chat": new Set([
"search-conversations",
"list-messages",
"search-messages",
]),
"google-people": new Set([
"search-directory-people",
"search-contacts",
"get-user-profile",
]),
"google-workspace-search": new Set(["search-corpus"]),
};
function googleWorkspaceToolLeafName(name: string): string {
return (name.split(/[.:/]/).pop() ?? name)
.replace(/([a-z0-9])([A-Z])/g, "$1-$2")
.replace(/_/g, "-")
.toLowerCase();
}
export function isGoogleWorkspaceToolAllowed(
profileId: GoogleWorkspaceConnectorProfileId,
tool: McpToolDescriptor,
): boolean {
if (profileId === "workspace.all") return googleWorkspaceToolTarget(tool.name) !== null;
const profile = GOOGLE_WORKSPACE_CONNECTOR_PROFILES[profileId];
const toolName = googleWorkspaceToolLeafName(tool.name);
const readTools =
GOOGLE_WORKSPACE_READ_TOOLS[profile.appSlug] ?? new Set<string>();
return (
readTools.has(toolName) ||
profile.writeTools.some(
(writeTool) => googleWorkspaceToolLeafName(writeTool) === toolName,
)
);
}
export function shouldQuarantineNewEntries(
connection: typeof toolConnections.$inferSelect,
): boolean {
return Boolean(nativeProviderCatalogFor(connection) || restConnectorFor(connection)) || asRecord(connection.config).quarantineNewEntries === true;
}