mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 21:34:48 +01:00
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>
This commit is contained in:
1 parent
6a24b417c0
commit
8ff45c0fa9
67 files changed
+3865
-134
No files matched your search
@@ -14,6 +14,8 @@ describe("tool app gallery URL matching", () => {
|
||||
expect(getAppDefinitionForUrl("https://workspace.google.com/")?.slug).toBe("google-workspace");
|
||||
expect(getAppDefinitionForUrl("https://mcp.neon.tech/mcp")?.slug).toBe("neon");
|
||||
expect(getAppDefinitionForUrl("https://app.withgauge.com/mcp")?.slug).toBe("gauge");
|
||||
expect(getAppDefinitionForUrl("https://circleback.ai/api/mcp")?.slug).toBe("circleback");
|
||||
expect(getAppDefinitionForUrl("https://app.circleback.ai/api/mcp")?.slug).toBe("circleback");
|
||||
expect(getAppDefinitionForUrl("https://api.dittowords.com/v2/mcp")?.slug).toBe("ditto");
|
||||
expect(getAppDefinitionForUrl("https://www.superagent.sh/mcp")?.slug).toBe("superagent");
|
||||
});
|
||||
|
||||
@@ -83,30 +83,31 @@ 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/google-workspace.json" with { type: "json" };
|
||||
import a86 from "./app-definitions/gmail.json" with { type: "json" };
|
||||
import a87 from "./app-definitions/google-drive.json" with { type: "json" };
|
||||
import a88 from "./app-definitions/google-docs.json" with { type: "json" };
|
||||
import a89 from "./app-definitions/google-sheets.json" with { type: "json" };
|
||||
import a90 from "./app-definitions/google-slides.json" with { type: "json" };
|
||||
import a91 from "./app-definitions/google-calendar.json" with { type: "json" };
|
||||
import a92 from "./app-definitions/google-chat.json" with { type: "json" };
|
||||
import a93 from "./app-definitions/google-people.json" with { type: "json" };
|
||||
import a94 from "./app-definitions/google-workspace-search.json" with { type: "json" };
|
||||
import a95 from "./app-definitions/openai.json" with { type: "json" };
|
||||
import a96 from "./app-definitions/openrouter.json" with { type: "json" };
|
||||
import a97 from "./app-definitions/xai.json" with { type: "json" };
|
||||
import a98 from "./app-definitions/google.json" with { type: "json" };
|
||||
import a99 from "./app-definitions/bedrock.json" with { type: "json" };
|
||||
import a100 from "./app-definitions/responses-api.json" with { type: "json" };
|
||||
import a101 from "./app-definitions/messages-api.json" with { type: "json" };
|
||||
import a102 from "./app-definitions/chat-completions-api.json" with { type: "json" };
|
||||
import a103 from "./app-definitions/local.json" with { type: "json" };
|
||||
import a104 from "./app-definitions/1password.json" with { type: "json" };
|
||||
import a105 from "./app-definitions/daytona.json" with { type: "json" };
|
||||
import a106 from "./app-definitions/monday.json" with { type: "json" };
|
||||
import a107 from "./app-definitions/paperclip-notebook.json" with { type: "json" };
|
||||
import a108 from "./app-definitions/unikraft.json" with { type: "json" };
|
||||
import a109 from "./app-definitions/speko.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] as AppDefinition[];
|
||||
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[];
|
||||
@@ -294,7 +294,7 @@ describe("AppDefinition catalog", () => {
|
||||
"google-workspace-search",
|
||||
]),
|
||||
);
|
||||
expect(SELF_SERVE_MCP_CANDIDATES).toHaveLength(65);
|
||||
expect(SELF_SERVE_MCP_CANDIDATES).toHaveLength(66);
|
||||
expect(BLOCKED_MCP_PROVIDERS.map((entry) => entry.slug)).toEqual([
|
||||
"g2",
|
||||
"vercel",
|
||||
@@ -460,15 +460,15 @@ describe("AppDefinition catalog", () => {
|
||||
expect(channel("slack")?.guidanceMd).toContain("reactions");
|
||||
expect(channel("slack")?.guidanceMd).toContain("direct messages");
|
||||
});
|
||||
it("keeps a complete, unique, dated evidence ledger for all 69 researched MCP providers", () => {
|
||||
it("keeps a complete, unique, dated evidence ledger for all 70 researched MCP providers", () => {
|
||||
// Ledger-wide date reflects the last full re-verification (2026-08-26);
|
||||
// later provider additions carry their own research evidence, but
|
||||
// bumping the shared date would overstate freshness for the other providers.
|
||||
expect(SELF_SERVE_MCP_RESEARCH.verifiedAt).toBe("2026-08-26");
|
||||
expect(SELF_SERVE_MCP_RESEARCH.entries).toHaveLength(69);
|
||||
expect(SELF_SERVE_MCP_RESEARCH.entries).toHaveLength(70);
|
||||
expect(
|
||||
new Set(SELF_SERVE_MCP_RESEARCH.entries.map((entry) => entry.slug)),
|
||||
).toHaveProperty("size", 69);
|
||||
).toHaveProperty("size", 70);
|
||||
for (const entry of SELF_SERVE_MCP_RESEARCH.entries) {
|
||||
expect(new URL(entry.docsUrl).protocol).toBe("https:");
|
||||
expect(new URL(entry.serverUrl).protocol).toBe("https:");
|
||||
@@ -905,7 +905,7 @@ describe("AppDefinition catalog", () => {
|
||||
"ticktick",
|
||||
"xero",
|
||||
]);
|
||||
expect(APP_STORE_DEFINITIONS).toHaveLength(88);
|
||||
expect(APP_STORE_DEFINITIONS).toHaveLength(89);
|
||||
const connectableSlugs = new Set(
|
||||
CONNECTABLE_APP_DEFINITIONS.map((entry) => entry.slug),
|
||||
);
|
||||
@@ -1340,6 +1340,37 @@ describe("AppDefinition catalog", () => {
|
||||
]);
|
||||
expect(method!.tenantFields?.[0]?.options?.map((option) => option.value)).toEqual(["dal", "fra", "sfo", "sin", "was"]);
|
||||
});
|
||||
it("connects Circleback's hosted server with browser sign-in and its documented read/write scopes", () => {
|
||||
const circleback = APP_DEFINITIONS.find((app) => app.slug === "circleback")!;
|
||||
expect(circleback).toMatchObject({
|
||||
name: "Circleback",
|
||||
categories: ["productivity"],
|
||||
urlPatterns: ["https://circleback.ai/*", "https://app.circleback.ai/*"],
|
||||
docsUrl: "https://circleback.ai/docs/support/platform/circleback-mcp",
|
||||
branding: { logoUrl: "/brands/apps/circleback.png" },
|
||||
redirectConstraints: "https-or-loopback-http",
|
||||
});
|
||||
expect(APP_STORE_DEFINITIONS.some((app) => app.slug === "circleback")).toBe(true);
|
||||
expect(CONNECTABLE_APP_DEFINITIONS.some((app) => app.slug === "circleback")).toBe(true);
|
||||
// Circleback documents no API key for its MCP server.
|
||||
expect(circleback.methods).toHaveLength(1);
|
||||
expect(circleback.methods[0]).toMatchObject({
|
||||
key: "mcp-oauth",
|
||||
label: "Sign in with Circleback",
|
||||
transport: "mcp_remote",
|
||||
auth: "oauth",
|
||||
ownershipModes: ["dcr"],
|
||||
riskTier: "S3",
|
||||
// `user` alone is read-only; write tools then ask the user to reconnect.
|
||||
defaults: { serverUrl: "https://circleback.ai/api/mcp", scopesHint: ["user", "user:write"] },
|
||||
capabilityProfile: { key: "write", description: expect.stringContaining("Set share and delete actions to Ask first") },
|
||||
});
|
||||
expect(circleback.methods[0]!.tenantFields ?? []).toEqual([]);
|
||||
expect(circleback.methods[0]!.warnings).toEqual([
|
||||
expect.stringContaining("A Circleback account"),
|
||||
expect.stringContaining("anyone with the link"),
|
||||
]);
|
||||
});
|
||||
it("connects Gauge's hosted server with browser sign-in or an organization API key", () => {
|
||||
const gauge = APP_DEFINITIONS.find((app) => app.slug === "gauge")!;
|
||||
expect(gauge).toMatchObject({
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"slug": "circleback",
|
||||
"name": "Circleback",
|
||||
"description": "Search meeting notes, transcripts, action items, calendar events and emails, and show meetings as cards in chat.",
|
||||
"categories": [
|
||||
"productivity"
|
||||
],
|
||||
"featured": false,
|
||||
"branding": {
|
||||
"logoUrl": "/brands/apps/circleback.png"
|
||||
},
|
||||
"urlPatterns": [
|
||||
"https://circleback.ai/*",
|
||||
"https://app.circleback.ai/*"
|
||||
],
|
||||
"docsUrl": "https://circleback.ai/docs/support/platform/circleback-mcp",
|
||||
"redirectConstraints": "https-or-loopback-http",
|
||||
"methods": [
|
||||
{
|
||||
"key": "mcp-oauth",
|
||||
"label": "Sign in with Circleback",
|
||||
"transport": "mcp_remote",
|
||||
"auth": "oauth",
|
||||
"ownershipModes": [
|
||||
"dcr"
|
||||
],
|
||||
"whenToUse": "Use browser sign-in for Circleback's hosted MCP server.",
|
||||
"defaults": {
|
||||
"serverUrl": "https://circleback.ai/api/mcp",
|
||||
"scopesHint": [
|
||||
"user",
|
||||
"user:write"
|
||||
]
|
||||
},
|
||||
"guidanceMd": "Sign in to Circleback and approve access. The connection acts as the Circleback user who signs in and sees the meetings, action items, calendar events and connected email that user can see. Write tools start enabled and remain governed by Paperclip's action policies.",
|
||||
"warnings": [
|
||||
"A Circleback account. The connection reads the signed-in user's meetings, transcripts, calendar and connected email.",
|
||||
"Circleback share tools can share meetings and folders with other people or anyone with the link, and delete tools cannot be undone. Set share and delete actions to Ask first before agents run unattended."
|
||||
],
|
||||
"consoleLinks": {
|
||||
"docs": "https://circleback.ai/docs/support/platform/circleback-mcp"
|
||||
},
|
||||
"riskTier": "S3",
|
||||
"capabilityProfile": {
|
||||
"key": "write",
|
||||
"label": "Read and write",
|
||||
"description": "Search and read meetings, transcripts, action items, calendar events and email, and manage action items, tags, folders and meeting notes. Circleback share tools can share meetings and folders with other people or anyone with the link, and delete tools cannot be undone. Set share and delete actions to Ask first before agents run unattended."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -2961,3 +2961,4 @@ export {
|
||||
issueActivityChangesTaskIdentity,
|
||||
} from "./issue-activity-identity.js";
|
||||
export { recognizeLinkPreview, type LinkPreviewTarget, type LinkPreviewState, type LinkPreview, type LinkPreviewResult } from "./link-preview.js";
|
||||
export * from "./mcp-apps.js";
|
||||
@@ -0,0 +1,92 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
MCP_APP_MIME_TYPE,
|
||||
buildMcpAppCsp,
|
||||
mcpAppToolCallableFromApp,
|
||||
mcpAppToolVisibleToModel,
|
||||
readMcpAppResource,
|
||||
readMcpAppToolUi,
|
||||
sanitizeMcpAppCspSource,
|
||||
} from "./mcp-apps.js";
|
||||
|
||||
describe("readMcpAppToolUi", () => {
|
||||
it("reads _meta.ui.resourceUri with the default visibility", () => {
|
||||
expect(readMcpAppToolUi({ ui: { resourceUri: "ui://circleback/meetings" } })).toEqual({
|
||||
resourceUri: "ui://circleback/meetings",
|
||||
visibility: ["model", "app"],
|
||||
});
|
||||
});
|
||||
|
||||
it("accepts the deprecated flat key and an explicit visibility", () => {
|
||||
expect(readMcpAppToolUi({ "ui/resourceUri": "ui://x/view" })?.resourceUri).toBe("ui://x/view");
|
||||
const appOnly = readMcpAppToolUi({ ui: { resourceUri: "ui://x/view", visibility: ["app", "bogus"] } });
|
||||
expect(appOnly?.visibility).toEqual(["app"]);
|
||||
expect(mcpAppToolVisibleToModel(appOnly)).toBe(false);
|
||||
expect(mcpAppToolCallableFromApp(appOnly)).toBe(true);
|
||||
});
|
||||
|
||||
it("keeps visibility for an app-only helper without a view", () => {
|
||||
const helper = readMcpAppToolUi({ ui: { visibility: ["app"] } });
|
||||
expect(helper).toEqual({ resourceUri: null, visibility: ["app"] });
|
||||
expect(mcpAppToolVisibleToModel(helper)).toBe(false);
|
||||
expect(mcpAppToolVisibleToModel(readMcpAppToolUi({ ui: { resourceUri: "https://evil.example", visibility: ["app"] } }))).toBe(false);
|
||||
expect(mcpAppToolVisibleToModel(readMcpAppToolUi({ ui: { visibility: [] } }))).toBe(false);
|
||||
});
|
||||
|
||||
it("ignores tools without a ui:// view", () => {
|
||||
expect(readMcpAppToolUi(undefined)).toBeNull();
|
||||
expect(readMcpAppToolUi({ ui: { resourceUri: "https://evil.example/view" } })).toBeNull();
|
||||
expect(mcpAppToolVisibleToModel(null)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("readMcpAppResource", () => {
|
||||
const uri = "ui://circleback/meetings";
|
||||
it("reads text content with its csp and border hints", () => {
|
||||
const resource = readMcpAppResource({
|
||||
contents: [{
|
||||
uri,
|
||||
mimeType: MCP_APP_MIME_TYPE,
|
||||
text: "<html><body>hi</body></html>",
|
||||
_meta: { ui: { csp: { resourceDomains: ["https://cdn.circleback.ai"] }, prefersBorder: false } },
|
||||
}],
|
||||
}, uri);
|
||||
expect(resource).toMatchObject({ html: "<html><body>hi</body></html>", prefersBorder: false, csp: { resourceDomains: ["https://cdn.circleback.ai"] } });
|
||||
});
|
||||
|
||||
it("decodes base64 blob content", () => {
|
||||
const blob = Buffer.from("<p>café</p>", "utf8").toString("base64");
|
||||
expect(readMcpAppResource({ contents: [{ uri, mimeType: "text/html; profile=mcp-app", blob }] }, uri)?.html).toBe("<p>café</p>");
|
||||
});
|
||||
|
||||
it("rejects other mime types and other resources", () => {
|
||||
expect(readMcpAppResource({ contents: [{ uri, mimeType: "text/html", text: "<p>x</p>" }] }, uri)).toBeNull();
|
||||
expect(readMcpAppResource({ contents: [{ uri: "ui://other", mimeType: MCP_APP_MIME_TYPE, text: "<p>x</p>" }] }, uri)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildMcpAppCsp", () => {
|
||||
it("defaults to no network access", () => {
|
||||
const csp = buildMcpAppCsp({});
|
||||
expect(csp).toContain("default-src 'none'");
|
||||
expect(csp).toContain("connect-src 'none'");
|
||||
expect(csp).toContain("frame-src 'none'");
|
||||
});
|
||||
|
||||
it("adds only well-formed https origins the server declared", () => {
|
||||
const csp = buildMcpAppCsp({
|
||||
connectDomains: ["https://api.circleback.ai", "https://x.com; script-src *", "http://insecure.example", "*"],
|
||||
resourceDomains: ["https://*.circleback.ai"],
|
||||
});
|
||||
expect(csp).toContain("connect-src https://api.circleback.ai;");
|
||||
expect(csp).toContain("script-src 'unsafe-inline' https://*.circleback.ai;");
|
||||
expect(csp).not.toContain("insecure");
|
||||
expect(csp).not.toMatch(/script-src \*/);
|
||||
});
|
||||
|
||||
it("sanitizes sources", () => {
|
||||
expect(sanitizeMcpAppCspSource("https://Example.COM/")).toBe("https://example.com");
|
||||
expect(sanitizeMcpAppCspSource("'unsafe-eval'")).toBeNull();
|
||||
expect(sanitizeMcpAppCspSource("https://a.com/path")).toBeNull();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,223 @@
|
||||
/**
|
||||
* 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("; ");
|
||||
}
|
||||
@@ -70,6 +70,7 @@
|
||||
{ "slug": "monday", "name": "monday.com", "wave": 2, "status": "blocked", "docsUrl": "https://developer.monday.com/api-reference/docs/integrate-with-monday-mcp", "serverUrl": "https://mcp.monday.com/mcp", "authMode": "provider_approval", "prerequisite": "Provider DCR rejects the Paperclip HTTPS callback with HTTP 400: redirect_uris are not allowed. Contact monday.com to allowlist the callback before OAuth setup; account-admin approval may also be needed.", "riskTier": "S4", "verifiedAt": "2026-10-09", "browserOnboarding": "blocked-callback-allowlist", "liveRead": "not-run", "blocker": "Provider callback allowlisting required" },
|
||||
{ "slug": "context7", "name": "Context7", "wave": 2, "status": "self_serve", "docsUrl": "https://context7.com/docs/api-guide", "serverUrl": "https://mcp.context7.com/mcp", "authMode": "public", "prerequisite": "No account or API key is required for anonymous remote MCP use; the official docs state anonymous requests have low rate limits. An optional API key raises limits and supports private repositories, but this curated method does not request or store one.", "riskTier": "S1", "verifiedAt": "2026-10-09", "browserOnboarding": "completed-public-no-auth", "liveRead": "passed: resolve-library-id and query-docs returned React public documentation; repeat query passed after reload with 0 agents selected", "liveWrite": "not-applicable", "blocker": null },
|
||||
{ "slug": "ditto", "name": "Ditto", "wave": 4, "status": "self_serve", "docsUrl": "https://developer.dittowords.com/guides/connect-the-mcp", "serverUrl": "https://api.dittowords.com/v2/mcp", "authMode": "dcr_or_api_key", "prerequisite": "A Ditto account in the workspace whose text and style guides agents should use. API keys require developer integrations on the Ditto plan.", "riskTier": "S4" },
|
||||
{ "slug": "braintrust", "name": "Braintrust", "wave": 4, "status": "self_serve", "docsUrl": "https://www.braintrust.dev/docs/integrations/developer-tools/mcp", "serverUrl": "https://api.braintrust.dev/mcp", "authMode": "dcr_or_api_key", "prerequisite": "A Braintrust account or API key. Select US or EU to match the organization’s data plane region. Account permissions bound access; evaluations and Topics processing may consume credits, dataset edits can permanently delete rows, and automation status can enable retention or delivery.", "riskTier": "S4", "verifiedAt": "2026-10-21", "browserOnboarding": "completed-oauth: US mcp-oauth authorized a temporary personal connection in an isolated instance; authenticated discovery returned 49 tools", "liveRead": "passed: US mcp-oauth bounded list_recent_objects and synthetic dataset sql_query readback through actual process-agent runs and run-scoped gateway sessions", "liveWrite": "passed: US mcp-oauth edit_dataset_rows inserted one synthetic row into a new disposable dataset through an actual process-agent gateway call; row and dataset removed", "blocker": "US API-key and both EU methods remain untested against real accounts. Live token expiry/refresh, provider-side OAuth revocation, and native CLI automatic capability delivery remain unqualified.", "evidenceLimit": "Public regional metadata probes confirmed endpoints, Streamable HTTP, DCR, PKCE S256, refresh-token support, and scope mcp without registration or account authorization. Separate US OAuth account proof passed connect, discovery, bounded read, synthetic write/readback, real process-agent gateway calls, catalog refresh, OAuth reconnect, local removal, post-removal denial, and structural API/log redaction. Token expiry/refresh was not forced; structural redaction did not decrypt tokens for exact-value scanning. The provider reported identity scopes despite the mcp request. See doc/connections/BRAINTRUST.md and braintrust-qualification-2026-10-21.json for method-specific proof and limits; metadata and fixtures do not qualify the remaining methods or lifecycle gaps." }
|
||||
{ "slug": "braintrust", "name": "Braintrust", "wave": 4, "status": "self_serve", "docsUrl": "https://www.braintrust.dev/docs/integrations/developer-tools/mcp", "serverUrl": "https://api.braintrust.dev/mcp", "authMode": "dcr_or_api_key", "prerequisite": "A Braintrust account or API key. Select US or EU to match the organization’s data plane region. Account permissions bound access; evaluations and Topics processing may consume credits, dataset edits can permanently delete rows, and automation status can enable retention or delivery.", "riskTier": "S4", "verifiedAt": "2026-10-21", "browserOnboarding": "completed-oauth: US mcp-oauth authorized a temporary personal connection in an isolated instance; authenticated discovery returned 49 tools", "liveRead": "passed: US mcp-oauth bounded list_recent_objects and synthetic dataset sql_query readback through actual process-agent runs and run-scoped gateway sessions", "liveWrite": "passed: US mcp-oauth edit_dataset_rows inserted one synthetic row into a new disposable dataset through an actual process-agent gateway call; row and dataset removed", "blocker": "US API-key and both EU methods remain untested against real accounts. Live token expiry/refresh, provider-side OAuth revocation, and native CLI automatic capability delivery remain unqualified.", "evidenceLimit": "Public regional metadata probes confirmed endpoints, Streamable HTTP, DCR, PKCE S256, refresh-token support, and scope mcp without registration or account authorization. Separate US OAuth account proof passed connect, discovery, bounded read, synthetic write/readback, real process-agent gateway calls, catalog refresh, OAuth reconnect, local removal, post-removal denial, and structural API/log redaction. Token expiry/refresh was not forced; structural redaction did not decrypt tokens for exact-value scanning. The provider reported identity scopes despite the mcp request. See doc/connections/BRAINTRUST.md and braintrust-qualification-2026-10-21.json for method-specific proof and limits; metadata and fixtures do not qualify the remaining methods or lifecycle gaps." },
|
||||
{ "slug": "circleback", "name": "Circleback", "wave": 4, "status": "self_serve", "docsUrl": "https://circleback.ai/docs/support/platform/circleback-mcp", "serverUrl": "https://circleback.ai/api/mcp", "authMode": "dcr", "prerequisite": "A Circleback account. The connection reads the signed-in user's meetings, transcripts, calendar and connected email.", "riskTier": "S3", "verifiedAt": "2026-11-12" }
|
||||
]
|
||||
}
|
||||
@@ -1,3 +1,4 @@
|
||||
import type { McpAppToolUi } from "../mcp-apps.js";
|
||||
import type {
|
||||
ConnectionTokenIssuanceOutcome,
|
||||
ConnectionTokenIssuancePath,
|
||||
@@ -568,6 +569,8 @@ export interface ToolCatalogEntry {
|
||||
inputSchema: Record<string, unknown> | null;
|
||||
outputSchema: Record<string, unknown> | null;
|
||||
annotations: Record<string, unknown> | null;
|
||||
/** MCP Apps view declaration (`_meta.ui`), when the tool renders one. */
|
||||
uiMeta?: McpAppToolUi | null;
|
||||
riskLevel: ToolRiskLevel;
|
||||
isReadOnly: boolean;
|
||||
isWrite: boolean;
|
||||
|
||||
Reference in new issue
Block a user