Files
PaperClipAI/server/src/routes/mcp-apps.ts
T
DottaandClaude Opus 5.5 a726dce4f0 feat(mcp): show live progress for long connected-app tool calls in the task chat (#21449)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents call tools from connected apps through the Paperclip MCP
gateway
> - Some tool calls take a long time: exports, builds, large searches
> - The MCP progress utility lets an app report how far a call is, but
Paperclip ignored it
> - So the task chat showed only a spinner until the call finished, with
no sign of life
> - This pull request reads the app's progress and shows it on the
tool's row while the call runs
> - The benefit is that people can see that a long call is working, how
far it is, and how long it has run

## Linked Issues or Issue Description

**Subsystem affected**
Connected apps (MCP gateway) and the task chat.

**Problem or motivation**
A long tool call from a connected MCP app shows only a spinner in the
task chat. Paperclip does not send a `progressToken`, and it drops
`notifications/progress` from the app.

**Proposed solution**
Send a `progressToken` on each `tools/call` that an agent run makes.
Read the app's progress notifications from the call's response stream.
Show a progress bar (or an indeterminate sweep), the latest message, and
elapsed time on the running tool row. Keep the latest state so that a
reload mid-call shows it.

**Alternatives considered**
A new transport for progress. The existing company live-events socket
already carries per-run events with run read checks, so this change uses
it.

**Additional context**
Spec:
https://modelcontextprotocol.io/specification/2026-07-28/basic/utilities/progress

## What Changed

- `mcp-http.ts`: `mcpHttpRequestInit` can add `_meta.progressToken`.
`readMcpHttpResponse` gives each notification on the response stream to
an observer before the result. The observer cannot fail or delay the
call. New `mcpProgressNotificationOf` matches a notification to its
token.
- `tool-gateway.ts`: remote HTTP and local stdio `tools/call` from an
agent run send a per-call token and forward progress to a reporter.
Calls without a run send no token.
- New `server/src/services/tool-call-progress.ts`: checks each update
(finite, increasing, plain single-line text of at most 200 characters).
It publishes a `heartbeat.run.tool_progress` live event at most every
250 ms (latest wins) and saves the latest update on the invocation at
most every 1 s. Nothing is awaited by the call. A final `done` event
goes out when the call ends.
- DB: nullable `tool_invocations.progress` jsonb column (migration
`0479`, `ADD COLUMN` only). A save never writes onto a finished call.
- Live delivery: the new event follows its run like transcript output. A
client gets it only for runs it follows, after the run read check, in
the run's company only.
- New route `GET /api/issues/:issueId/tool-call-progress` (task read
check) returns the latest progress of the task's running calls, for a
reload mid-call. Documented in `docs/api/issues.md`.
- UI: `ToolCallProgressProvider` (one per chat) keeps the latest update
per call. A running tool row subscribes and shows a bar or sweep, the
message, the percent and elapsed time (design tokens, reduced motion
honored). Finished rows drop it and never fetch or re-render for
progress. `LiveUpdatesProvider` ignores the event for query
invalidation.
- `packages/kv-demo-mcp-server`: new `slow_with_progress` demo tool
(`steps`, `stepMs`, `withTotal`) in its own file.
- Storybook: `Tasks/Tool progress` stories (running with total, running
without total, done).
- Docs: new `doc/connections/MCP-PROGRESS.md`;
`MCP-PROTOCOL-VERSIONS.md` no longer lists progress as unsupported.

## Verification

- Red/green: on the original source, 5 of the new server tests fail
(token in `_meta`, SSE with interleaved progress and result,
notification matching, run-interest delivery, gateway end-to-end). With
this change they pass.
- `server/src/__tests__/mcp-http.test.ts` (13),
`tool-call-progress.test.ts` (9: throttling, latest wins, bounded text,
out-of-order drop, finish, failures never throw, company/run/tool
scoping), `tool-call-progress-store.test.ts` (2, embedded Postgres:
company and task scoping, no write onto a finished call),
`realtime/live-event-delivery.test.ts` (run interest),
`tool-gateway.test.ts` end-to-end against the real SDK kv demo server
over Streamable HTTP: 6 provider updates over about 1.2 s give 3 to 7
throttled events, all for the right company, run, task and tool, the
last one `done`; no event reaches another company; the invocation keeps
the progress; the result is unchanged.
- UI: `tool-call-progress.test.tsx` (10: name matching, row states,
plain-text rendering, drop on complete, restore after reload, no fetch
for finished rows). All 67 task-chat test files pass.
- `packages/kv-demo-mcp-server`: 13 tests, including progress over HTTP
with and without a total.
- Storybook: checked the three stories in a browser. The bar fills to
40%, the sweep animates, the elapsed time ticks, and the done row shows
no progress.
- `pnpm verify`: see the CI checks for the final revision.

## Risks

- Low. The migration adds one nullable column.
- An SSE response is now bounded per message, not per stream, so handled
notifications (such as progress) do not use up the result's size limit.
Each message is still bounded.
- Progress code runs only while a run's tool call is in flight. It adds
a few bytes to the request and throttled, fire-and-forget work. Agent
boot and time to first token do not change.
- A row finds its call by run and tool name. If one run calls the same
tool twice at the same time, both rows show the newer call's progress.
- Progress from a call that became an MCP Task is not shown.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use
and code execution.

## 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-13 20:14:22 -06:00

201 lines
8.6 KiB
TypeScript

import { Router, type Request, type Response } from "express";
import { and, eq } from "drizzle-orm";
import { z } from "zod";
import { issueComments, issues, type Db } from "@paperclipai/db";
import {
mcpAppMessageSentSchema,
mcpAppModelContextUpdateSchema,
normalizeMcpAppModelContext,
type McpAppModelContext,
type McpAppViewDetail,
} from "@paperclipai/shared";
import { validate } from "../middleware/validate.js";
import { logActivity } from "../services/index.js";
import { assertBoard, getAccessibleResource } from "./authz.js";
import { connectionRequestUserId } from "./connection-management-authz.js";
import { authorizationService } from "../services/authorization.js";
import { mcpAppViewsService, toMcpAppViewSummary } from "../services/mcp-app-views.js";
import { listToolCallProgress } from "../services/tool-call-progress.js";
import { ToolGatewayHttpError, type ToolGatewayService } from "../services/tool-gateway.js";
const uuidSchema = z.string().uuid();
type McpAppIssue = { id: string; companyId: string; status: string; assigneeAgentId: string | null; assigneeUserId: string | null };
/** A view can only attribute a comment the viewer sent moments ago. */
const MESSAGE_ATTRIBUTION_WINDOW_MS = 10 * 60_000;
type McpAppsGateway = Pick<ToolGatewayService, "readMcpAppViewResource">;
/**
* MCP Apps views in the task chat. Viewing follows task read access. A view's
* own tool calls are served by the tool-access router, which applies the
* connection test-call authorization.
*/
export function mcpAppsRoutes(db: Db, toolGateway: McpAppsGateway) {
const router = Router();
const views = mcpAppViewsService(db);
const readableTask = async (req: Request, res: Response, next: () => void) => {
assertBoard(req);
if (!uuidSchema.safeParse(req.params.issueId).success) {
res.status(404).json({ error: "Task not found" });
return;
}
const [issue] = await db.select({
id: issues.id, companyId: issues.companyId, status: issues.status,
assigneeAgentId: issues.assigneeAgentId, assigneeUserId: issues.assigneeUserId,
}).from(issues)
.where(eq(issues.id, req.params.issueId as string)).limit(1);
if (!(await getAccessibleResource(req, res, issue, "Task not found"))) return;
// Company access is not enough: private tasks also need task read access.
const readable = await authorizationService(db).decide({ actor: req.actor, action: "issue:read", resource: {
type: "issue", companyId: issue.companyId, issueId: issue.id,
} });
if (!readable.allowed) {
res.status(404).json({ error: "Task not found" });
return;
}
res.locals.mcpAppIssue = issue;
res.setHeader("Cache-Control", "no-store");
next();
};
router.use("/issues/:issueId/mcp-app-views", readableTask);
router.use("/issues/:issueId/tool-call-progress", readableTask);
async function viewFor(req: Request, res: Response) {
const issue = res.locals.mcpAppIssue as { id: string; companyId: string };
const viewId = req.params.viewId as string;
const view = uuidSchema.safeParse(viewId).success ? await views.get(issue.companyId, viewId) : null;
if (!view || view.issueId !== issue.id) {
res.status(404).json({ error: "View not found" });
return null;
}
return { issue, view };
}
function sendGatewayError(res: Response, error: unknown) {
if (error instanceof ToolGatewayHttpError) {
res.status(error.status).json({ error: error.message, reasonCode: error.reasonCode });
return true;
}
return false;
}
/**
* Acting on a view for the agent (its context, its messages) is the viewer's
* own act on the task: a signed-in person who may comment on it. Agents,
* board API keys and MCP clients cannot.
*/
async function viewerWhoMayComment(req: Request, res: Response): Promise<string | null> {
const issue = res.locals.mcpAppIssue as McpAppIssue;
// A person in the app, not a board API key or an MCP client acting for them.
const interactive = req.actor.source === "session" || req.actor.source === "local_implicit" || req.actor.source === "cloud_tenant";
const userId = req.actor.type === "board" && interactive ? req.actor.userId : undefined;
if (!userId) {
res.status(403).json({ error: "Only a signed-in person viewing the task can do this" });
return null;
}
const decision = await authorizationService(db).decide({ actor: req.actor, action: "issue:comment", resource: {
type: "issue", companyId: issue.companyId, issueId: issue.id, status: issue.status,
assigneeAgentId: issue.assigneeAgentId, assigneeUserId: issue.assigneeUserId,
} });
if (!decision.allowed) {
res.status(403).json({ error: "You can't comment on this task" });
return null;
}
return userId;
}
// `ui/update-model-context`: the view's latest context, given to the task's next run.
router.put("/issues/:issueId/mcp-app-views/:viewId/model-context", validate(mcpAppModelContextUpdateSchema), async (req, res) => {
const found = await viewFor(req, res);
if (!found) return;
const userId = await viewerWhoMayComment(req, res);
if (!userId) return;
let context: McpAppModelContext | null;
try {
context = normalizeMcpAppModelContext(req.body);
} catch (error) {
res.status(413).json({ error: error instanceof Error ? error.message : "App context is too large" });
return;
}
const changed = await views.setModelContext(found.issue.companyId, found.view.id, context);
if (changed) {
await logActivity(db, {
companyId: found.issue.companyId, actorType: "user", actorId: userId,
action: "issue.mcp_app_context_updated", entityType: "issue", entityId: found.issue.id,
details: {
viewId: found.view.id, applicationName: found.view.applicationName, toolName: found.view.upstreamToolName,
cleared: context === null,
},
});
}
res.json({ updated: changed });
});
/**
* `ui/message`: the viewer approved a view's proposed message and sent it as
* their own comment through the task's normal comment path. This records
* that the comment came from the view.
*/
router.post("/issues/:issueId/mcp-app-views/:viewId/messages", validate(mcpAppMessageSentSchema), async (req, res) => {
const found = await viewFor(req, res);
if (!found) return;
const userId = await viewerWhoMayComment(req, res);
if (!userId) return;
const [comment] = await db.select({ id: issueComments.id, createdAt: issueComments.createdAt }).from(issueComments)
.where(and(
eq(issueComments.clientRequestId, req.body.clientRequestId),
eq(issueComments.companyId, found.issue.companyId),
eq(issueComments.issueId, found.issue.id),
eq(issueComments.authorUserId, userId),
)).limit(1);
if (!comment || Date.now() - comment.createdAt.getTime() > MESSAGE_ATTRIBUTION_WINDOW_MS) {
res.status(404).json({ error: "Comment not found" });
return;
}
await logActivity(db, {
companyId: found.issue.companyId, actorType: "user", actorId: userId,
action: "issue.mcp_app_message_sent", entityType: "issue", entityId: found.issue.id,
details: {
commentId: comment.id, viewId: found.view.id,
applicationName: found.view.applicationName, toolName: found.view.upstreamToolName,
},
});
res.status(201).json({ commentId: comment.id });
});
// The latest progress of the task's running app tool calls (and recently finished ones, as done), for a reload mid-call.
router.get("/issues/:issueId/tool-call-progress", async (_req, res) => {
const issue = res.locals.mcpAppIssue as { id: string; companyId: string };
res.json(await listToolCallProgress(db, issue.companyId, issue.id));
});
router.get("/issues/:issueId/mcp-app-views", async (req, res) => {
const issue = res.locals.mcpAppIssue as { id: string; companyId: string };
res.json(await views.listForIssue(issue.companyId, issue.id));
});
router.get("/issues/:issueId/mcp-app-views/:viewId", async (req, res) => {
const found = await viewFor(req, res);
if (!found) return;
try {
const resource = await toolGateway.readMcpAppViewResource({
companyId: found.issue.companyId,
userId: connectionRequestUserId(req) ?? "board",
view: found.view,
});
const detail: McpAppViewDetail = {
...toMcpAppViewSummary(found.view),
toolResult: found.view.toolResult as unknown as McpAppViewDetail["toolResult"],
resource,
};
res.json(detail);
} catch (error) {
if (!sendGatewayError(res, error)) throw error;
}
});
return router;
}