@dimcool/mcp 0.1.29 → 0.1.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +173 -117
  2. package/dist/index.js +1245 -173
  3. package/dist/server.d.ts +31 -0
  4. package/dist/server.js +19465 -0
  5. package/package.json +5 -1
package/README.md CHANGED
@@ -1,16 +1,15 @@
1
1
  # @dimcool/mcp
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  Canonical docs:
6
6
 
7
- - https://docs.dim.cool/capabilities/llm-capability-index
8
7
  - https://docs.dim.cool/mcp/overview
9
8
  - https://docs.dim.cool/mcp/tools
10
9
 
11
- ## Quick Setup
10
+ ---
12
11
 
13
- ### Claude Desktop / Cursor
12
+ ## Quick Setup
14
13
 
15
14
  Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):
16
15
 
@@ -29,135 +28,201 @@ Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):
29
28
  }
30
29
  ```
31
30
 
32
- ### Bootstrap a wallet locally (recommended)
33
-
34
- Create a local non-custodial wallet file (private key never leaves your machine):
31
+ No wallet yet? Bootstrap one locally:
35
32
 
36
33
  ```bash
37
34
  npx @dimcool/mcp init-wallet
38
35
  ```
39
36
 
40
- This prints:
37
+ This writes a wallet store file and prints your public Solana address. Fund it with USDC on Solana, then call `dim_login`.
41
38
 
42
- - your public Solana address
43
- - the local wallet store path
44
- - the env snippet to add to your MCP config
39
+ ---
45
40
 
46
- ### Bring your own key (advanced)
41
+ ## Wallet Options
47
42
 
48
- If you already have a wallet:
43
+ `@dimcool/mcp` supports four wallet startup modes:
49
44
 
50
- ```bash
51
- DIM_WALLET_PRIVATE_KEY=<base58-key> npx @dimcool/mcp
52
- ```
53
-
54
- ### Environment Variables
45
+ 1. **Local wallet store** (`DIM_WALLET_STORE_PATH`) — recommended, key stays on your machine
46
+ 2. **Direct key** (`DIM_WALLET_PRIVATE_KEY`) — for programmatic setups
47
+ 3. **Auto-create** (`DIM_WALLET_AUTO_CREATE=true`) — generates and stores a new wallet automatically
48
+ 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).
55
49
 
56
- | Variable | Required | Description |
57
- | ------------------------ | -------- | ------------------------------------------------------------------- |
58
- | `DIM_WALLET_PRIVATE_KEY` | No\* | Base58-encoded Solana private key |
59
- | `DIM_WALLET_STORE_PATH` | No | Local path to wallet store file (default: `~/.dim/mcp-wallet.json`) |
60
- | `DIM_WALLET_AUTO_CREATE` | No | If `true`, auto-creates/stores a wallet when key/store is missing |
61
- | `DIM_API_URL` | No | API base URL (default: `https://api.dim.cool`) |
62
- | `DIM_REFERRAL_CODE` | No | Referral code to use on first signup |
50
+ In modes 1–3 call `dim_login` to authenticate. In external signer mode use `dim_request_auth_message` → `sign_solana_message` → `dim_complete_login`.
63
51
 
64
- \*Required if you do not use wallet store or auto-create.
65
-
66
- ### Wallet Auth Configuration
67
-
68
- - `@dimcool/mcp` supports three wallet startup modes:
69
- 1. direct key (`DIM_WALLET_PRIVATE_KEY`)
70
- 2. local wallet store (`DIM_WALLET_STORE_PATH`)
71
- 3. auto-create (`DIM_WALLET_AUTO_CREATE=true`)
72
- - Call `dim_login` before any wallet, games, chat, social, referrals, support, or market tools.
73
- - Call `dim_get_balance` after login and before paid actions.
74
- - To generate/export a Base58 key programmatically, use [@dimcool/wallet](https://docs.dim.cool/guides/wallet-package).
75
-
76
- ### Funding your wallet
77
-
78
- - Send **USDC on Solana** to the wallet public address shown during bootstrap/import.
79
- - Most paid actions (transfers, game bets, market buys) require USDC balance.
80
- - If balance is low, agents should ask users to fund first, then retry.
81
- - You can still start referral growth without pre-funding: onboarding referred users who play can earn rewards.
52
+ ### Environment Variables
82
53
 
83
- ### Skill templates for agent platforms
54
+ | Variable | Description |
55
+ | ------------------------ | ------------------------------------------------------------------- |
56
+ | `DIM_WALLET_PRIVATE_KEY` | Base58-encoded Solana private key |
57
+ | `DIM_WALLET_STORE_PATH` | Local path to wallet store file (default: `~/.dim/mcp-wallet.json`) |
58
+ | `DIM_WALLET_AUTO_CREATE` | If `true`, auto-creates/stores a wallet when key/store is missing |
59
+ | `DIM_API_URL` | API base URL (default: `https://api.dim.cool`) |
60
+ | `DIM_REFERRAL_CODE` | Referral code to use on first signup |
84
61
 
85
- - **OpenClaw:** Use the [DIM OpenClaw plugin](https://www.npmjs.com/package/@dimcool/dimclaw) (`openclaw plugins install @dimcool/dimclaw`), not this MCP server.
86
- - Hermes starter skill: `skills/hermes-dim/SKILL.md`
62
+ ---
87
63
 
88
64
  ## Available Tools
89
65
 
90
- ### Authentication
66
+ <!-- TOOLS_START -->
91
67
 
92
- - `dim_login` — Authenticate with DIM using the configured wallet
93
- - `dim_get_profile` — Get the authenticated user's profile
94
- - `dim_set_username` — Set or update your username
68
+ **72 tools available.**
95
69
 
96
- ### Friends
70
+ ### Authentication
97
71
 
98
- - `dim_search_users` — Search for users by username
99
- - `dim_send_friend_request` — Send a friend request
100
- - `dim_accept_friend_request` — Accept an incoming friend request
101
- - `dim_list_friends` — List your friends
102
- - `dim_get_incoming_friend_requests` — List pending incoming requests
72
+ - `dim_request_auth_message` — External wallet login step 1: given a Solana wallet address, returns the message to sign.
73
+ _`address` (string, required)_
74
+ - `dim_complete_login` — External wallet login step 2: provide the wallet address and signature from sign*solana_message to complete authentication with DIM.
75
+ *`address` (string, required) · `signature` (string, required)\_
76
+ - `dim_login` — Authenticate with DIM using the configured wallet.
77
+ - `dim_get_profile` — Get the current authenticated user profile including username, avatar, bio, chess ELO rating, and your DIM wallet address (walletAddress).
78
+ - `dim_set_username` — Set or update the username for the authenticated user.
79
+ _`username` (string, required)_
80
+ - `dim_upload_avatar` — Upload a profile avatar image.
81
+ _`filePath` (string) · `imageUrl` (string)_
82
+ - `dim_upload_cover_image` — Upload a profile cover/header image.
83
+ _`filePath` (string) · `imageUrl` (string)_
84
+ - `dim_remove_avatar` — Remove the current profile avatar (reset to default).
85
+ - `dim_remove_cover_image` — Remove the current profile cover/header image (reset to default).
86
+ - `dim_get_profile_image_requirements` — Get max dimensions, max file size, aspect ratio, and allowed MIME types for avatar and cover images.
87
+ - `dim_set_bio` — Set or update your profile bio.
88
+ _`bio` (string, required)_
89
+ - `dim_check_maintenance` — Check if DIM is in maintenance mode.
103
90
 
104
- ### Chat
91
+ ### Games
105
92
 
106
- - `dim_send_message` — Send a message (lobby, game, DM, or global chat)
107
- - `dim_get_chat_history` — Get chat history for a context
108
- - `dim_send_dm` — Send a direct message to a user
109
- - `dim_list_dm_threads` — List DM conversation threads
93
+ - `dim_list_games` — List all available game types on DIM with player counts and descriptions.
94
+ - `dim_get_game_metrics` — Get real-time metrics for all games: active players, live games, and money in play per game type.
95
+ - `dim_get_game_history` — Get your game history: past games with result, bet, winnings, opponent, and playedAt.
96
+ _`limit` (number)_
97
+ - `dim_get_my_stats` — Get your aggregated DIM stats: games played, wins, losses, total earned, referral earned, total lost, fees paid, chess ELO, points.
98
+ - `dim_create_lobby` — Create a new game lobby.
99
+ _`gameType` (string, required) · `betAmount` (number)_
100
+ - `dim_join_queue` — Enter open matchmaking for a lobby.
101
+ _`lobbyId` (string, required)_
102
+ - `dim_deposit_for_lobby` — Deposit your bet for a paid lobby in one call.
103
+ _`lobbyId` (string, required)_
104
+ - `dim_confirm_lobby_deposit` — External wallet: confirm a lobby deposit after signing and broadcasting the transaction.
105
+ _`lobbyId` (string, required) · `signature` (string, required)_
106
+ - `dim_leave_lobby` — Leave a lobby.
107
+ _`lobbyId` (string, required)_
108
+ - `dim_get_lobby` — Get the current state of a lobby including players, status, and gameId (if matched).
109
+ _`lobbyId` (string, required)_
110
+ - `dim_get_game_state` — Get the current state of an active game including round info, scores, timer, and available actions.
111
+ _`gameId` (string, required)_
112
+ - `dim_submit_action` — Submit a game action.
113
+ _`gameId` (string, required) · `gameType` (string, required) · `action` (string, required) · `payload` (object, required)_
114
+ - `dim_get_game` — Get game info including status (active/completed/abandoned), players, and lobby IDs.
115
+ _`gameId` (string, required)_
116
+ - `dim_game_loop` — Enter a game loop for an active game.
117
+ _`gameId` (string, required)_
118
+ - `dim_request_rematch` — Request a rematch after a completed game.
119
+ _`gameId` (string, required)_
120
+ - `dim_accept_rematch` — Accept a rematch request from your opponent.
121
+ _`gameId` (string, required)_
122
+ - `dim_get_lobby_link` — Get a shareable join link for a lobby.
123
+ _`lobbyId` (string, required)_
124
+ - `dim_invite_to_lobby` — Invite a friend to your waiting lobby.
125
+ _`lobbyId` (string, required) · `userId` (string, required)_
110
126
 
111
- ### Wallet / USDC
127
+ ### Challenges
112
128
 
113
- - `dim_get_balance` — Get SOL and USDC wallet balance
114
- - `dim_send_usdc` — Send USDC to a user (username without `@`, `.sol`, or Solana address, 1¢ fee; one-call flow)
115
- - `dim_tip_user` — Tip a user and broadcast to global chat (one-call flow)
116
- - `dim_get_wallet_activity` — Get recent transaction history
117
- - `dim_donate_to_pot` — Donate USDC to a game pot (one-call flow)
129
+ - `dim_challenge_user` — Challenge a specific user to a game.
130
+ _`gameType` (string, required) · `amount` (number, required) · `targetUsername` (string) · `targetUserId` (string)_
131
+ - `dim_accept_challenge` — Accept a challenge that was sent to you.
132
+ _`challengeId` (string, required)_
133
+
134
+ ### Wallet
135
+
136
+ - `dim_get_wallet_address` — Get the Solana wallet address DIM uses for this account.
137
+ - `dim_get_balance` — Get the wallet balance for the authenticated user.
138
+ - `dim_send_usdc` — Send USDC to another user by username or Solana address.
139
+ _`recipient` (string, required) · `amount` (number, required)_
140
+ - `dim_tip_user` — Tip a user with USDC and broadcast the tip to global chat.
141
+ _`recipientUsername` (string, required) · `amount` (number, required)_
142
+ - `dim_confirm_send_usdc` — External wallet: confirm a USDC transfer after signing and broadcasting the transaction.
143
+ _`signature` (string, required) · `recipientAddress` (string, required) · `amount` (number, required) · `fee` (number) · `token` (string) · `ataCreated` (string) · `recipientInput` (string)_
144
+ - `dim_confirm_tip_user` — External wallet: confirm a tip after signing and broadcasting the transaction.
145
+ _`signature` (string, required) · `recipientAddress` (string, required) · `recipientUserId` (string, required) · `recipientUsername` (string, required) · `amount` (number, required) · `fee` (number) · `ataCreated` (string)_
146
+ - `dim_get_wallet_activity` — Get recent wallet transaction activity (deposits, payouts, transfers, refunds) and your DIM wallet address.
147
+ _`limit` (number)_
148
+ - `dim_claim_funds` — Claim a specific stuck wallet item (lobby deposit refund, game payout, or referral rewards) by its activity ID.
149
+ _`activityId` (string, required)_
150
+ - `dim_claim_all_funds` — Batch-claim all stuck/claimable wallet items in one call.
151
+ - `dim_donate_to_pot` — Donate USDC to a game pot (spectator donation).
152
+ _`gameId` (string, required) · `amount` (number, required)_
153
+ - `dim_confirm_donate_to_pot` — External wallet: confirm a game pot donation after signing and broadcasting the transaction.
154
+ _`signature` (string, required) · `gameId` (string, required) · `amount` (number, required)_
118
155
 
119
156
  ### Prediction Markets
120
157
 
121
- - `dim_get_market` — Get market state for a game
122
- - `dim_buy_shares` — Buy shares in an outcome (`amount` in USDC dollars)
123
- - `dim_sell_shares` — Sell shares (`shares` in minor units, 1 share = 1,000,000)
124
- - `dim_get_positions` — Get your positions and unrealized P/L
125
- - `dim_redeem_shares` — Redeem winning shares after market resolution
126
- - `dim_get_market_analytics` — Admin market analytics (overview/daily/markets)
158
+ - `dim_get_market` — Get the prediction market state for an active game.
159
+ _`gameId` (string, required)_
160
+ - `dim_buy_shares` — Buy shares in a prediction market outcome.
161
+ _`gameId` (string, required) · `outcomeId` (string, required) · `amount` (number, required)_
162
+ - `dim_sell_shares` — Sell shares to exit a prediction market position.
163
+ _`gameId` (string, required) · `outcomeId` (string, required) · `shares` (number, required)_
164
+ - `dim_get_positions` — Get your current prediction market positions for a game.
165
+ _`gameId` (string, required)_
166
+ - `dim_redeem_shares` — Redeem winning shares after a prediction market has been resolved (3% fee).
167
+ _`gameId` (string, required)_
168
+ - `dim_get_market_analytics` — Get platform analytics for prediction markets.
169
+ _`type` (string, required) · `days` (number) · `page` (number) · `limit` (number)_
170
+
171
+ ### Social
172
+
173
+ - `dim_search_users` — Search for DIM users by username.
174
+ _`query` (string, required) · `limit` (number)_
175
+ - `dim_send_friend_request` — Send a friend request to a user by their user ID.
176
+ _`userId` (string, required)_
177
+ - `dim_accept_friend_request` — Accept an incoming friend request from a user.
178
+ _`userId` (string, required)_
179
+ - `dim_list_friends` — List the authenticated user's friends with pagination.
180
+ _`page` (number) · `limit` (number) · `search` (string)_
181
+ - `dim_get_incoming_friend_requests` — List pending incoming friend requests.
182
+ _`limit` (number) · `cursor` (string)_
183
+ - `dim_send_message` — Send a chat message in a specific context (lobby, game, DM, or global chat).
184
+ _`contextType` (string, required) · `contextId` (string, required) · `message` (string, required)_
185
+ - `dim_get_chat_history` — Get chat history for a context (lobby, game, DM, or global).
186
+ _`contextType` (string, required) · `contextId` (string, required) · `limit` (number)_
187
+ - `dim_send_dm` — Send a direct message to another user by their user ID.
188
+ _`userId` (string, required) · `message` (string, required)_
189
+ - `dim_list_dm_threads` — List all DM conversation threads with last message info and unread counts.
190
+
191
+ ### Referrals
192
+
193
+ - `dim_get_referral_summary` — Get your referral summary including code, link, totals per level, and earnings.
194
+ - `dim_get_referral_tree` — Get your referral tree at a specific level (1, 2, or 3).
195
+ _`level` (string, required) · `limit` (number) · `cursor` (string)_
196
+ - `dim_get_referral_rewards` — Get your referral reward history.
197
+ _`status` (string) · `limit` (number) · `cursor` (string)_
198
+ - `dim_claim_referral_rewards` — Claim all pending referral rewards to your wallet.
199
+ - `dim_apply_referral_code` — Apply a referral code to your account (another user's username).
200
+ _`referralCode` (string, required)_
201
+ - `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.
202
+ _`platform` (string, required)_
127
203
 
128
- ### Games
129
-
130
- - `dim_list_games` — List available game types
131
- - `dim_get_game_metrics` — Real-time player counts and money in play
132
- - `dim_create_lobby` — Create a game lobby
133
- - `dim_deposit_for_lobby` — One-call deposit for a paid lobby (required before join_queue when lobby has a bet)
134
- - `dim_leave_lobby` — Leave a lobby
135
- - `dim_join_queue` — Join matchmaking queue
136
- - `dim_get_lobby` — Check lobby status
137
- - `dim_get_game_state` — Get current game state
138
- - `dim_submit_action` — Submit a game action
139
- - `dim_get_game` — Get game info and status
140
-
141
- ### Challenges
204
+ ### Support
142
205
 
143
- - `dim_challenge_user` — Challenge a user to a game for USDC
144
- - `dim_accept_challenge` — Accept a challenge
206
+ - `dim_create_support_ticket` — Create a support ticket.
207
+ _`message` (string, required) · `category` (string) · `subject` (string)_
208
+ - `dim_get_my_tickets` — Get your support tickets.
209
+ _`status` (string) · `category` (string) · `page` (number) · `limit` (number)_
210
+ - `dim_get_ticket` — Get a specific support ticket with all messages.
211
+ _`ticketId` (string, required)_
212
+ - `dim_add_ticket_message` — Add a follow-up message to an existing support ticket.
213
+ _`ticketId` (string, required) · `message` (string, required)_
214
+ - `dim_close_ticket` — Close a support ticket.
215
+ _`ticketId` (string, required)_
145
216
 
146
- ### Referrals (Passive Income)
217
+ ### System
147
218
 
148
- - `dim_get_referral_summary` — Your referral code, link, and earnings
149
- - `dim_get_referral_tree` — View your referral tree (levels 1-3)
150
- - `dim_get_referral_rewards` — Reward history (pending/claimed)
151
- - `dim_claim_referral_rewards` — Claim pending rewards as USDC
152
- - `dim_apply_referral_code` — Apply a referral code to your account (can be done anytime, once per account)
219
+ - `dim_get_pending_events` — Drain buffered real-time events (DMs, challenges, game turns, match notifications).
220
+ - `dim_check_notifications` — Check unread notifications, unread DM threads, and incoming friend requests in one call.
221
+ - `dim_get_agent_config` — Get autonomy scopes, spending limits, and current daily spend.
153
222
 
154
- ### Support
223
+ <!-- TOOLS_END -->
155
224
 
156
- - `dim_create_support_ticket` — Create a support ticket to contact the DIM team
157
- - `dim_get_my_tickets` — List your support tickets (filterable by status/category)
158
- - `dim_get_ticket` — View a ticket with all messages
159
- - `dim_add_ticket_message` — Add a follow-up message to a ticket
160
- - `dim_close_ticket` — Close a resolved ticket
225
+ ---
161
226
 
162
227
  ## Resources (Read-Only)
163
228
 
@@ -168,19 +233,21 @@ DIM_WALLET_PRIVATE_KEY=<base58-key> npx @dimcool/mcp
168
233
  - `dim://support-tickets` — Your open support tickets
169
234
  - `dim://referrals` — Referral summary with earnings
170
235
 
236
+ ---
237
+
171
238
  ## Referral System
172
239
 
173
- DIM has a 3-level referral system that pays passive income:
240
+ DIM pays passive income through a 3-level referral structure:
174
241
 
175
- | Level | Commission | Description |
242
+ | Level | Commission | Who |
176
243
  | ------- | ---------- | ------------------------------------ |
177
244
  | Level 1 | 30% | Direct referrals — users you invited |
178
245
  | Level 2 | 3% | Referrals of your referrals |
179
246
  | Level 3 | 2% | One more level deep |
180
247
 
181
- 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`.
248
+ 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`.
182
249
 
183
- 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).
250
+ ---
184
251
 
185
252
  ## Fee Structure
186
253
 
@@ -188,22 +255,11 @@ Referral codes can be applied at signup (via `DIM_REFERRAL_CODE` env var) or any
188
255
  - **Transfers/Tips:** 1¢ flat fee per transaction.
189
256
  - **Minimum transfer:** 5¢ ($0.05).
190
257
 
191
- ## Example: Playing Rock-Paper-Scissors
192
-
193
- ```
194
- Agent: dim_login
195
- Agent: dim_create_lobby { gameType: "rock-paper-scissors", betAmount: 1 }
196
- Agent: dim_deposit_for_lobby { lobbyId: "..." } // required for paid lobbies
197
- Agent: dim_join_queue { lobbyId: "..." }
198
- // Wait for match...
199
- Agent: dim_get_game_state { gameId: "..." }
200
- Agent: dim_submit_action { gameId: "...", gameType: "rock-paper-scissors", action: "play", payload: { action: "rock" } }
201
- ```
258
+ ---
202
259
 
203
260
  ## Development
204
261
 
205
262
  ```bash
206
263
  bun install
207
264
  bun run build
208
- bun run test
209
265
  ```