ake/paperclip
1
0
Fork 0
mirror of https://github.com/alkimake/paperclip.git synced 2026-06-14 01:50:39 +09:00
Code Issues Projects Releases Packages Wiki Activity
paperclip/packages/mcp-server/README.md
Dotta 09d0678840
[codex] Harden heartbeat scheduling and runtime controls (#4223) 
## Thinking Path

> - Paperclip orchestrates AI agents through issue checkout, heartbeat
runs, routines, and auditable control-plane state
> - The runtime path has to recover from lost local processes, transient
adapter failures, blocked dependencies, and routine coalescing without
stranding work
> - The existing branch carried several reliability fixes across
heartbeat scheduling, issue runtime controls, routine dispatch, and
operator-facing run state
> - These changes belong together because they share backend contracts,
migrations, and runtime status semantics
> - This pull request groups the control-plane/runtime slice so it can
merge independently from board UI polish and adapter sandbox work
> - The benefit is safer heartbeat recovery, clearer runtime controls,
and more predictable recurring execution behavior

## What Changed

- Adds bounded heartbeat retry scheduling, scheduled retry state, and
Codex transient failure recovery handling.
- Tightens heartbeat process recovery, blocker wake behavior, issue
comment wake handling, routine dispatch coalescing, and
activity/dashboard bounds.
- Adds runtime-control MCP tools and Paperclip skill docs for issue
workspace runtime management.
- Adds migrations `0061_lively_thor_girl.sql` and
`0062_routine_run_dispatch_fingerprint.sql`.
- Surfaces retry state in run ledger/agent UI and keeps related shared
types synchronized.

## Verification

- `pnpm exec vitest run
server/src/__tests__/heartbeat-retry-scheduling.test.ts
server/src/__tests__/heartbeat-process-recovery.test.ts
server/src/__tests__/routines-service.test.ts`
- `pnpm exec vitest run src/tools.test.ts` from `packages/mcp-server`

## Risks

- Medium risk: this touches heartbeat recovery and routine dispatch,
which are central execution paths.
- Migration order matters if split branches land out of order: merge
this PR before branches that assume the new runtime/routine fields.
- Runtime retry behavior should be watched in CI and in local operator
smoke tests because it changes how transient failures are resumed.

> 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-based coding agent runtime, shell/git tool use
enabled. Exact hosted model build and context window are not exposed in
this Paperclip heartbeat environment.

## 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
- [ ] 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
2026-04-21 12:24:11 -05:00

2 KiB
Raw Blame History

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 example http://localhost:3100
  • PAPERCLIP_API_KEY - bearer token used for /api requests
  • PAPERCLIP_COMPANY_ID - optional default company for company-scoped tools
  • PAPERCLIP_AGENT_ID - optional default agent for checkout helpers
  • PAPERCLIP_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:

  • paperclipMe
  • paperclipInboxLite
  • paperclipListAgents
  • paperclipGetAgent
  • paperclipListIssues
  • paperclipGetIssue
  • paperclipGetHeartbeatContext
  • paperclipListComments
  • paperclipGetComment
  • paperclipListIssueApprovals
  • paperclipListDocuments
  • paperclipGetDocument
  • paperclipListDocumentRevisions
  • paperclipListProjects
  • paperclipGetProject
  • paperclipGetIssueWorkspaceRuntime
  • paperclipWaitForIssueWorkspaceService
  • paperclipListGoals
  • paperclipGetGoal
  • paperclipListApprovals
  • paperclipGetApproval
  • paperclipGetApprovalIssues
  • paperclipListApprovalComments

Write tools:

  • paperclipCreateIssue
  • paperclipUpdateIssue
  • paperclipCheckoutIssue
  • paperclipReleaseIssue
  • paperclipAddComment
  • paperclipUpsertIssueDocument
  • paperclipRestoreIssueDocumentRevision
  • paperclipControlIssueWorkspaceServices
  • paperclipCreateApproval
  • paperclipLinkIssueApproval
  • paperclipUnlinkIssueApproval
  • paperclipApprovalDecision
  • paperclipAddApprovalComment

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.