2f94a66ba1
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The inbox is where operators quickly scan which issues are active, blocked, or waiting for attention > - A blocked parent can still have active descendant work, but the inbox previously depended on only loaded rows to infer that state > - That made collapsed or partially loaded issue trees look more stuck than they really were > - This pull request carries live descendant summary data through the issue list API and inbox UI > - The benefit is a more accurate blocked-inbox signal, so operators can distinguish truly stalled work from blocked parents that still have live child activity ## Linked Issues or Issue Description No public GitHub issue was found for this exact inbox descendant-status polish. Feature request fields: **Subsystem affected** Cross-cutting: `server/`, `packages/shared`, plugin/MCP API surfaces, and `ui/` inbox rendering. **Problem or motivation** Inbox rows need to show when blocked or collapsed parents still have live descendant work, even when the live child row is not loaded in the current client tree. Without a server-provided descendant summary, a parent can look stalled even though active work continues below it. **Proposed solution** Expose an optional live descendant count on issue list results, request it from inbox views, and use it to render covered blocked status and live-below indicators. Keep the field opt-in so other issue list callers keep their existing payload shape and query cost. **Alternatives considered** Relying only on client-loaded subtree state was ruled out because it misses collapsed or unloaded descendants. Always returning the count was also avoided because most list callers do not need this extra summary. **Roadmap alignment** This is scoped operator-visibility polish for the existing inbox. It does not duplicate a named `ROADMAP.md` milestone. **Additional context** The recursive summary query is guarded against parent cycles, and the UI still falls back to loaded subtree live counts when server summary data is absent or stale. ## What Changed - Added optional `includeLiveDescendantSummary` support to issue list contracts, SDK surfaces, MCP tools, routes, services, and tests. - Added `liveDescendantCount` to issue list results when requested. - Updated inbox and blocked-inbox queries to request live descendant summaries. - Updated inbox row status rendering so blocked parents with live descendants show covered blocker treatment without duplicating the live-below chip. - Hardened live descendant summary traversal against parent cycles and preserved the loaded-subtree fallback path for blocked inbox rows. - Added focused tests for the API parameter, service behavior, helper logic, cycle handling, and inbox UI query/rendering behavior. ## Verification - `pnpm exec vitest run server/src/__tests__/issue-list-assignee-filter-routes.test.ts ui/src/lib/inbox-live-descendants.test.ts ui/src/components/IssueColumns.test.tsx ui/src/components/BlockedInboxView.test.tsx ui/src/pages/Inbox.test.tsx` - `pnpm --filter @paperclipai/ui typecheck` - Rebased cleanly onto current upstream `master` before pushing. - Confirmed the branch diff does not include `pnpm-lock.yaml` or `.github/workflows/*` changes. ## Risks Low to moderate risk. The new descendant count is opt-in on list requests, but it adds query work when the inbox asks for it. The recursive traversal now tracks visited ancestors to avoid cycle failures. The UI uses the server count as a supplement to existing loaded-tree state, so stale or absent counts fall back to the prior behavior. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, GPT-5 coding agent, tool-enabled with local shell and git access. Reasoning mode and context window are managed by the Paperclip/Codex runtime. ## 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge |
||
|---|---|---|
| .. | ||
| src | ||
| README.md | ||
| package.json | ||
| tsconfig.json | ||
| vitest.config.ts | ||
README.md
Paperclip MCP Server
Model Context Protocol server for Paperclip.
This package is a thin MCP wrapper over the existing Paperclip REST API. It does not talk to the database directly and it does not reimplement business logic.
Authentication
The server reads its configuration from environment variables:
PAPERCLIP_API_URL- Paperclip base URL, for examplehttp://localhost:3100PAPERCLIP_API_KEY- bearer token used for/apirequestsPAPERCLIP_COMPANY_ID- optional default company for company-scoped toolsPAPERCLIP_AGENT_ID- optional default agent for checkout helpersPAPERCLIP_RUN_ID- optional run id forwarded on mutating requests
Usage
npx -y @paperclipai/mcp-server
Or locally in this repo:
pnpm --filter @paperclipai/mcp-server build
node packages/mcp-server/dist/stdio.js
Tool Surface
Read tools:
paperclipMepaperclipInboxLitepaperclipListAgentspaperclipGetAgentpaperclipListIssuespaperclipGetIssuepaperclipGetHeartbeatContextpaperclipListCommentspaperclipGetCommentpaperclipListIssueApprovalspaperclipListDocumentspaperclipGetDocumentpaperclipListDocumentRevisionspaperclipListProjectspaperclipGetProjectpaperclipGetIssueWorkspaceRuntimepaperclipWaitForIssueWorkspaceServicepaperclipListGoalspaperclipGetGoalpaperclipListApprovalspaperclipGetApprovalpaperclipGetApprovalIssuespaperclipListApprovalComments
Write tools:
paperclipCreateIssuepaperclipUpdateIssuepaperclipCheckoutIssuepaperclipReleaseIssuepaperclipAddCommentpaperclipSuggestTaskspaperclipAskUserQuestionspaperclipRequestConfirmationpaperclipUpsertIssueDocumentpaperclipRestoreIssueDocumentRevisionpaperclipControlIssueWorkspaceServicespaperclipCreateApprovalpaperclipLinkIssueApprovalpaperclipUnlinkIssueApprovalpaperclipApprovalDecisionpaperclipAddApprovalComment
Escape hatch:
paperclipApiRequest
paperclipApiRequest is limited to paths under /api and JSON bodies. It is
meant for endpoints that do not yet have a dedicated MCP tool.