Files
PaperClipAI/packages/shared/src/app-definitions.generated.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

114 lines
8.5 KiB
TypeScript

import a0 from "./app-definitions/agentmail.json" with { type: "json" };
import a1 from "./app-definitions/zapier.json" with { type: "json" };
import a2 from "./app-definitions/arcade.json" with { type: "json" };
import a3 from "./app-definitions/executor.json" with { type: "json" };
import a4 from "./app-definitions/railway.json" with { type: "json" };
import a5 from "./app-definitions/github.json" with { type: "json" };
import a6 from "./app-definitions/github-code-review-bot.json" with { type: "json" };
import a7 from "./app-definitions/slack.json" with { type: "json" };
import a8 from "./app-definitions/microsoft-teams.json" with { type: "json" };
import a9 from "./app-definitions/imessage-photon.json" with { type: "json" };
import a10 from "./app-definitions/telegram.json" with { type: "json" };
import a11 from "./app-definitions/discord.json" with { type: "json" };
import a12 from "./app-definitions/notion.json" with { type: "json" };
import a13 from "./app-definitions/posthog.json" with { type: "json" };
import a14 from "./app-definitions/linear.json" with { type: "json" };
import a15 from "./app-definitions/context7.json" with { type: "json" };
import a16 from "./app-definitions/shopify.json" with { type: "json" };
import a17 from "./app-definitions/composio.json" with { type: "json" };
import a18 from "./app-definitions/oauth-generic.json" with { type: "json" };
import a19 from "./app-definitions/api-key-generic.json" with { type: "json" };
import a20 from "./app-definitions/sentry.json" with { type: "json" };
import a21 from "./app-definitions/vercel.json" with { type: "json" };
import a22 from "./app-definitions/enterpret.json" with { type: "json" };
import a23 from "./app-definitions/anthropic.json" with { type: "json" };
import a24 from "./app-definitions/browser-use-cloud.json" with { type: "json" };
import a25 from "./app-definitions/cognee.json" with { type: "json" };
import a26 from "./app-definitions/jira.json" with { type: "json" };
import a27 from "./app-definitions/airtable.json" with { type: "json" };
import a28 from "./app-definitions/beehiiv.json" with { type: "json" };
import a29 from "./app-definitions/bitly.json" with { type: "json" };
import a30 from "./app-definitions/candid.json" with { type: "json" };
import a31 from "./app-definitions/cloudflare.json" with { type: "json" };
import a32 from "./app-definitions/cloudinary.json" with { type: "json" };
import a33 from "./app-definitions/coda.json" with { type: "json" };
import a34 from "./app-definitions/hugging-face.json" with { type: "json" };
import a35 from "./app-definitions/kernel.json" with { type: "json" };
import a36 from "./app-definitions/local-falcon.json" with { type: "json" };
import a37 from "./app-definitions/make.json" with { type: "json" };
import a38 from "./app-definitions/manufact.json" with { type: "json" };
import a39 from "./app-definitions/miro.json" with { type: "json" };
import a40 from "./app-definitions/netlify.json" with { type: "json" };
import a41 from "./app-definitions/oreilly.json" with { type: "json" };
import a42 from "./app-definitions/planetscale.json" with { type: "json" };
import a43 from "./app-definitions/resend.json" with { type: "json" };
import a44 from "./app-definitions/ticktick.json" with { type: "json" };
import a45 from "./app-definitions/todoist.json" with { type: "json" };
import a46 from "./app-definitions/webflow.json" with { type: "json" };
import a47 from "./app-definitions/wix.json" with { type: "json" };
import a48 from "./app-definitions/brex.json" with { type: "json" };
import a49 from "./app-definitions/clickhouse.json" with { type: "json" };
import a50 from "./app-definitions/egnyte.json" with { type: "json" };
import a51 from "./app-definitions/embat.json" with { type: "json" };
import a52 from "./app-definitions/mixpanel.json" with { type: "json" };
import a53 from "./app-definitions/postman.json" with { type: "json" };
import a54 from "./app-definitions/razorpay.json" with { type: "json" };
import a55 from "./app-definitions/sanity.json" with { type: "json" };
import a56 from "./app-definitions/stripe.json" with { type: "json" };
import a57 from "./app-definitions/supabase.json" with { type: "json" };
import a58 from "./app-definitions/ticket-tailor.json" with { type: "json" };
import a59 from "./app-definitions/asana.json" with { type: "json" };
import a60 from "./app-definitions/box.json" with { type: "json" };
import a61 from "./app-definitions/mem0.json" with { type: "json" };
import a62 from "./app-definitions/pagerduty.json" with { type: "json" };
import a63 from "./app-definitions/similarweb.json" with { type: "json" };
import a64 from "./app-definitions/xero.json" with { type: "json" };
import a65 from "./app-definitions/youcom.json" with { type: "json" };
import a66 from "./app-definitions/fireflies.json" with { type: "json" };
import a67 from "./app-definitions/zep.json" with { type: "json" };
import a68 from "./app-definitions/supermemory.json" with { type: "json" };
import a69 from "./app-definitions/honcho.json" with { type: "json" };
import a70 from "./app-definitions/neon.json" with { type: "json" };
import a71 from "./app-definitions/superagent.json" with { type: "json" };
import a72 from "./app-definitions/telem.json" with { type: "json" };
import a73 from "./app-definitions/gauge.json" with { type: "json" };
import a74 from "./app-definitions/tavily.json" with { type: "json" };
import a75 from "./app-definitions/calendly.json" with { type: "json" };
import a76 from "./app-definitions/exa.json" with { type: "json" };
import a77 from "./app-definitions/firecrawl.json" with { type: "json" };
import a78 from "./app-definitions/parallel-search.json" with { type: "json" };
import a79 from "./app-definitions/windsor-ai.json" with { type: "json" };
import a80 from "./app-definitions/gsc-wizard.json" with { type: "json" };
import a81 from "./app-definitions/clickup.json" with { type: "json" };
import a82 from "./app-definitions/klaviyo.json" with { type: "json" };
import a83 from "./app-definitions/ditto.json" with { type: "json" };
import a84 from "./app-definitions/braintrust.json" with { type: "json" };
import a85 from "./app-definitions/circleback.json" with { type: "json" };
import a86 from "./app-definitions/google-workspace.json" with { type: "json" };
import a87 from "./app-definitions/gmail.json" with { type: "json" };
import a88 from "./app-definitions/google-drive.json" with { type: "json" };
import a89 from "./app-definitions/google-docs.json" with { type: "json" };
import a90 from "./app-definitions/google-sheets.json" with { type: "json" };
import a91 from "./app-definitions/google-slides.json" with { type: "json" };
import a92 from "./app-definitions/google-calendar.json" with { type: "json" };
import a93 from "./app-definitions/google-chat.json" with { type: "json" };
import a94 from "./app-definitions/google-people.json" with { type: "json" };
import a95 from "./app-definitions/google-workspace-search.json" with { type: "json" };
import a96 from "./app-definitions/openai.json" with { type: "json" };
import a97 from "./app-definitions/openrouter.json" with { type: "json" };
import a98 from "./app-definitions/xai.json" with { type: "json" };
import a99 from "./app-definitions/google.json" with { type: "json" };
import a100 from "./app-definitions/bedrock.json" with { type: "json" };
import a101 from "./app-definitions/responses-api.json" with { type: "json" };
import a102 from "./app-definitions/messages-api.json" with { type: "json" };
import a103 from "./app-definitions/chat-completions-api.json" with { type: "json" };
import a104 from "./app-definitions/local.json" with { type: "json" };
import a105 from "./app-definitions/1password.json" with { type: "json" };
import a106 from "./app-definitions/daytona.json" with { type: "json" };
import a107 from "./app-definitions/monday.json" with { type: "json" };
import a108 from "./app-definitions/paperclip-notebook.json" with { type: "json" };
import a109 from "./app-definitions/unikraft.json" with { type: "json" };
import a110 from "./app-definitions/speko.json" with { type: "json" };
import type { AppDefinition } from "./types/app-definition.js";
export const APP_DEFINITIONS=[a0,a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15,a16,a17,a18,a19,a20,a21,a22,a23,a24,a25,a26,a27,a28,a29,a30,a31,a32,a33,a34,a35,a36,a37,a38,a39,a40,a41,a42,a43,a44,a45,a46,a47,a48,a49,a50,a51,a52,a53,a54,a55,a56,a57,a58,a59,a60,a61,a62,a63,a64,a65,a66,a67,a68,a69,a70,a71,a72,a73,a74,a75,a76,a77,a78,a79,a80,a81,a82,a83,a84,a85,a86,a87,a88,a89,a90,a91,a92,a93,a94,a95,a96,a97,a98,a99,a100,a101,a102,a103,a104,a105,a106,a107,a108,a109,a110] as AppDefinition[];