forked from farhoodlabs/paperclip
Dotta
e400315cbf
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The issue graph and liveness recovery system decide whether assigned work is executable or parked > - Assigned issues created without an explicit status could silently land in backlog, making parents look blocked with no productive wake path > - The server, shared validators, recovery analysis, and UI all need to agree on that execution semantic > - This pull request makes assigned issue creation default to `todo`, flags assigned backlog blockers, and surfaces the state in the board > - The benefit is that parked assigned work becomes intentional and visible instead of creating silent liveness stalls ## What Changed - Adds contract tests for assigned issue creation defaults. - Defaults assigned issue creation to `todo` when status is omitted while preserving explicit `backlog` parking. - Exposes `resolveCreateIssueStatusDefault` through shared validators. - Teaches liveness/blocker attention paths to distinguish assigned backlog blockers. - Adds UI notices, row/header badges, and issue detail safeguards for assigned backlog blockers. - Adds Storybook fixtures and execution-semantics documentation for the assigned-backlog behavior. ## Verification - `pnpm run preflight:workspace-links && pnpm exec vitest run packages/shared/src/validators/issue.test.ts server/src/__tests__/issue-assigned-backlog-contract-routes.test.ts server/src/__tests__/issue-blocker-attention.test.ts server/src/__tests__/issue-liveness.test.ts server/src/__tests__/heartbeat-issue-liveness-escalation.test.ts ui/src/components/IssueAssignedBacklogNotice.test.tsx ui/src/components/IssueRow.test.tsx` — 50 passed, 23 skipped. - Skipped tests were embedded Postgres suites on this host with the repo skip message: `Postgres init script exited with code null. Please check the logs for extra info. The data directory might already exist.` - Pairwise merge check against the issue-controls PR branch completed without conflicts via `git merge --no-commit --no-ff` in a temporary worktree. - Screenshots for assigned-backlog UI states: [light](docs/pr-screenshots/pr-5428/assigned-backlog-light.png), [dark](docs/pr-screenshots/pr-5428/assigned-backlog-dark.png). - Follow-up checks: `pnpm --filter /ui typecheck`; `pnpm --filter /mcp-server build`; `pnpm --filter /mcp-server test`; `pnpm exec vitest run packages/shared/src/validators/issue.test.ts`; focused UI component tests. - Remote PR checks on head `6300b3c`: policy, verify, serialized server shards 1/4-4/4, Canary Dry Run, e2e, Greptile Review, and Snyk all passed. ## Risks - Medium: changes status defaulting for assigned issue creation when the caller omits status. Explicit `backlog` remains supported, and server/shared tests cover both paths. - Medium: liveness classification changes can affect blocker attention labels; focused service and UI tests cover the new assigned-backlog state. > 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 coding agent, GPT-5 model family (`gpt-5`), tool-enabled Paperclip heartbeat environment. Context window and internal reasoning mode are not exposed by the 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
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.