diff --git a/README.md b/README.md index 28e1041..855b5eb 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Hosted at [getpluck.io](https://getpluck.io), or run your own with `docker compo - `packages/db`: the only code that touches MongoDB. Every query is scoped to one person. - `packages/extract`: reading pages, PDFs, email and imports. - `packages/blob`: S3 (MinIO locally). - - `packages/mcp`: the connector's tools, resources and prompts. `packages/mcp-stdio` is `npx @getpluck/mcp`. + - `packages/mcp`: the connector's tools, resources and prompts. `packages/mcp-stdio` is `npx @getpluck/mcp` ([npm](https://www.npmjs.com/package/@getpluck/mcp)). - `packages/shared-schemas`: every type, as a Zod schema, shared by server and clients. - `packages/client`: the API client, offline queue and PKCE shared by the iPhone app and the extension. - `packages/i18n`: the words in ten languages (English, Spanish, Portuguese (Brazil), French, German, Japanese, Italian, Dutch, Korean, Chinese (Simplified)). diff --git a/SECURITY.md b/SECURITY.md index 44fd4c8..16232c4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -19,7 +19,7 @@ Tell us what you found, how to see it, and what someone could do with it. A proo ## What is in scope -The hosted service at getpluck.io, the code in this repository (web app, API, MCP connector, browser extension, iPhone app and share extension, the Docker image), and the published `@getpluck/mcp` package. +The hosted service at getpluck.io, the code in this repository (web app, API, MCP connector, browser extension, iPhone app and share extension, the Docker image), and the published [`@getpluck/mcp`](https://www.npmjs.com/package/@getpluck/mcp) package. Self-hosted copies are run by their owners; report problems in the code here, and the owner of that copy for problems in how it is run. diff --git a/docs/architecture.md b/docs/architecture.md index af61455..dd782a1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -31,7 +31,7 @@ One Next.js app (`apps/web`) is the website, the signed-in app, the REST API for | `apps/web/lib/email.ts`, `emails.ts`, `digest-email.ts` | `sendEmail` (SMTP to Mailpit locally, SES in production) and the email templates. | | `packages/db` | Every collection, index and query (`collections.ts` defines them all). Every query is scoped by `userId`; `public.ts` is the only reader for public Lists. | | `packages/mcp` | The connector's tools, resources and prompts (package `@pluck/mcp-server`). It sees the library only through `PluckLibrary`. | -| `packages/mcp-stdio` | The `npx @getpluck/mcp` bridge (package `@getpluck/mcp`, the one published to npm): stdio to the hosted connector with an API key. | +| `packages/mcp-stdio` | The `npx @getpluck/mcp` bridge (package [`@getpluck/mcp`](https://www.npmjs.com/package/@getpluck/mcp), the one published to npm): stdio to the hosted connector with an API key. | | `packages/extract` | Guarded fetch (`fetch.ts`), page and PDF reading (`extract.ts`, Defuddle then Readability), email (`email.ts`) and imports. Its fixtures are served by `pnpm stack` so tests never touch the internet. | | `packages/blob` | S3 through the AWS SDK; MinIO locally and for self-hosting. | | `packages/shared-schemas` | Every type as a Zod schema, used by the server and every client. | diff --git a/docs/handover/design/Settings.dc.html b/docs/handover/design/Settings.dc.html index 44d8299..f78bd43 100644 --- a/docs/handover/design/Settings.dc.html +++ b/docs/handover/design/Settings.dc.html @@ -59,7 +59,7 @@

AI t
Claude Code
claude mcp add --transport http pluck https://getpluck.io/mcp
Self-hosting without a public URL -npx @pluck/mcp --key pk_live_••••••••3f9a
+npx @getpluck/mcp --key pk_live_••••••••3f9a
Opens your AI with “What did I pluck this week?”
diff --git a/docs/handover/design/SiteClaude.dc.html b/docs/handover/design/SiteClaude.dc.html index 36d43bc..cf99a42 100644 --- a/docs/handover/design/SiteClaude.dc.html +++ b/docs/handover/design/SiteClaude.dc.html @@ -104,7 +104,7 @@

docker compose up -d # then, for AI tools without a public URL -npx @pluck/mcp --server http://localhost:3000 --key pk_live_… +npx @getpluck/mcp --server http://localhost:3000 --key pk_live_…

diff --git a/docs/handover/pluck-product-spec-v2.md b/docs/handover/pluck-product-spec-v2.md index 4deee40..a4b622e 100644 --- a/docs/handover/pluck-product-spec-v2.md +++ b/docs/handover/pluck-product-spec-v2.md @@ -186,7 +186,7 @@ The share sheet is the product on iOS. It saves in place, like Pocket did. The a The connector is the product's second half. It has to feel like your AI has read your library, not like it is poking an API. Pluck speaks MCP, so Claude, ChatGPT, Cursor, Claude Code and any other MCP client use the same URL. Claude is named only as one of them. -**Setup.** Settings, AI tools: the connector URL with a copy button, install steps for Claude, Claude Code, ChatGPT, Cursor and self-hosted, a 20-second GIF, and a "Test it" button that opens your AI with "What did I pluck this week?" prefilled. Self-hosters without a public URL get `npx @pluck/mcp` with their API key. +**Setup.** Settings, AI tools: the connector URL with a copy button, install steps for Claude, Claude Code, ChatGPT, Cursor and self-hosted, a 20-second GIF, and a "Test it" button that opens your AI with "What did I pluck this week?" prefilled. Self-hosters without a public URL get `npx @getpluck/mcp` with their API key. **The four prompts.** These are the only "AI features" Pluck has, and they live in your AI tool. diff --git a/docs/handover/pluck-technical-spec-v2.md b/docs/handover/pluck-technical-spec-v2.md index 5284514..ed84255 100644 --- a/docs/handover/pluck-technical-spec-v2.md +++ b/docs/handover/pluck-technical-spec-v2.md @@ -45,7 +45,7 @@ packages/shared-schemas Zod types, OpenAPI, error codes packages/db the only package that touches MongoDB packages/extract Defuddle/Readability, fixtures packages/mcp tools, resources, prompts -packages/mcp-stdio npx @pluck/mcp bridge for self-host +packages/mcp-stdio npx @getpluck/mcp bridge for self-host packages/ui brand tokens, Logo and Icon components, kind glyphs infra/cdk DataStack, EmailStack, DnsStack docs/ self-host.md, mcp.md @@ -213,7 +213,7 @@ The MCP server is the product's brain socket and the only public integration sur | Claude Code | `claude mcp add --transport http pluck https://getpluck.io/mcp` | OAuth with loopback redirect, or `--header "Authorization: Bearer pk_live_..."` | | ChatGPT | Settings, Connectors, Create, MCP server URL | OAuth | | Cursor and other editors | `mcp.json` with `{ "mcpServers": { "pluck": { "url": "https://getpluck.io/mcp" } } }` | OAuth or API key | -| Self-host without public HTTPS | `npx @pluck/mcp --server --key pk_live_...` (stdio bridge) | API key | +| Self-host without public HTTPS | `npx @getpluck/mcp --server --key pk_live_...` (stdio bridge) | API key | **OAuth flow.** `POST /mcp` without a token returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://getpluck.io/.well-known/oauth-protected-resource"`. The client reads the first `authorization_servers` entry, fetches `/.well-known/oauth-authorization-server`, uses CIMD if advertised and DCR otherwise, runs the authorisation code flow with PKCE and `resource=https://getpluck.io/mcp`, and refreshes on its own. The server validates `aud` on every request and includes `iss` in authorisation responses. Each discovery and token endpoint answers inside 10 seconds. No apex-to-www redirects on these paths. @@ -370,7 +370,7 @@ Each step ends green in CI and deployable. 4. Lists: CRUD, per-list note and tick, reorder, `a` shortcut, list page, Private/Public switch, public page with the narrow projection and its test, copy, report. 5. Search with `$text`, filter chips, "Ask your AI" empty state. 6. Worker: retry queue, expiry job, archive-stale, digest email, email-in, import, export. -7. MCP server: OAuth metadata and CIMD, the 12 tools, 2 resources, 4 prompts, the end-to-end OAuth test. `npx @pluck/mcp` bridge. Settings AI tools section. +7. MCP server: OAuth metadata and CIMD, the 12 tools, 2 resources, 4 prompts, the end-to-end OAuth test. `npx @getpluck/mcp` bridge. Settings AI tools section. 8. Extension: popup, capture, list picker, all-tabs, context menus, badge, options. 9. Marketing site, privacy, terms, Connect your AI page. 10. iOS Shortcut, then the Expo app and the Swift share extension. diff --git a/docs/mcp.md b/docs/mcp.md index 90abd55..a45a357 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -80,6 +80,6 @@ Everything an AI tool changes is marked "by AI" in Pluck: its tags until the per - `packages/mcp` holds the tools, resources and prompts. It sees the library only through `PluckLibrary` (`packages/mcp/src/library.ts`); `apps/web/lib/connector.ts` binds it to the in-process library for one person, with every write marked as made by AI. - `apps/web/app/mcp/route.ts` authenticates (OAuth token or API key), rate limits and serves. -- `packages/mcp-stdio` is the `npx @getpluck/mcp` bridge. +- `packages/mcp-stdio` is the `npx @getpluck/mcp` bridge, published as [`@getpluck/mcp`](https://www.npmjs.com/package/@getpluck/mcp). - Tests: `apps/web/lib/connector.test.ts` (every tool against a seeded database), `apps/web/lib/cimd.test.ts`, `packages/mcp-stdio/src/bridge.test.ts`, and `e2e/mcp.spec.ts` (the full OAuth dance, every tool, resource and prompt over HTTP, Disconnect, API keys and the stdio bridge). - Try it by hand: `npx @modelcontextprotocol/inspector`, then connect to `http://localhost:3000/mcp`. diff --git a/packages/mcp-stdio/README.md b/packages/mcp-stdio/README.md index 4d193b2..22df28c 100644 --- a/packages/mcp-stdio/README.md +++ b/packages/mcp-stdio/README.md @@ -1,5 +1,7 @@ # @getpluck/mcp +[npm](https://www.npmjs.com/package/@getpluck/mcp) + Your [Pluck](https://getpluck.io) library in any MCP client that speaks stdio, with an API key. Clients that connect to a remote server (Claude, ChatGPT, Cursor) can use `https://getpluck.io/mcp` directly and need none of this.