mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-04 11:01:16 +01:00
DottaandPaperclip
cabc9146d0
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Apps give those agents governed access to external tools. > - Remote MCP setup needs secure endpoint validation and durable credentials. > - PostHog needs both browser sign-in and personal API key setup paths. > - This pull request adds the shared remote MCP foundation and the PostHog definition. > - The benefit is a secure and reusable base for later app connection work. ## Linked Issues or Issue Description Refs #11965 This is stack 1 of 11. It replaces the first reviewable part of #11965. ## What Changed - Add guarded remote MCP setup and credential handling. - Add PostHog OAuth and API key connection methods. - Add focused server, shared contract, and UI coverage. - Keep the migration replay-safe and idempotent. - Give the late-close security regression the same 10-second CI headroom as the adjacent real-timer handshake test. - Synchronize fake-timer handshake tests at the exact ensure-session boundary so real filesystem setup cannot race the fake deadline. - Drive PTY overflow coverage only after listener registration so scheduling cannot reorder the test fixture. ## Verification - pnpm exec vitest run packages/adapter-utils/src/acpx-engine/execute.test.ts server/src/__tests__/plugin-worker-manager.test.ts (220 passed; affected cases also passed five focused stress repetitions) - `pnpm exec vitest run packages/adapter-utils/src/acpx-engine/execute.test.ts -t "never leaks a sandbox-provided value from a late close rejection into logs or the result"` (1 passed) - `pnpm exec vitest run packages/adapter-utils/src/acpx-engine/execute.test.ts -t "never promotes a late ensureSession resolution|closes a late-resolving real handle exactly once"` (2 passed) - `pnpm -r typecheck` - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/tool-access-service.test.ts` - `pnpm --filter @paperclipai/db check:migrations` - `pnpm build` ## Risks - Remote endpoint validation can reject configurations that previously passed without checks. - OAuth configuration errors can block setup until the operator corrects the provider settings. - The migration uses guarded statements so repeated execution is safe. - The test-only synchronization changes do not affect runtime behavior; they remove filesystem/fake-clock and listener-registration races observed under parallel CI load. > I checked `ROADMAP.md`. This stack continues the existing app connection work from #11965 and does not duplicate another planned item. ## Model Used OpenAI Codex, GPT-5. The runtime model ID and context window were not exposed. The model used reasoning, 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 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
57 lines
3.3 KiB
TypeScript
57 lines
3.3 KiB
TypeScript
/**
|
|
* The static prompt an operator copies and hands to an agent to get a
|
|
* paste-ready MCP config back (PAP-17087, plan section 3A).
|
|
*
|
|
* This is a constant on purpose. It must never interpolate the textarea's
|
|
* contents, the company, an endpoint, or a secret: the operator pastes it into
|
|
* whatever chat surface they like, so anything folded in here leaves Paperclip.
|
|
* Keeping it a constant is also what makes "opening or copying help makes no
|
|
* connection or import request" true by construction rather than by review.
|
|
*
|
|
* The instructions are ordered so the *first* thing in the reply is the JSON the
|
|
* operator has to paste, because that is the only part Paperclip's config
|
|
* preview parser reads. Everything else is prose for the human.
|
|
*/
|
|
export const MCP_CONFIG_HELP_PROMPT = `I want to connect an MCP (Model Context Protocol) server to Paperclip, and I need a paste-ready config.
|
|
|
|
Target server: <name the server, or ask me if I have not said>
|
|
|
|
Please:
|
|
|
|
1. Confirm which MCP server this is. If I have not named one, or you are unsure which product I mean, ask me for its name or a link to its documentation before answering. Then consult the current official documentation for that server (the vendor's own docs or the server's own repository), not your memory of it.
|
|
|
|
2. Reply with one valid, paste-ready JSON object FIRST, before any prose. It must have a single top-level "mcpServers" key containing exactly one remote server entry, using:
|
|
- the exact HTTP(S) endpoint as "url", including any required query parameters
|
|
- the exact required header names, spelled the way the server expects them
|
|
Example of the shape (not the values):
|
|
|
|
{
|
|
"mcpServers": {
|
|
"example": {
|
|
"url": "https://mcp.example.com/mcp",
|
|
"headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
|
|
}
|
|
}
|
|
}
|
|
|
|
3. Use an obvious placeholder for every credential, like <YOUR_API_KEY>. Do not ask me to paste a real token into this conversation, do not repeat one back to me, and do not embed one in the JSON.
|
|
|
|
4. After the JSON, add short setup notes covering:
|
|
- how I obtain each credential, step by step
|
|
- which scopes or permissions the credential needs
|
|
- which fields are optional and what they change
|
|
- whether this server requires browser sign-in (OAuth) instead of headers, in which case say so plainly
|
|
- the official documentation links you actually used
|
|
|
|
5. Do not invent fields, header names, or URLs. If you are not certain about something, say which part you are unsure about instead of guessing. If this server only runs locally as a command (stdio) and has no remote HTTP endpoint, say that the paste-a-config path does not apply, and give me the verified local command separately.`;
|
|
|
|
/**
|
|
* What the operator needs to know about the hand-off, shown above the prompt.
|
|
* Kept next to the prompt so the two cannot drift apart.
|
|
*/
|
|
export const MCP_CONFIG_HELP_INSTRUCTIONS = [
|
|
"Copy this prompt and send it to an agent or assistant that can look up the server's documentation.",
|
|
"Paste only the JSON block it replies with back into the box on this page.",
|
|
"Paperclip reads the header names from that JSON and asks you for the values, then stores them as Paperclip secrets — so the config you paste should contain placeholders, not live credentials.",
|
|
] as const;
|