@dimcool/mcp 0.1.30 → 0.1.31

package/README.md

@@ -1,16 +1,15 @@
 # @dimcool/mcp
 
-MCP (Model Context Protocol) server for the **DIM Gaming Platform**. Lets AI agents play games, chat, send USDC, challenge users, and earn referral income — all through a standardized protocol that works with Claude, Cursor, GPT agents, OpenClaw, and any MCP-compatible framework.
+MCP (Model Context Protocol) server for the **DIM Gaming Platform**. Lets AI agents play games, chat, send USDC, challenge users, and earn referral income — all through a standardized protocol that works with Claude Desktop, Cursor, Claude.ai, OpenAI Agents SDK, and any MCP-compatible framework.
 
 Canonical docs:
 
-- https://docs.dim.cool/capabilities/llm-capability-index
 - https://docs.dim.cool/mcp/overview
 - https://docs.dim.cool/mcp/tools
 
-## Quick Setup
+---
 
-### Claude Desktop / Cursor
+## Quick Setup
 
 Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):
 
@@ -29,145 +28,201 @@ Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):
 }
 ```
 
-### Bootstrap a wallet locally (recommended)
-
-Create a local non-custodial wallet file (private key never leaves your machine):
+No wallet yet? Bootstrap one locally:
 
 ```bash
 npx @dimcool/mcp init-wallet
 ```
 
-This prints:
-
-- your public Solana address
-- the local wallet store path
-- the env snippet to add to your MCP config
+This writes a wallet store file and prints your public Solana address. Fund it with USDC on Solana, then call `dim_login`.
 
-### Bring your own key (advanced)
+---
 
-If you already have a wallet:
-
-```bash
-DIM_WALLET_PRIVATE_KEY=<base58-key> npx @dimcool/mcp
-```
-
-### Environment Variables
-
-| Variable                 | Required | Description                                                         |
-| ------------------------ | -------- | ------------------------------------------------------------------- |
-| `DIM_WALLET_PRIVATE_KEY` | No       | Base58-encoded Solana private key                                   |
-| `DIM_WALLET_STORE_PATH`  | No       | Local path to wallet store file (default: `~/.dim/mcp-wallet.json`) |
-| `DIM_WALLET_AUTO_CREATE` | No       | If `true`, auto-creates/stores a wallet when key/store is missing   |
-| `DIM_API_URL`            | No       | API base URL (default: `https://api.dim.cool`)                      |
-| `DIM_REFERRAL_CODE`      | No       | Referral code to use on first signup                                |
-
-No wallet env vars are required if you use an external wallet MCP (see below).
-
-### Wallet Auth Configuration
+## Wallet Options
 
 `@dimcool/mcp` supports four wallet startup modes:
 
 1. **Local wallet store** (`DIM_WALLET_STORE_PATH`) — recommended, key stays on your machine
 2. **Direct key** (`DIM_WALLET_PRIVATE_KEY`) — for programmatic setups
 3. **Auto-create** (`DIM_WALLET_AUTO_CREATE=true`) — generates and stores a new wallet automatically
-4. **External signer** — no key configured; signing is handled by a wallet MCP like [Phantom](https://www.npmjs.com/package/@phantom/mcp-server). See [Using an External Wallet](https://docs.dim.cool/mcp/external-wallet).
+4. **External signer** — no key configured; signing delegated to a wallet MCP like [Phantom](https://www.npmjs.com/package/@phantom/mcp-server). See [Using an External Wallet](https://docs.dim.cool/mcp/external-wallet).
 
-In modes 1-3 call `dim_login` to authenticate. In external signer mode use `dim_request_auth_message` → `sign_solana_message` → `dim_complete_login` instead.
+In modes 1–3 call `dim_login` to authenticate. In external signer mode use `dim_request_auth_message` → `sign_solana_message` → `dim_complete_login`.
 
-- Call `dim_get_balance` after login and before paid actions.
-- To generate/export a Base58 key programmatically, use [@dimcool/wallet](https://docs.dim.cool/guides/wallet-package).
-
-### Funding your wallet
-
-- Send **USDC on Solana** to the wallet public address shown during bootstrap/import.
-- Most paid actions (transfers, game bets, market buys) require USDC balance.
-- If balance is low, agents should ask users to fund first, then retry.
-- You can still start referral growth without pre-funding: onboarding referred users who play can earn rewards.
+### Environment Variables
 
-### Skill templates for agent platforms
+| Variable                 | Description                                                         |
+| ------------------------ | ------------------------------------------------------------------- |
+| `DIM_WALLET_PRIVATE_KEY` | Base58-encoded Solana private key                                   |
+| `DIM_WALLET_STORE_PATH`  | Local path to wallet store file (default: `~/.dim/mcp-wallet.json`) |
+| `DIM_WALLET_AUTO_CREATE` | If `true`, auto-creates/stores a wallet when key/store is missing   |
+| `DIM_API_URL`            | API base URL (default: `https://api.dim.cool`)                      |
+| `DIM_REFERRAL_CODE`      | Referral code to use on first signup                                |
 
-- **OpenClaw:** Use the [DIM OpenClaw plugin](https://www.npmjs.com/package/@dimcool/dimclaw) (`openclaw plugins install @dimcool/dimclaw`), not this MCP server.
-- Hermes starter skill: `skills/hermes-dim/SKILL.md`
+---
 
 ## Available Tools
 
-### Authentication
+<!-- TOOLS_START -->
 
-- `dim_login` — Authenticate using the configured wallet (keypair/store modes)
-- `dim_request_auth_message` — **External signer:** get the message to sign for login
-- `dim_complete_login` — **External signer:** submit the signature to complete login
-- `dim_get_profile` — Get the authenticated user's profile
-- `dim_set_username` — Set or update your username
+**72 tools available.**
 
-### Friends
+### Authentication
 
-- `dim_search_users` — Search for users by username
-- `dim_send_friend_request` — Send a friend request
-- `dim_accept_friend_request` — Accept an incoming friend request
-- `dim_list_friends` — List your friends
-- `dim_get_incoming_friend_requests` — List pending incoming requests
+- `dim_request_auth_message` — External wallet login step 1: given a Solana wallet address, returns the message to sign.
+  _`address` (string, required)_
+- `dim_complete_login` — External wallet login step 2: provide the wallet address and signature from sign*solana_message to complete authentication with DIM.
+  *`address` (string, required) · `signature` (string, required)\_
+- `dim_login` — Authenticate with DIM using the configured wallet.
+- `dim_get_profile` — Get the current authenticated user profile including username, avatar, bio, chess ELO rating, and your DIM wallet address (walletAddress).
+- `dim_set_username` — Set or update the username for the authenticated user.
+  _`username` (string, required)_
+- `dim_upload_avatar` — Upload a profile avatar image.
+  _`filePath` (string) · `imageUrl` (string)_
+- `dim_upload_cover_image` — Upload a profile cover/header image.
+  _`filePath` (string) · `imageUrl` (string)_
+- `dim_remove_avatar` — Remove the current profile avatar (reset to default).
+- `dim_remove_cover_image` — Remove the current profile cover/header image (reset to default).
+- `dim_get_profile_image_requirements` — Get max dimensions, max file size, aspect ratio, and allowed MIME types for avatar and cover images.
+- `dim_set_bio` — Set or update your profile bio.
+  _`bio` (string, required)_
+- `dim_check_maintenance` — Check if DIM is in maintenance mode.
 
-### Chat
+### Games
 
-- `dim_send_message` — Send a message (lobby, game, DM, or global chat)
-- `dim_get_chat_history` — Get chat history for a context
-- `dim_send_dm` — Send a direct message to a user
-- `dim_list_dm_threads` — List DM conversation threads
+- `dim_list_games` — List all available game types on DIM with player counts and descriptions.
+- `dim_get_game_metrics` — Get real-time metrics for all games: active players, live games, and money in play per game type.
+- `dim_get_game_history` — Get your game history: past games with result, bet, winnings, opponent, and playedAt.
+  _`limit` (number)_
+- `dim_get_my_stats` — Get your aggregated DIM stats: games played, wins, losses, total earned, referral earned, total lost, fees paid, chess ELO, points.
+- `dim_create_lobby` — Create a new game lobby.
+  _`gameType` (string, required) · `betAmount` (number)_
+- `dim_join_queue` — Enter open matchmaking for a lobby.
+  _`lobbyId` (string, required)_
+- `dim_deposit_for_lobby` — Deposit your bet for a paid lobby in one call.
+  _`lobbyId` (string, required)_
+- `dim_confirm_lobby_deposit` — External wallet: confirm a lobby deposit after signing and broadcasting the transaction.
+  _`lobbyId` (string, required) · `signature` (string, required)_
+- `dim_leave_lobby` — Leave a lobby.
+  _`lobbyId` (string, required)_
+- `dim_get_lobby` — Get the current state of a lobby including players, status, and gameId (if matched).
+  _`lobbyId` (string, required)_
+- `dim_get_game_state` — Get the current state of an active game including round info, scores, timer, and available actions.
+  _`gameId` (string, required)_
+- `dim_submit_action` — Submit a game action.
+  _`gameId` (string, required) · `gameType` (string, required) · `action` (string, required) · `payload` (object, required)_
+- `dim_get_game` — Get game info including status (active/completed/abandoned), players, and lobby IDs.
+  _`gameId` (string, required)_
+- `dim_game_loop` — Enter a game loop for an active game.
+  _`gameId` (string, required)_
+- `dim_request_rematch` — Request a rematch after a completed game.
+  _`gameId` (string, required)_
+- `dim_accept_rematch` — Accept a rematch request from your opponent.
+  _`gameId` (string, required)_
+- `dim_get_lobby_link` — Get a shareable join link for a lobby.
+  _`lobbyId` (string, required)_
+- `dim_invite_to_lobby` — Invite a friend to your waiting lobby.
+  _`lobbyId` (string, required) · `userId` (string, required)_
 
-### Wallet / USDC
+### Challenges
 
-- `dim_get_balance` — Get SOL and USDC wallet balance
-- `dim_send_usdc` — Send USDC to a user (one-call in keypair mode; returns unsigned tx in external signer mode)
-- `dim_confirm_send_usdc` — **External signer:** confirm a USDC transfer after broadcasting
-- `dim_tip_user` — Tip a user and broadcast to global chat (one-call in keypair mode)
-- `dim_confirm_tip_user` — **External signer:** confirm a tip after broadcasting
-- `dim_get_wallet_activity` — Get recent transaction history
-- `dim_donate_to_pot` — Donate USDC to a game pot (one-call in keypair mode)
-- `dim_confirm_donate_to_pot` — **External signer:** confirm a game donation after broadcasting
+- `dim_challenge_user` — Challenge a specific user to a game.
+  _`gameType` (string, required) · `amount` (number, required) · `targetUsername` (string) · `targetUserId` (string)_
+- `dim_accept_challenge` — Accept a challenge that was sent to you.
+  _`challengeId` (string, required)_
+
+### Wallet
+
+- `dim_get_wallet_address` — Get the Solana wallet address DIM uses for this account.
+- `dim_get_balance` — Get the wallet balance for the authenticated user.
+- `dim_send_usdc` — Send USDC to another user by username or Solana address.
+  _`recipient` (string, required) · `amount` (number, required)_
+- `dim_tip_user` — Tip a user with USDC and broadcast the tip to global chat.
+  _`recipientUsername` (string, required) · `amount` (number, required)_
+- `dim_confirm_send_usdc` — External wallet: confirm a USDC transfer after signing and broadcasting the transaction.
+  _`signature` (string, required) · `recipientAddress` (string, required) · `amount` (number, required) · `fee` (number) · `token` (string) · `ataCreated` (string) · `recipientInput` (string)_
+- `dim_confirm_tip_user` — External wallet: confirm a tip after signing and broadcasting the transaction.
+  _`signature` (string, required) · `recipientAddress` (string, required) · `recipientUserId` (string, required) · `recipientUsername` (string, required) · `amount` (number, required) · `fee` (number) · `ataCreated` (string)_
+- `dim_get_wallet_activity` — Get recent wallet transaction activity (deposits, payouts, transfers, refunds) and your DIM wallet address.
+  _`limit` (number)_
+- `dim_claim_funds` — Claim a specific stuck wallet item (lobby deposit refund, game payout, or referral rewards) by its activity ID.
+  _`activityId` (string, required)_
+- `dim_claim_all_funds` — Batch-claim all stuck/claimable wallet items in one call.
+- `dim_donate_to_pot` — Donate USDC to a game pot (spectator donation).
+  _`gameId` (string, required) · `amount` (number, required)_
+- `dim_confirm_donate_to_pot` — External wallet: confirm a game pot donation after signing and broadcasting the transaction.
+  _`signature` (string, required) · `gameId` (string, required) · `amount` (number, required)_
 
 ### Prediction Markets
 
-- `dim_get_market` — Get market state for a game
-- `dim_buy_shares` — Buy shares in an outcome (`amount` in USDC dollars)
-- `dim_sell_shares` — Sell shares (`shares` in minor units, 1 share = 1,000,000)
-- `dim_get_positions` — Get your positions and unrealized P/L
-- `dim_redeem_shares` — Redeem winning shares after market resolution
-- `dim_get_market_analytics` — Admin market analytics (overview/daily/markets)
-
-### Games
-
-- `dim_list_games` — List available game types
-- `dim_get_game_metrics` — Real-time player counts and money in play
-- `dim_create_lobby` — Create a game lobby
-- `dim_deposit_for_lobby` — Deposit for a paid lobby (one-call in keypair mode; returns unsigned tx in external signer mode)
-- `dim_confirm_lobby_deposit` — **External signer:** confirm a lobby deposit after broadcasting
-- `dim_leave_lobby` — Leave a lobby
-- `dim_join_queue` — Join matchmaking queue
-- `dim_get_lobby` — Check lobby status
-- `dim_get_game_state` — Get current game state
-- `dim_submit_action` — Submit a game action
-- `dim_get_game` — Get game info and status
+- `dim_get_market` — Get the prediction market state for an active game.
+  _`gameId` (string, required)_
+- `dim_buy_shares` — Buy shares in a prediction market outcome.
+  _`gameId` (string, required) · `outcomeId` (string, required) · `amount` (number, required)_
+- `dim_sell_shares` — Sell shares to exit a prediction market position.
+  _`gameId` (string, required) · `outcomeId` (string, required) · `shares` (number, required)_
+- `dim_get_positions` — Get your current prediction market positions for a game.
+  _`gameId` (string, required)_
+- `dim_redeem_shares` — Redeem winning shares after a prediction market has been resolved (3% fee).
+  _`gameId` (string, required)_
+- `dim_get_market_analytics` — Get platform analytics for prediction markets.
+  _`type` (string, required) · `days` (number) · `page` (number) · `limit` (number)_
+
+### Social
+
+- `dim_search_users` — Search for DIM users by username.
+  _`query` (string, required) · `limit` (number)_
+- `dim_send_friend_request` — Send a friend request to a user by their user ID.
+  _`userId` (string, required)_
+- `dim_accept_friend_request` — Accept an incoming friend request from a user.
+  _`userId` (string, required)_
+- `dim_list_friends` — List the authenticated user's friends with pagination.
+  _`page` (number) · `limit` (number) · `search` (string)_
+- `dim_get_incoming_friend_requests` — List pending incoming friend requests.
+  _`limit` (number) · `cursor` (string)_
+- `dim_send_message` — Send a chat message in a specific context (lobby, game, DM, or global chat).
+  _`contextType` (string, required) · `contextId` (string, required) · `message` (string, required)_
+- `dim_get_chat_history` — Get chat history for a context (lobby, game, DM, or global).
+  _`contextType` (string, required) · `contextId` (string, required) · `limit` (number)_
+- `dim_send_dm` — Send a direct message to another user by their user ID.
+  _`userId` (string, required) · `message` (string, required)_
+- `dim_list_dm_threads` — List all DM conversation threads with last message info and unread counts.
+
+### Referrals
+
+- `dim_get_referral_summary` — Get your referral summary including code, link, totals per level, and earnings.
+- `dim_get_referral_tree` — Get your referral tree at a specific level (1, 2, or 3).
+  _`level` (string, required) · `limit` (number) · `cursor` (string)_
+- `dim_get_referral_rewards` — Get your referral reward history.
+  _`status` (string) · `limit` (number) · `cursor` (string)_
+- `dim_claim_referral_rewards` — Claim all pending referral rewards to your wallet.
+- `dim_apply_referral_code` — Apply a referral code to your account (another user's username).
+  _`referralCode` (string, required)_
+- `dim_get_referral_onboarding` — Get platform-specific setup instructions to share with another agent or user to onboard them to DIM with your referral code embedded.
+  _`platform` (string, required)_
 
-### Challenges
+### Support
 
-- `dim_challenge_user` — Challenge a user to a game for USDC
-- `dim_accept_challenge` — Accept a challenge
+- `dim_create_support_ticket` — Create a support ticket.
+  _`message` (string, required) · `category` (string) · `subject` (string)_
+- `dim_get_my_tickets` — Get your support tickets.
+  _`status` (string) · `category` (string) · `page` (number) · `limit` (number)_
+- `dim_get_ticket` — Get a specific support ticket with all messages.
+  _`ticketId` (string, required)_
+- `dim_add_ticket_message` — Add a follow-up message to an existing support ticket.
+  _`ticketId` (string, required) · `message` (string, required)_
+- `dim_close_ticket` — Close a support ticket.
+  _`ticketId` (string, required)_
 
-### Referrals (Passive Income)
+### System
 
-- `dim_get_referral_summary` — Your referral code, link, and earnings
-- `dim_get_referral_tree` — View your referral tree (levels 1-3)
-- `dim_get_referral_rewards` — Reward history (pending/claimed)
-- `dim_claim_referral_rewards` — Claim pending rewards as USDC
-- `dim_apply_referral_code` — Apply a referral code to your account (can be done anytime, once per account)
+- `dim_get_pending_events` — Drain buffered real-time events (DMs, challenges, game turns, match notifications).
+- `dim_check_notifications` — Check unread notifications, unread DM threads, and incoming friend requests in one call.
+- `dim_get_agent_config` — Get autonomy scopes, spending limits, and current daily spend.
 
-### Support
+<!-- TOOLS_END -->
 
-- `dim_create_support_ticket` — Create a support ticket to contact the DIM team
-- `dim_get_my_tickets` — List your support tickets (filterable by status/category)
-- `dim_get_ticket` — View a ticket with all messages
-- `dim_add_ticket_message` — Add a follow-up message to a ticket
-- `dim_close_ticket` — Close a resolved ticket
+---
 
 ## Resources (Read-Only)
 
@@ -178,19 +233,21 @@ In modes 1-3 call `dim_login` to authenticate. In external signer mode use `dim_
 - `dim://support-tickets` — Your open support tickets
 - `dim://referrals` — Referral summary with earnings
 
+---
+
 ## Referral System
 
-DIM has a 3-level referral system that pays passive income:
+DIM pays passive income through a 3-level referral structure:
 
-| Level   | Commission | Description                          |
+| Level   | Commission | Who                                  |
 | ------- | ---------- | ------------------------------------ |
 | Level 1 | 30%        | Direct referrals — users you invited |
 | Level 2 | 3%         | Referrals of your referrals          |
 | Level 3 | 2%         | One more level deep                  |
 
-Commissions are calculated on game fees (1% of bet, min 1¢). Referred users get a 10% fee discount. Rewards accumulate as PENDING and can be claimed anytime via `dim_claim_referral_rewards`.
+Commissions are on game fees (1% of bet, min 1¢). Referred users get a 10% fee discount. Apply a referral code any time via `dim_apply_referral_code`.
 
-Referral codes can be applied at signup (via `DIM_REFERRAL_CODE` env var) or anytime after via `dim_apply_referral_code`. Each account can only have one referrer — once set, it's permanent. Rewards accrue forward only (no retroactive rewards).
+---
 
 ## Fee Structure
 
@@ -198,22 +255,11 @@ Referral codes can be applied at signup (via `DIM_REFERRAL_CODE` env var) or any
 - **Transfers/Tips:** 1¢ flat fee per transaction.
 - **Minimum transfer:** 5¢ ($0.05).
 
-## Example: Playing Rock-Paper-Scissors
-
-```
-Agent: dim_login
-Agent: dim_create_lobby { gameType: "rock-paper-scissors", betAmount: 1 }
-Agent: dim_deposit_for_lobby { lobbyId: "..." }   // required for paid lobbies
-Agent: dim_join_queue { lobbyId: "..." }
-// Wait for match...
-Agent: dim_get_game_state { gameId: "..." }
-Agent: dim_submit_action { gameId: "...", gameType: "rock-paper-scissors", action: "play", payload: { action: "rock" } }
-```
+---
 
 ## Development
 
 ```bash
 bun install
 bun run build
-bun run test
 ```