Cursor plugin specification and official plugins
TypeScript
Request calls scopes and document scheduled-call tools.
Paul Vann58994c60919f
diff --git a/third_party/x/.cursor-plugin/plugin.json b/third_party/x/.cursor-plugin/plugin.jsonindex 9ef3293c..afeabbbe 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.6.6",+ "version": "2.7.0","minClientVersions": {"cursor": "3.13.0"},- "description": "Search posts, read timelines, pull trends, manage bookmarks, and access X Chat.",+ "description": "Search posts, read timelines, pull trends, manage bookmarks, access X Chat, and schedule X calls.","author": {"name": "Cursor","email": "[email protected]"@@ -23,6 +23,7 @@"news","lists","bookmarks",+ "calls","chat","social","mcp"diff --git a/third_party/x/CHANGELOG.md b/third_party/x/CHANGELOG.mdindex 9f690c80..60b22dd1 100644--- a/third_party/x/CHANGELOG.md+++ b/third_party/x/CHANGELOG.md@@ -2,6 +2,12 @@All notable changes to this plugin will be documented here.+## 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`.+- The guide covers `schedule_call`, `list_scheduled_calls`, `get_scheduled_call`, `update_scheduled_call`, `cancel_scheduled_call`, and `respond_to_scheduled_call`. Schedule, update, cancel, and RSVP only when the owner asked. Missing call 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.6.6 — media.write scope- Requested `media.write`.diff --git a/third_party/x/README.md b/third_party/x/README.mdindex 965db845..501045c9 100644--- a/third_party/x/README.md+++ b/third_party/x/README.md@@ -2,7 +2,7 @@Cursor plugin that connects agents to the [X API](https://docs.x.com) through X's official hosted [Model Context Protocol](https://modelcontextprotocol.io/) server at `https://api.x.com/mcp`.-This plugin signs you in with OAuth as your own X account. It is no longer read-only: alongside searching and reading public X data, agents can manage your lists, bookmarks, blocks, and mutes, and call X Chat endpoints.+This plugin signs you in with OAuth as your own X account. It is no longer read-only: alongside searching and reading public X data, agents can manage your lists, bookmarks, blocks, and mutes, call X Chat endpoints, and schedule X calls.## Install@@ -37,6 +37,8 @@ Or run `/add-plugin x` in chat."bookmark.write","dm.read","dm.write",+ "calls.read",+ "calls.write","media.write","developer.billing.write","developer.write",@@ -61,6 +63,7 @@ Or run `/add-plugin x` in chat.| Bookmarks | Read and manage your bookmarks || Blocks & mutes | Read your blocks and mutes; add or remove blocks || Chat | List conversations, fetch events, send messages, typing, and read receipts; list, open, and accept message requests |+| Calls | List and open scheduled X calls; schedule, update, or cancel one; RSVP to an invitation || Developer account | Read your X developer account settings and credit balance |Posting is not included: the plugin does not request the `tweet.write` scope, so agents cannot publish posts as you.@@ -73,7 +76,7 @@ Requests run in your user context, so they count against your account's rate lim## Scopes requested-`tweet.read`, `users.read`, `follows.read`, `space.read`, `mute.read`, `like.read`, `list.read`, `list.write`, `block.read`, `block.write`, `bookmark.read`, `bookmark.write`, `dm.read`, `dm.write`, `media.write`, `developer.billing.write`, `developer.write`, `offline.access`+`tweet.read`, `users.read`, `follows.read`, `space.read`, `mute.read`, `like.read`, `list.read`, `list.write`, `block.read`, `block.write`, `bookmark.read`, `bookmark.write`, `dm.read`, `dm.write`, `calls.read`, `calls.write`, `media.write`, `developer.billing.write`, `developer.write`, `offline.access`## X documentation searchdiff --git a/third_party/x/mcp.json b/third_party/x/mcp.jsonindex 8a2ccedb..bdb1b4b3 100644--- a/third_party/x/mcp.json+++ b/third_party/x/mcp.json@@ -20,6 +20,8 @@"bookmark.write","dm.read","dm.write",+ "calls.read",+ "calls.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 54b59fc9..dc366ef3 100644--- a/third_party/x/skills/x-api-mcp-guide/SKILL.md+++ b/third_party/x/skills/x-api-mcp-guide/SKILL.md@@ -13,7 +13,10 @@ description: >-live in THIS file: clone xchat-grokbot-helper and run xchat_lite.py locally —do not wait for the user to name the helper or another skill. Missing chattools or dm.read/dm.write while other X tools work: reconnect the X plugin.- Estimate every X call and confirm before anything expensive.+ 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.---# X MCP guide@@ -97,6 +100,7 @@ Once tools exist and `{credits}` is cached, send this once. Adapt the wording to> - **News & trends** — search X news stories and get trends by location> - **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>> You have about $X.XX in credits.>@@ -136,6 +140,8 @@ Do **not** treat `get_usage_credits` not found as #2 by itself. If other `user-XMissing **Chat** tools (`get_chat_conversations`, `send_chat_message`, …) while timeline/search/`get_users_me` work is **not** #2. That is [X Chat scopes](#x-chat-scopes) — reconnect for `dm.read` / `dm.write`.+Missing **call** tools (`schedule_call`, `list_scheduled_calls`, …) while other X tools work is **not** #2. That is [X call scopes](#x-call-scopes) — reconnect for `calls.read` / `calls.write`.+**When (fallback):** `client-forbidden`; `user-not-enrolled`; `client-not-enrolled`; Client Forbidden; 403 on timeline / mentions / search / bookmarks after Connect.**Say:**@@ -202,6 +208,16 @@ Then follow [error 1](#1-sign-in-failed) or [error 2](#2-account-not-ready). DoDo not tell them to create a Project or App. Do not ask for a Bearer token. After reconnect, follow [X Chat](#x-chat): clone the helper yourself, use a [saved key](#saved-key) or secret-request **only** the Chat PIN into `CHAT_PIN`, then read/reply.+### X call scopes++**When:** the user wants to list, schedule, change, cancel, or RSVP to an X call, other X tools work, but the call tools are missing or a call 403s for `calls.read` / `calls.write`.++**Say:**++> X calls need an extra sign-in. Reconnect the X plugin in this chat and approve access to your calls. Then I'll retry. Don't paste keys or tokens.++Do not tell them to create a Project or App. Do not ask for a Bearer token. After reconnect, follow [Scheduled calls](#scheduled-calls).+## 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.@@ -259,6 +275,8 @@ Every X call can charge the user. Estimate the cost **before** calling. Read [reX 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 for `get_chat_conversations`, `get_chat_message_requests`, `get_chat_message_request`, `accept_chat_message_request`, `get_chat_conversation`, `get_chat_conversation_events`, public key lookups, `add_conversation_keys`, `send_chat_message`, typing indicators, or marking a conversation read.+Scheduled X calls are not in [references/pricing.md](references/pricing.md). Check the live pricing table before one. If `calls` is not listed, do not invent a price. Schedule, update, cancel, and RSVP still need a yes, because they change the owner's calendar and can email invitees.+The live payload:- `eventTypePricing` — price **per resource returned** (each post, user, news story…).@@ -339,6 +357,26 @@ When they ask what they can do, re-fetch `{credits}`, say how many they have lef- Bookmarks: list `{me}`. Save: parse status id, create bookmark.- 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.++## Scheduled calls++These tools are the owner's X Calls calendar. They are not X Chat and not a livestream. Do not clone the Chat helper, ask for a Chat PIN, or send a chat message to schedule a call.++| Tool | Does | Scope |+| --- | --- | --- |+| `list_scheduled_calls` | X calls on the calendar in a window (defaults to the next 24 hours, at most 7 days) | `calls.read` |+| `get_scheduled_call` | One scheduled call by `id` | `calls.read` |+| `schedule_call` | Put a call on the calendar and invite people | `calls.write` |+| `update_scheduled_call` | Move, rename, or re-invite a call the owner organizes | `calls.write` |+| `cancel_scheduled_call` | Cancel a call the owner organizes | `calls.write` |+| `respond_to_scheduled_call` | RSVP. `response` is `accepted`, `declined`, or `tentative` | `calls.write` |++List or open a call when they ask. Schedule, update, cancel, or RSVP only when they asked, and repeat the time, who is invited, and the RSVP before you do it. A write can email invitees.++`id` is the scheduled-call id from a list or schedule result. On a recurring call, pass `scope` and `occurrence_start_time` only when they said which occurrences: one, this one and the ones after it, or all of them. Default is all.++If 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.## X Chat@@ -560,6 +598,8 @@ If `add_conversation_keys` returns `UNAUTHORIZED_REQUESTING_USER` or similar: yo- Quote `total_balance` or `free_grants` as “you received $X”. Gift size by plan is the starter table, and only if they ask **and** you know the plan. Always say remaining balance (`You have about $X.XX in credits.`, including $0.00).- Treat tools=0 / `user-X-*` not found as a paywall. That is [error 2](#2-account-not-ready).- 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.- 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`.