Cursor plugin specification and official plugins
TypeScript
Request broadcast scopes and document livestream tools in the X skill.
Michael Rosinsky15d1c5982a0a
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.jsonindex e78d8044..6cdebe40 100644--- a/.cursor-plugin/marketplace.json+++ b/.cursor-plugin/marketplace.json@@ -181,7 +181,7 @@{"name": "x","source": "third_party/x",- "description": "Search posts, read timelines, pull trends, manage bookmarks, access X Chat, and schedule X calls."+ "description": "Search posts, read timelines, pull trends, manage bookmarks, access X Chat, schedule X calls, and manage livestreams."},{"name": "clay",diff --git a/README.md b/README.mdindex 17c115d3..6bd1a779 100644--- a/README.md+++ b/README.md@@ -39,7 +39,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc| `hubspot` | [HubSpot](third_party/hubspot/) | Cursor | Integrations | Search and update contacts, companies, deals, and tickets. || `intercom` | [Intercom](third_party/intercom/) | Cursor | Integrations | Search conversations, contacts, and Help Center articles. || `zoom` | [Zoom](third_party/zoom/) | Cursor | Integrations | Search meetings, pull transcripts, and work with Zoom Docs. |-| `x` | [X](third_party/x/) | Cursor | Integrations | Search posts, read timelines, pull trends, manage bookmarks, access X Chat, and schedule X calls. |+| `x` | [X](third_party/x/) | Cursor | Integrations | Search posts, read timelines, pull trends, manage bookmarks, access X Chat, schedule X calls, and manage livestreams. || `clay` | [Clay](third_party/clay/) | Cursor | Integrations | Enrich people and companies, run AI research agents. || `circleback` | [Circleback](third_party/circleback/) | Cursor | Integrations | Search meetings, transcripts, action items, and emails. || `docusign` | [Docusign](third_party/docusign/) | Cursor | Integrations | Manage envelopes, templates, workflows, and agreements. |diff --git a/third_party/x/.cursor-plugin/plugin.json b/third_party/x/.cursor-plugin/plugin.jsonindex afeabbbe..7fa9076c 100644--- a/third_party/x/.cursor-plugin/plugin.json+++ b/third_party/x/.cursor-plugin/plugin.json@@ -1,11 +1,11 @@{"name": "x","displayName": "X",- "version": "2.7.0",+ "version": "2.8.0","minClientVersions": {"cursor": "3.13.0"},- "description": "Search posts, read timelines, pull trends, manage bookmarks, access X Chat, and schedule X calls.",+ "description": "Search posts, read timelines, pull trends, manage bookmarks, access X Chat, schedule X calls, and manage livestreams.","author": {"name": "Cursor","email": "[email protected]"@@ -24,6 +24,7 @@"lists","bookmarks","calls",+ "livestream","chat","social","mcp"diff --git a/third_party/x/CHANGELOG.md b/third_party/x/CHANGELOG.mdindex 60b22dd1..7e6afd41 100644--- a/third_party/x/CHANGELOG.md+++ b/third_party/x/CHANGELOG.md@@ -2,6 +2,15 @@All notable changes to this plugin will be documented here.+## 2.8.0 — Livestreams++- Requested `broadcast.read` and `broadcast.write` so agents can manage the owner's X livestreams on `https://api.x.com/mcp`.+- The guide covers stream sources (`list_sources`, `get_source`, `create_source`, `update_source`, `delete_source`), broadcasts (`list_broadcasts`, `get_broadcast`), scheduled broadcasts (`list_scheduled_broadcasts`, `get_scheduled_broadcast`, `create_scheduled_broadcast`, `update_scheduled_broadcast`, `delete_scheduled_broadcast`, `go_live_scheduled_broadcast`), chat moderators (`get_chat_moderators`, `add_chat_moderator`, `remove_chat_moderator`), and chat mutes (`mute_broadcast_chat_user`, `unmute_broadcast_chat_user`).+- Scheduling a livestream takes a source from `list_sources` and a start time in the owner's timezone. Writes only when the owner asked. A source's `id` is its stream key, so it stays out of the chat.+- Going live right now (starting, publishing, or ending an immediate broadcast) is not supported. A scheduled broadcast starts on its own, or with `go_live_scheduled_broadcast` when scheduled with `manual_publish: true`.+- Livestream tools are free. Missing livestream tools while other X tools work means reconnect, not a new Project or App.+- Existing installs need to sign in to X again to pick up the new scopes.+## 2.7.0 — Scheduled X calls- Requested `calls.read` and `calls.write` so agents can list, schedule, update, cancel, and RSVP to X calls on `https://api.x.com/mcp`.diff --git a/third_party/x/mcp.json b/third_party/x/mcp.jsonindex bdb1b4b3..f25fad87 100644--- a/third_party/x/mcp.json+++ b/third_party/x/mcp.json@@ -22,6 +22,8 @@"dm.write","calls.read","calls.write",+ "broadcast.read",+ "broadcast.write","media.write","developer.billing.write","developer.write",diff --git a/third_party/x/skills/x-api-mcp-guide/SKILL.md b/third_party/x/skills/x-api-mcp-guide/SKILL.mdindex adea1fcb..ee5b7c5d 100644--- a/third_party/x/skills/x-api-mcp-guide/SKILL.md+++ b/third_party/x/skills/x-api-mcp-guide/SKILL.md@@ -16,7 +16,12 @@ description: >-Scheduled X calls use schedule_call, list_scheduled_calls, get_scheduled_call,update_scheduled_call, cancel_scheduled_call, and respond_to_scheduled_call.Missing those tools or calls.read/calls.write while other X tools work:- reconnect the X plugin. Estimate every X call and confirm before anything expensive.+ reconnect the X plugin. Livestreams (stream sources, broadcasts, scheduled+ broadcasts, chat moderators and mutes) use list_sources, create_source,+ list_broadcasts, create_scheduled_broadcast and the other tools in the+ Livestreams section. Missing those tools or broadcast.read/broadcast.write+ while other X tools work: reconnect the X plugin. Going live right now is not+ supported. Estimate every X call and confirm before anything expensive.---# X MCP guide@@ -101,6 +106,7 @@ Once tools exist and `{credits}` is cached, send this once. Adapt the wording to> - **Bookmarks** — list, add, and remove bookmarks, and organize them into folders> - **Chat** — read and reply to X Chat, and list, open, or accept message requests (needs a Chat PIN via secret-request, not pasted here). Posting tweets is not supported.> - **Calls** — list the X calls on your calendar, schedule or change one, and RSVP to an invitation+> - **Livestreams** — your stream sources and broadcasts, schedule a broadcast, and manage chat moderators and mutes. Going live right now isn't supported.>> You have about $X.XX in credits.>@@ -218,6 +224,16 @@ Do not tell them to create a Project or App. Do not ask for a Bearer token. AfteDo not tell them to create a Project or App. Do not ask for a Bearer token. After reconnect, follow [Scheduled calls](#scheduled-calls).+### Livestream scopes++**When:** the user wants their stream sources, broadcasts, scheduled broadcasts, chat moderators, or chat mutes, other X tools work, but the livestream tools are missing or a call 403s for `broadcast.read` / `broadcast.write`.++**Say:**++> Livestreams need an extra sign-in. Reconnect the X plugin in this chat and approve access to your broadcasts. Then I'll retry. Don't paste keys, tokens, or stream keys.++Do not tell them to create a Project or App. Do not ask for a Bearer token. After reconnect, follow [Livestreams](#livestreams).+## Other errors`not-authorized-for-resource` (private account they don't own): stop. Their own timeline/bookmarks: probe current user, retry once with that id.@@ -277,6 +293,8 @@ X Chat is free for this plugin. X Chat reads (`GET /2/chat/*`) and public key loScheduled X calls are free, including on Grok Bot. Do not estimate a cost, ask for confirmation, or check or require credits for `list_scheduled_calls`, `get_scheduled_call`, `schedule_call`, `update_scheduled_call`, `cancel_scheduled_call`, or `respond_to_scheduled_call`.+Livestream tools are free. Do not estimate a cost or check or require credits for any tool in [Livestreams](#livestreams). Writes still need the owner to have asked (see that section).+The live payload:- `eventTypePricing` — price **per resource returned** (each post, user, news story…).@@ -358,6 +376,7 @@ When they ask what they can do, re-fetch `{credits}`, say how many they have lef- One post: parse status id, lookup.- X Chat / inbox / DMs / message requests: [X Chat](#x-chat). Clone the helper if missing — do not ask the user to find it. Use a [saved key](#saved-key) or secret-request the Chat PIN only. Owner must approve outbound text unless they already said to send or reply. Accept a request only when they said to accept.- X calls on the calendar: [Scheduled calls](#scheduled-calls). List or open when they ask. Schedule, update, cancel, or RSVP only when they asked.+- Livestreams ("schedule a livestream tomorrow at 3pm", "show me my livestreams", "make @xyz a moderator", "mute @xyz in my stream"): [Livestreams](#livestreams). List or open when they ask. Create, change, delete, go live, moderate, or mute only when they asked.## Scheduled calls@@ -378,6 +397,54 @@ List or open a call when they ask. Schedule, update, cancel, or RSVP only when tIf the tools are missing or a call returns 403 for `calls.read` / `calls.write`, that is [X call scopes](#x-call-scopes). Reconnect. Do not create a Project or App.+## Livestreams++These tools manage the owner's X livestreams: stream sources (RTMP/RTMPS ingest points for their encoder), broadcasts, scheduled broadcasts, and their broadcast chat's moderators and mutes. They are not X Calls and not X Chat.++| Tool | Does | Scope |+| --- | --- | --- |+| `list_sources` | The owner's stream sources | `broadcast.read` |+| `get_source` | One source by `id`; `is_stream_active` says whether the encoder is pushing video | `broadcast.read` |+| `create_source` | New source. `name` and `region` | `broadcast.write` |+| `update_source` | Rename a source. `id` and `name` | `broadcast.write` |+| `delete_source` | Delete a source by `id` | `broadcast.write` |+| `list_broadcasts` | The owner's broadcasts (live and past) | `broadcast.read` |+| `get_broadcast` | One broadcast by `id`, with state and viewer counts | `broadcast.read` |+| `list_scheduled_broadcasts` | The owner's scheduled broadcasts | `broadcast.read` |+| `get_scheduled_broadcast` | One scheduled broadcast by `id` | `broadcast.read` |+| `create_scheduled_broadcast` | Schedule a broadcast on a source | `broadcast.write` |+| `update_scheduled_broadcast` | Change a scheduled broadcast | `broadcast.write` |+| `delete_scheduled_broadcast` | Cancel a scheduled broadcast by `id` | `broadcast.write` |+| `go_live_scheduled_broadcast` | Start a schedule created with `manual_publish: true` | `broadcast.write` |+| `get_chat_moderators` | The owner's chat moderators | `broadcast.read` |+| `add_chat_moderator` | Make `user_id` a moderator | `broadcast.write` |+| `remove_chat_moderator` | Remove a moderator by `user_id` | `broadcast.write` |+| `mute_broadcast_chat_user` | Mute `user_id` in a running broadcast's chat (`id`) | `broadcast.write` |+| `unmute_broadcast_chat_user` | Unmute `user_id` in that chat | `broadcast.write` |++List or open when they ask. Create, change, delete, go live, add or remove a moderator, or mute only when they asked, and repeat what will change before you do it.++**Going live right now is not supported.** There is no tool to start, publish, or end an immediate broadcast. If they ask to go live now, say so plainly. They can schedule a broadcast instead: it starts on its own at its start time while their encoder streams to the source, or with `go_live_scheduled_broadcast` if they scheduled it with `manual_publish: true`.++**Schedule a livestream** ("tomorrow at 3pm"):++1. `list_sources`. If there is more than one, ask which. If there are none, offer `create_source` (a `name`, and a `region` from `us-east-1`, `us-east-2`, `us-west-1`, `us-west-2`, `ca-central-1`, `sa-east-1`, `eu-west-1`, `eu-west-3`, `eu-central-1`, `ap-south-1`, `ap-southeast-1`, `ap-southeast-2`, `ap-northeast-1`, or `ap-northeast-2`; pick the one closest to them).+2. Work out the start time in the owner's timezone. If you don't know it, ask. Repeat the date, time, and timezone back.+3. `create_scheduled_broadcast` with `source_id` (the source's `id`), `scheduled_start_ms` (milliseconds since the Unix epoch, as a string), and `title` if they gave one. Leave out `scheduled_end_ms` for an open-ended broadcast.+4. Reply with the title and time, and `https://x.com/i/broadcasts/{broadcast_id}`.++**Ids:** `get_scheduled_broadcast`, `update_scheduled_broadcast`, `delete_scheduled_broadcast`, `go_live_scheduled_broadcast`, `get_broadcast`, and the mute tools take the alphanumeric `broadcast_id` as `id`. `update_scheduled_broadcast` also needs the numeric `scheduled_broadcast_id` and replaces the whole schedule: `get_scheduled_broadcast` first and send every field you want to keep. Moderator and mute tools take a numeric `user_id`: resolve a handle with `get_users_by_username`.++**Moderators** apply to all of the owner's broadcasts (at most 20). **Mutes** work only while the broadcast is running; pass `end_at_ms` for a timeout.++**Stream keys are secrets.** A source's `id` is also its stream key (`rtmp_stream_key`): anyone with it can stream as the owner. Don't show the full `id`, `rtmp_stream_key`, or ingest URLs in chat unless they asked to set up an encoder, and never post them. Refer to sources by `name`. Deleting a source breaks any encoder still using its key.++`create_source` is not idempotent. If it fails or times out, `list_sources` before trying again so you don't create a duplicate.++`list_broadcasts` 403s with "requires X Premium or more than 1,000 followers" for accounts that can't stream. Say that plainly; it is not credits or scopes. Going live on a schedule needs the same.++If the tools are missing or a call returns 403 for `broadcast.read` / `broadcast.write`, that is [Livestream scopes](#livestream-scopes). Reconnect. Do not create a Project or App.+## X ChatX Chat is free for this plugin. X Chat reads (`GET /2/chat/*`) and public key lookups are free everywhere, in Grok Bot and in Cursor. Do not estimate a cost, ask for confirmation, or check or require credits.@@ -600,6 +667,10 @@ If `add_conversation_keys` returns `UNAUTHORIZED_REQUESTING_USER` or similar: yo- Treat missing Chat tools as “create a Project and App.” If other X tools work, that is [X Chat scopes](#x-chat-scopes) — reconnect.- Treat missing call tools as “create a Project and App.” If other X tools work, that is [X call scopes](#x-call-scopes) — reconnect.- Schedule, update, cancel, or RSVP to an X call unless the owner asked. Do not use the X Chat helper for calls.+- Treat missing livestream tools as "create a Project and App." If other X tools work, that is [Livestream scopes](#livestream-scopes) — reconnect.+- Say you can go live right now, or try to. Only `go_live_scheduled_broadcast`, and only on a schedule created with `manual_publish: true`.+- Show or post a source's full `id`, stream key, or ingest URLs unless the owner asked to set up an encoder.+- Create, change, or delete a source or scheduled broadcast, or add, remove, mute, or unmute a user, unless the owner asked.- Wait for the user to name `xchat_lite`, the helper repo, or a second X Chat skill. Clone it yourself.- Treat a reply as accepting a message request. Accept only with `accept_chat_message_request`, and only when the owner said to accept.- Call `get_chat_message_request` while scanning requests. That marks them delivered. List with `get_chat_message_requests`.