Cursor plugin specification and official plugins
TypeScript
Rework X Money guide from server source
Asad Salmanbab183fe1020
diff --git a/third_party/x-money/README.md b/third_party/x-money/README.mdindex 4401780f..e73f9a16 100644--- a/third_party/x-money/README.md+++ b/third_party/x-money/README.md@@ -34,36 +34,39 @@ Or ask the agent to connect your X Money account.## Connecting-Auth is OAuth 2.1 with PKCE. There is no client ID, API key, or token to paste. The Cursor backend is a registered confidential client of X Money and completes the sign-in on your behalf.+Auth is OAuth. There is no client ID, API key, or token to paste. Cursor completes the sign-in on your behalf.-1. Grok Bot opens the X Money consent page in a browser.-2. The page shows a connection code and a QR code.-3. Open the code in the X app and approve it with your passkey.-4. The page redirects back to Grok Bot and the connection completes.+1. Grok Bot opens the **Connect Grok Bot to X Money** page in a browser. It shows a connection code and a QR code.+2. Enter the code in the X Money app, or scan the QR code, and approve with your passkey.+3. The page confirms the connection and Grok Bot picks it up on its own.-Access tokens expire after 15 minutes and refresh automatically. Tokens are stored encrypted on the Cursor backend and never reach the agent, the chat, or your device. You can revoke the connection at any time from **X → Money → Settings → Connections**.+The code is valid for about 5 minutes. You can revoke the connection at any time from **X → Money → Settings → Connections**.## What agents can do| Category | Capabilities || --- | --- |-| Balances | Available balance of your main, secondary, and joint accounts |-| Transactions | Your transaction history, newest first, with optional filters |-| Payments | Send money from your X Money balance to another X user, or ask another X user to pay you |-| Cards | Create a single-use virtual card for one online purchase at one merchant |+| Balances | Available balance of your X Money accounts |+| Transactions | Your transaction history, with optional filters |+| Payments | Send money to another X user, or ask another X user to pay you |+| Purchases | Pay a merchant online with an X Money virtual card |-The hosted server is the source of truth for the available actions. X Money enables actions per account, so the set can differ between users.+X Money decides which actions are available for each account, so the set can differ between users.++## Approval++Every action that moves money is confirmed with you first. Before sending money, requesting money, or paying a merchant, the agent shows an Approve / Cancel prompt that states exactly who, how much, and what for. Nothing happens until you approve, and each action needs its own approval. X Money also enforces this on its side and refuses any such call that was not approved.## Skill-`skills/x-money-guide/SKILL.md` tells the agent how the connection works, how to guide a user through connect, reconnect, and revoke (**X → Money → Settings → Connections**), what each refusal means, and that every action that moves money needs a fresh approval.+`skills/x-money-guide/SKILL.md` gives the agent the approval rule above, the connection flow, how to guide you through connect, reconnect, and revoke, and what each X Money failure message means.## Notes-- Payments and cards created through this server are live and move real money.-- Every action passes the same X Money checks as the app. X Money also enforces agent spending limits on top of your account limits. A refused action returns a message for the agent to relay and is not retried.-- Higher-risk transfers, such as bank transfers and large payments, are not available to agents and stay behind verification in the X app.-- Each virtual card works for exactly one merchant and one purchase. Card details are returned to the agent to complete checkout and are not shown in chat.+- Payments and purchases made through this plugin are live and move real money.+- Every action passes the same X Money checks as the app, plus separate limits for agents. When X Money refuses an action, the agent relays the reason and does not retry.+- Higher-risk transfers stay in the X app and are not available to agents.+- Card details used for a purchase go straight to the merchant checkout and are never shown in chat.- The agent never sees your X Money password, passkey, or bank credentials.## Docsdiff --git a/third_party/x-money/skills/x-money-guide/SKILL.md b/third_party/x-money/skills/x-money-guide/SKILL.mdindex 1779de23..6fbbe0d2 100644--- a/third_party/x-money/skills/x-money-guide/SKILL.md+++ b/third_party/x-money/skills/x-money-guide/SKILL.md@@ -2,33 +2,39 @@name: X Money guidedescription: >-Read this before the first X Money action in a session and again on any- X Money error, refusal, or missing capability. Covers how the connection- works (connection code plus passkey in the X app), how to walk the user- through connect, reconnect, and revoke at x.com/i/money/settings/connections,- what each refusal means, and the approval rule for any action that moves- money or creates a card.+ X Money error, refusal, or missing capability. Covers the approval rule for+ every action that moves money (always ask, every time, no exceptions), how+ the connection works (connection code plus passkey in the X app), how to+ guide the user through connect, reconnect, and revoke at+ x.com/i/money/settings/connections, and what each failure message means.---# X Money guide-This plugin uses the **X Money MCP** at `https://mcp.money.x.com/mcp`. The user connects once. The Cursor backend holds the tokens and refreshes them. The agent never sees tokens, card numbers in chat, passwords, or passkeys.+This plugin connects the agent to the user's X Money account through the **X Money MCP** at `https://mcp.money.x.com/mcp`. The user connects once in Grok Bot. From then on the Cursor backend holds the connection and the agent calls X Money on the user's behalf.-Discover the available actions from the server's tool list. The server is the source of truth for what the user can do and for every schema. Do not assume an action exists because it is mentioned here.+Discover what the user can do from the server's tool list. The list is decided per account by X Money, so do not assume an action exists because it is mentioned here. Every result carries a `message` written for the user. Relay it in your own words instead of describing internals.-## Approval rule+## Always confirm before moving money-Sending money, requesting money, and creating a virtual card move real money. Before each such call, ask the user for approval with a `SendToUser` widget that states the exact action in one sentence: amount, recipient or merchant, and purpose. Call the tool only after the user picks Approve. Never batch approvals. Never infer approval from an earlier message.+Some actions move real money or create a way to spend it: sending money, requesting money, and paying a merchant. For each one:-A tool result with `outcome: "refused"` is final. Relay its `message` to the user in plain words. Do not retry a refused call and do not change the amount to get around it.+1. **Ask first, every time.** Send a `SendToUser` widget with **Approve** and **Cancel**. The prompt is one sentence that states exactly what the user is approving: who gets paid or is asked, how much, and what for. For a purchase: the item, the merchant, and the total. Put the breakdown (items, shipping, tax, fees) in the help text. If the amount is an estimate, say so.+2. **Wait for the answer.** Call the tool only after the user picks Approve. If they pick Cancel, or do not answer, do nothing and say so.+3. **Approve one action at a time.** Never batch several payments under one approval. Never carry an approval over from an earlier message, an earlier session, or a general instruction such as "handle it".+4. **Re-ask when anything changes.** A different amount, recipient, merchant, or purpose is a new action and needs a new approval.+5. **Never fake it.** Every money-moving tool has an approval input. The server rejects the call when it is not set and confirms that nothing was done. Set it only after a real Approve in this conversation.++Ask for balances and transactions freely. Those are read-only.## How the connection works1. The user taps **Connect** on the X Money plugin in Grok Bot.-2. A browser opens the X Money consent page. It shows a **connection code** and a QR code.-3. The user opens the code in the **X app** on the account that owns the X Money account, then approves with their **passkey**.-4. The consent page detects the approval and returns to Grok Bot. The connection is complete.+2. A page titled **Connect Grok Bot to X Money** opens. It shows a **connection code** and a QR code.+3. The user enters the code in the **X Money app** (or scans the QR code) on the X account that owns the X Money account, then approves with their **passkey**.+4. The page shows **Connected. You can return to Grok Bot.** and the connection completes on its own.-The connection code expires after **5 minutes**. Access tokens live 15 minutes and refresh automatically. The connection stays valid until the user revokes it or it goes unused for 45 days.+The code is valid for about 5 minutes. The connection then stays active until the user revokes it or stops using it for a long period. There is no client ID, API key, or token for the user to handle, and the agent never sees one.## Connections screen@@ -36,87 +42,131 @@ The connection code expires after **5 minutes**. Access tokens live 15 minutes aSend the user here to:-- see which agents are connected to X Money,+- see which agents are connected to X Money and what each one can do,- revoke Grok Bot's access,- confirm that a connection they just approved is listed.-Revoking on this screen ends the connection immediately. The next Grok Bot call fails with an auth error and the user must connect again.+Revoking ends the connection at once. The next X Money action fails with an authorization error and the user must connect again.## Troubleshooting-Match the situation, say the quoted line in your own voice, then give the one next step. Do not explain OAuth, tokens, or backend internals.+Match the situation, say the quoted line in your own voice, then give the one next step. Do not explain OAuth, tokens, grants, or the backend.++### Not connected, or authorization error on a call++Signals: X Money shows as needing authorization, no X Money tools are listed, or a call fails with `401` or `invalid bearer token`.-### Not connected, or auth error on a call+> Your X Money connection is not active. Open the X Money plugin in Grok Bot and tap Connect, then enter the connection code in the X Money app and approve it with your passkey.-Signals: no X Money tools in the tool list, `401`, `invalid_token`, `grant has been revoked`, `refresh token has expired`, `refresh token does not exist`.+If the user says they did not revoke anything, still reconnect. There is no other way to restore a connection.-> Your X Money connection is not active. Open the X Money plugin in Grok Bot and tap Connect, then approve the connection code in the X app with your passkey.+### "This code has expired. Start again from Grok Bot."-If the user says they did not revoke anything, still reconnect. A revoked or expired connection cannot be restored any other way.+The consent page says this after about 5 minutes.-### Connection code expired+> The connection code expired. Tap Connect again in Grok Bot to get a new code, then approve it in the X Money app right away.-Signal: the consent page says the code expired, or the user waited more than 5 minutes.+### "This connection was not approved."-> The connection code expired. Tap Connect again in Grok Bot to get a new code, then approve it in the X app within 5 minutes.+The user declined in the X Money app.-### Code rejected in the X app+> The connection was declined. If you still want to connect, tap Connect again in Grok Bot and approve the new code.-Signal: the X app says the code is invalid.+### "The connection code is invalid, expired, or already used."-Ask which X account they are signed into. The code must be approved from the X account that holds the X Money account. If it is the right account, tell them to restart from Connect. Codes are single-use and tied to one connection attempt.+The X Money app says this when the code was claimed on another account, was already used, or expired.++Ask which X account they are signed into in the X Money app. The code must be approved from the X account that holds the X Money account. Each code works once. Tell them to start again from Connect.### Passkey step fails-Signal: the X app cannot complete the passkey challenge.+The X Money app cannot complete the passkey challenge.> Approving an agent connection needs a passkey on your X account. Set one up in X → Settings → Security, then approve the connection again.-### New connections not accepted+### "New customer connections are not currently accepted."-Signal: `new customer connections are not currently accepted`.+The connection was approved but X Money did not activate it. This is a staged rollout, not an account problem.-> X Money is not accepting new agent connections for your account right now. This is a staged rollout, not a problem with your account. Try again later.+> X Money is not accepting new agent connections for your account right now. Try again later.Do not suggest workarounds.-### Action missing or "not ready for you yet"+### "Something went wrong. Refresh this page to try again." or "Something went wrong. Try again."++A transient error on the consent page.-Signals: an action the user asks for has no matching tool while other X Money tools work, or a call returns `This X Money MCP tool isn't ready for you yet.`+> Refresh the page. If it fails again, tap Connect in Grok Bot to start over.++### "This X Money MCP tool isn't ready for you yet." or an action is missing++X Money enables actions per account. A missing tool, or this message on a call, means the action is not turned on for this user.> That X Money action is not enabled for your account yet.-Offer the actions that are present. Do not tell the user to reinstall or reconnect; the tool set is decided per account by X Money.+Offer the actions that are present. Do not tell the user to reinstall or reconnect.++### "Not authorized to call tool"++The user's role on the account does not allow this action, for example a member of a joint account.++> Your X Money account does not allow that action from here. You can do it in the X Money app.++### "MCP is not enabled"++X Money has paused agent access for everyone.++> X Money is temporarily unavailable to agents. Try again later.### User has no X Money account-Signal: the consent page or the X app says the user cannot use X Money, or the user says they never set it up.+The consent page or the X Money app says the user cannot use X Money, or the user says they never set it up.> X Money is available to eligible customers in the United States. Set up X Money in the X app first, then connect it here.-## Refusals when sending or requesting money+## Reading payment results++Every send or request returns an `outcome` and a `message`.-Relay the `message` from the result. Common ones and what to add:+| Outcome | Meaning | What to do |+| --- | --- | --- |+| `completed` | The money moved, or the request reached the other person | Relay the message |+| `pending` | X Money is reviewing it, or the other person has to act | Relay the message. Do not send again. The user can watch it in the X Money app |+| `refused` | X Money did not make it | Relay the message. **Never retry a refusal** and never change the amount to get around it |++Common refusal messages and what to add:| Message contains | Add || --- | --- |-| `verify this payment in the X Money app` | The user can send it themselves in the X app. Agents cannot complete verification steps. |-| `sending limits` or `Too many transfers` | Agent payments have their own daily caps on top of the account limits. Try again later or pay in the X app. |-| `balance is too low` | Check the balance and suggest a smaller amount, or adding funds in the X app. |-| `No X user named` | Confirm the @handle. Handles change; a numeric user id is more stable. |+| `verify this payment in the X Money app` | Agents cannot complete verification. The user can send it themselves in the X app. |+| `per-payment limit for agents` or `Agents can't move money for this account` | Agent payments have their own limits. The user can do this in the X Money app. |+| `sending limits` or `Too many transfers` | Try again later or pay in the X Money app. |+| `balance is too low` | Check the balance and offer a smaller amount, or adding funds in the X app. |+| `No X user named` | Confirm the @handle. Handles change; a numeric X user id is more stable. |+| `isn't on X Money yet` | The other person has to set up X Money before they can be paid or asked. |+| `own X account` | Pick another X user. || `only accepts money from people they follow` | Nothing to fix from here. |-| `could not confirm` | Do not send again. Tell the user to check the transaction in the X app. |-| `Agents can't move money for this account right now` | Agent payments are switched off for this account. Pay in the X app. |+| `different currencies` or `can't receive` or `can't send` | Nothing to fix from here. Pay in the X Money app. |+| `X Money did not allow this payment` | X Money blocked it and gives no further reason. Do not retry. |++Two results are not outcomes but errors, and both matter:++- **`X Money could not process this right now; try again later`** — a transient failure. Nothing moved. Tell the user. Retry once later only if they still want it, with a fresh approval.+- **`X Money accepted this payment but could not confirm it. Do not send it again`** — the payment may have gone through. **Never send it again.** Tell the user to check the transaction in the X Money app.++When you retry the very same payment after a network failure, reuse the same idempotency key so X Money never makes it twice. A reused key returns the earlier result and says so.-## Virtual cards+## Purchases with a card-- One card is valid for one merchant and one purchase. Never reuse a card or split a purchase across cards.-- A result that says the daily card count or spend is used up includes `limits_reset_at`. Tell the user when limits reset. Do not create another card.-- Card details go straight into the merchant checkout. Never print the card number, CVC, or expiry in chat.+- Approve the purchase itself: item, merchant, and total. The card X Money issues is not what the user approves.+- If the result says **no card was created** because a daily limit is reached, it names when limits reset. Tell the user and stop. Do not try again today.+- `failed to create card, try again` is transient. One retry is fine, with the same approval.+- Card details go straight into the merchant checkout. Never print the card number, CVC, or expiry in chat, and never store them.-## What not to do+## Never- Never ask the user for an X Money password, passkey, card number, or bank login.- Never ask the user to paste a token or code into chat.-- Never retry a `401`, a refusal, or a limits result unchanged.-- Never move money without a fresh approval for that exact action.+- Never move money, request money, or create a card without a fresh approval for that exact action.+- Never retry a refusal, an unconfirmed payment, or a limit result.+- Never explain tokens, grants, or the backend. Name the situation and the next step.