@link.me/mcp 0.2.56 → 0.3.1

package/README.md

@@ -83,7 +83,9 @@ linkme config show --json | jq -r '.token'
 
 ## Available Tools
 
-The MCP server exposes 100+ tools covering the full Linkme platform. All tools return structured JSON. Destructive operations (delete, cancel, reset) auto-confirm without prompting.
+The MCP server exposes 170+ tools covering the full Linkme platform. All tools return structured JSON (both a text block and, on success, matching `structuredContent`).
+
+Every tool is annotated with [MCP tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so hosts can surface expected behavior before a call. Tools backed by a destructive CLI command (delete, cancel, reset, etc.) are marked `destructiveHint: true` and their description is suffixed with `(Destructive: executes immediately without a confirmation prompt.)` — the underlying `--force` flag is auto-injected and these tools run immediately with no confirmation step, so check annotations/descriptions before calling them.
 
 ### Profile & Identity
 
@@ -107,33 +109,40 @@ The MCP server exposes 100+ tools covering the full Linkme platform. All tools r
 
 | Tool | Description |
 |------|-------------|
-| `links_list` | List profile links |
-| `links_add` | Add a link |
-| `links_edit` | Edit a link |
-| `links_delete` | Delete a link |
-| `featured_list` | List featured links |
-| `featured_add` | Add a featured link |
-| `featured_edit` | Edit a featured link |
-| `featured_delete` | Delete a featured link |
-| `social_list` | List social links |
-| `social_set` | Set a social link |
+| `links_list` | List custom and platform links |
+| `links_add` | Add a custom link |
+| `links_edit` | Edit a custom link |
+| `links_delete` | Delete a custom link |
+| `links_set` | Set a platform/social link |
+| `links_unset` | Remove a platform/social link |
+| `links_platform_list\|set\|delete` | Platform links (shared link system) |
+| `links_schedule_list\|create\|edit\|delete\|publish-now\|cancel` | Scheduled links |
+| `featured_list\|add\|edit\|delete\|reorder` | Featured links |
+| `featured_headers_*`, `featured_multilinks_*` | Featured headers and multilinks |
 
 ### AP (Post on All Platforms)
 
 | Tool | Description |
 |------|-------------|
 | `ap_accounts` | List connected accounts |
-| `ap_connect` | Connect a provider |
 | `ap_disconnect` | Disconnect a provider |
+| `ap_upload` | Upload a video for posting |
+| `ap_limits` | Show plan limits and remaining quota |
 | `ap_post_list` | List posts |
+| `ap_post_calendar` | Posts in a date range |
 | `ap_post_create` | Create a post |
 | `ap_post_status` | Check post status |
 | `ap_post_publish` | Publish a draft |
-| `ap_post_cancel` | Cancel a post |
+| `ap_post_cancel` | Cancel a post (whole post or specific targets) |
 | `ap_post_retry` | Retry a failed post |
-| `ap_analytics` | Post analytics |
+| `ap_post_reschedule` | Update caption/schedule of a scheduled post |
+| `ap_post_insights` | Per-target live insights |
+| `ap_post_comments` | Per-target comments |
+| `ap_analytics_post` | Post analytics |
 | `ap_analytics_accounts` | Account-wide analytics |
 
+Connecting a provider (`linkme ap connect`) is an interactive OAuth flow and is CLI-only.
+
 ### Analytics
 
 | Tool | Description |
@@ -152,52 +161,99 @@ The MCP server exposes 100+ tools covering the full Linkme platform. All tools r
 | `email_test` | Send a test email |
 | `email_history` | Campaign history |
 | `email_detail` | Campaign details |
+| `email_recipients` | List campaign recipients |
 | `email_cancel` | Cancel a campaign |
-| `email_domains` | Sending domains |
 | `email_upload-image` | Upload an image |
-| `email_templates_list` | List templates |
-| `email_templates_create` | Create a template |
-| `email_templates_delete` | Delete a template |
+| `email_domains_list` | List sending domains (verified and pending) |
+| `email_domains_add` | Add a sending domain |
+| `email_domains_verify` | Check DNS verification status |
+| `email_templates_list\|get\|create\|update\|delete` | Email templates |
 
 ### Commerce & Shop
 
 | Tool | Description |
 |------|-------------|
 | `commerce_products_list` | List digital products |
-| `commerce_products_create` | Create a product |
-| `commerce_products_delete` | Delete a product |
-| `shop_products_list\|add\|edit\|delete` | Shop products |
+| `commerce_products_create` | Create a digital product |
+| `commerce_products_edit` | Edit a digital product |
+| `commerce_products_reorder` | Reorder digital products |
+| `commerce_products_orders` | List digital product sales |
+| `commerce_products_delete` | Delete a digital product |
+| `commerce_merch_list\|categories` | Merch catalog |
+| `shop_products_list\|add\|edit\|delete` | Physical shop products |
 | `shop_categories_list\|add\|edit\|reorder\|delete` | Shop categories |
 
 ### Other Tools
 
 | Tool | Description |
 |------|-------------|
+| `search` | Search Linkme users |
+| `username_check` | Check username availability |
+| `waitlist_status\|join` | Feature waitlists (e.g. AP) |
 | `contacts_list` | List contacts |
 | `contacts_stats` | Contact analytics |
-| `gallery_list\|delete` | Gallery media |
-| `auth_login\|logout\|sessions\|switch` | Authentication |
+| `gallery_upload\|list\|delete` | Gallery media |
+| `profile_video_show\|set\|remove` | Profile video |
+| `profile_forms_*`, `profile_events_*` | Forms and events |
+| `auth_login\|logout\|resume` | Authentication |
+| `auth_sessions_list\|revoke` | Session management |
 | `config_show\|set\|reset` | Configuration |
-| `automations_*` | Instagram automations (20+ tools) |
-| `courses_*` | Course management |
+| `automations_*` | Instagram automations (16 tools) |
+| `courses_*` | Course management (incl. `courses_videos_upload`) |
 | `feeds_*` | Feed subscriptions |
 | `reviews_*` | Review subscriptions |
 | `agency_*` | Agency management |
+| `skill_list\|show` | Bundled agent skill docs |
+
+## Hosted / Remote Server (Streamable HTTP)
+
+Besides the stdio binary, the server can run as a remote MCP endpoint over [Streamable HTTP](https://modelcontextprotocol.io/specification/basic/transports#streamable-http) — the transport required for the claude.ai connectors directory and the ChatGPT Apps ecosystem:
+
+```bash
+PORT=8788 linkme-mcp-http          # or: bun run start:mcp-http
+```
+
+- `POST /mcp` — the MCP endpoint (stateless; one request per call, safe for serverless).
+- Auth is per-request: `Authorization: Bearer <linkme-token>`. Requests without a token get a `401` with a `WWW-Authenticate` header pointing at the RFC 9728 metadata.
+- `GET /.well-known/oauth-protected-resource/mcp` — protected-resource metadata.
+- `GET /healthz` — health probe.
+
+### Sign in with Linkme (claude.ai / Claude Desktop / ChatGPT)
+
+The hosted server supports OAuth 2.1, so no token setup is needed: add `https://mcp.link.me/mcp` as a custom connector in claude.ai, Claude Desktop, or ChatGPT and sign in with your Linkme account when prompted. No CLI or npm install required.
+
+Self-hosting operators: see `docs/mcp-oauth.md` in the source repository for configuration.
+- The process is multi-tenant safe: the bearer token is scoped to the request, local CLI profiles are never read, and only `LINKME_API_URL` / `LINKME_AUTH_URL` / `LINKME_AP_URL` are forwarded from the host environment.
+
+The handler is built on the SDK's web-standard transport (`Request`/`Response`), so `createMcpHttpHandler()` from `mcp/http-server.ts` also runs unchanged on Cloudflare Workers, Deno, or any fetch-based runtime.
+
+### Cloudflare Workers deploy
+
+A ready-to-deploy Worker lives in `workers/` (`mcp-worker.ts` + `wrangler.jsonc`):
+
+```bash
+bun run dev:mcp-worker      # local workerd via wrangler dev
+bun run deploy:mcp-worker   # wrangler deploy (requires wrangler login)
+```
+
+- Requires the `nodejs_compat` compatibility flag (already configured) — commands write config to workerd's in-memory virtual `/tmp`, never to real disk.
+- `workers/stubs/` aliases two transitive deps that misbehave on workerd: `when-exit` (browser build references `window`) and `atomically` (temp-file rename fails on the virtual fs; a plain write is equivalent there).
+- Set `LINKME_OAUTH_ISSUERS` (and optionally `LINKME_API_URL` / `LINKME_AUTH_URL` / `LINKME_AP_URL`) as Worker vars.
+- Known limitation: `skill_list` / `skill_show` return an in-band tool error on Workers — skill markdown files are not bundled into the Worker.
 
 ## Environment Variables
 
 | Variable | Description |
 |----------|-------------|
 | `LINKME_TOKEN` | Auth token (required) |
-| `LINKME_API_URL` | Override API base URL |
-| `LINKME_AUTH_URL` | Override auth service URL |
-| `LINKME_AP_URL` | Override AP service URL |
+| `LINKME_API_URL` | Override core API gateway (fallback for user/analytics/commerce/email) |
+| `LINKME_<SERVICE>_URL` | Per-service overrides — see `linkme config endpoints` for the full list |
 
 ## How It Works
 
 The MCP server uses stdio transport and exposes each CLI command as an MCP tool. Tool inputs are derived from the same Zod schemas used by the CLI. All tools run in JSON mode with color disabled, returning structured responses suitable for LLM consumption.
 
-Interactive commands (shell completion, video upload) are excluded from the MCP tool set.
+Commands that genuinely require a terminal are excluded from the MCP tool set: shell completion, browser OAuth flows (`ap connect`, `automations authorize`), profile switching (`auth switch`), and interactive reordering (`links reorder`). Upload commands (`ap_upload`, `gallery_upload`, `courses_videos_upload`, `email_upload-image`, `profile_video_set`) are fully flag-driven and ARE available as tools.
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@link.me/mcp",
-	"version": "0.2.56",
+	"version": "0.3.1",
 	"description": "Linkme platform MCP server for Claude, Cursor, and other AI agents",
 	"license": "UNLICENSED",
 	"bin": {
@@ -16,10 +16,10 @@
 		"ai"
 	],
 	"optionalDependencies": {
-		"@link.me/mcp-darwin-arm64": "0.2.56",
-		"@link.me/mcp-darwin-x64": "0.2.56",
-		"@link.me/mcp-linux-x64": "0.2.56",
-		"@link.me/mcp-linux-arm64": "0.2.56",
-		"@link.me/mcp-windows-x64": "0.2.56"
+		"@link.me/mcp-darwin-arm64": "0.3.1",
+		"@link.me/mcp-darwin-x64": "0.3.1",
+		"@link.me/mcp-linux-x64": "0.3.1",
+		"@link.me/mcp-linux-arm64": "0.3.1",
+		"@link.me/mcp-windows-x64": "0.3.1"
 	}
 }