mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-09 16:35:27 +02:00
Dotta
9036d3c484
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Native providers can receive only the semantic operations authorized for one run. > - Codex ACP consumes those operations through an MCP endpoint. > - The endpoint must be private, authenticated, bounded, and deterministic under retries. > - It must not advertise runner-private operations or allow callers to replace terminal-result schemas. > - This pull request adds a provider-neutral loopback MCP bridge with those controls. ## Linked Issues or Issue Description **What would you like to improve?** The runner has a run-scoped semantic catalog and dispatcher, but the ACPX runtime needs a secure transport for that catalog. A generic local MCP server could expose extra operations, accept ambiguous tool definitions, or execute the same call twice after a retry. **Why is this important?** Semantic tool presence is part of the authorization boundary. Undiscoverable operations must remain unavailable. Terminal completion and blocked-result schemas must not be replaceable. Duplicate call identities must be idempotent, and conflicting duplicates must fail closed. **Suggested approach** Bind one MCP endpoint to `127.0.0.1` for each admitted runtime. Require a random bearer secret. Compile the closed tool schemas before listening. Keep private operations out of `tools/list`. Validate and fingerprint each call before dispatch. Bound request size, result size, time, and retained call identities. Abort active operations on timeout, cancellation, or bridge close. **Additional context** #12401 is merged. This PR does not attach the bridge to ACPX, register a provider, or change any server or direct-adapter behavior. ## What Changed - Add a provider-neutral runner semantic MCP bridge bound only to IPv4 loopback. - Require constant-time bearer authentication before MCP operations. - Expose only the supplied public catalog plus fixed completion and blocked-result tools. - Keep runner-private operations callable by trusted extensions but absent from discovery. - Reject invalid names, duplicate definitions, public/private collisions, and terminal schema replacement. - Compile JSON Schema validators before accepting traffic. - Validate calls before dispatch and replay identical duplicate identities exactly once. - Treat numeric and string JSON-RPC identities as distinct and reject conflicting duplicates. - Bound request bodies, result text, timeouts, retained identities, and concurrent capacity. - Terminate oversized request bodies, preserve successful mutation outcomes, and keep complete semantic results. - Propagate MCP cancellation and abort active calls during close. ## Verification - Exact verified head: `e5070e235448680e480e8d3f66bb46ac62d71c8e`. - Full GitHub PR workflow passed in [run 33342776925](https://github.com/paperclipai/paperclip/actions/runs/33342776925), including runner verification/build, typecheck, all test shards, canary, and e2e. - Greptile is 5/5 on the exact head with zero unresolved review threads. - Superagent Security, Snyk, contributor trust, and commitperclip passed on the exact head. - Storybook skipped by path as expected. - The diff contains 2 files and does not change dependencies, `pnpm-lock.yaml`, workflows, migrations, server selection, or UI behavior. - No additional local suite was run during the final restack; GitHub Actions is the authoritative verification environment. ## Risks The main risk is widening model-visible authority. The bridge exposes only its closed public catalog and fixed terminal tools; private operations are omitted from discovery and catalog ambiguity fails during startup. Another risk is duplicate execution after a provider retry. The bridge fingerprints each admitted JSON-RPC identity, reuses the first promise for exact retries, and rejects changed payloads. The endpoint uses loopback plus a per-runtime bearer secret and has no production caller in this pull request. ## Model Used OpenAI Codex with GPT-5 and repository tool use. ## 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 linked an existing public item or described the issue in this PR - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal task identifier - [x] I have added or updated tests where applicable - [x] I have documented the authorization, network, idempotency, and rollout risks - [x] All applicable GitHub Actions are green - [x] Greptile is 5/5 with every actionable comment resolved - [x] I have addressed all review findings before merge