@dimcool/mcp 0.1.0-beta.1

package/README.md

@@ -0,0 +1,164 @@
+# @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.
+
+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
+
+Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "dim": {
+      "command": "npx",
+      "args": ["@dimcool/mcp"],
+      "env": {
+        "DIM_WALLET_PRIVATE_KEY": "your-base58-solana-private-key",
+        "DIM_API_URL": "https://api.dim.cool"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable                 | Required | Description                                    |
+| ------------------------ | -------- | ---------------------------------------------- |
+| `DIM_WALLET_PRIVATE_KEY` | Yes      | Base58-encoded Solana private key              |
+| `DIM_API_URL`            | No       | API base URL (default: `https://api.dim.cool`) |
+| `DIM_REFERRAL_CODE`      | No       | Referral code to use on first signup           |
+
+### Wallet Auth Configuration
+
+- `@dimcool/mcp` uses `DIM_WALLET_PRIVATE_KEY` directly for wallet-based login and signing.
+- Call `dim_login` before any wallet, games, chat, social, referrals, support, or market tools.
+- To generate/export a Base58 key programmatically, use [@dimcool/wallet](https://docs.dim.cool/guides/wallet-package).
+
+## Available Tools
+
+### Authentication
+
+- `dim_login` — Authenticate with DIM using the configured wallet
+- `dim_get_profile` — Get the authenticated user's profile
+- `dim_set_username` — Set or update your username
+
+### Friends
+
+- `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
+
+### Chat
+
+- `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
+
+### Wallet / USDC
+
+- `dim_get_balance` — Get SOL and USDC wallet balance
+- `dim_send_usdc` — Send USDC to a user (username without `@`, `.sol`, or Solana address, 1¢ fee; one-call flow)
+- `dim_tip_user` — Tip a user and broadcast to global chat (one-call flow)
+- `dim_get_wallet_activity` — Get recent transaction history
+- `dim_donate_to_pot` — Donate USDC to a game pot (one-call flow)
+
+### 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_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
+
+### Challenges
+
+- `dim_challenge_user` — Challenge a user to a game for USDC
+- `dim_accept_challenge` — Accept a challenge
+
+### Referrals (Passive Income)
+
+- `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)
+
+### Support
+
+- `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)
+
+- `dim://profile` — Current user profile
+- `dim://friends` — Friends list
+- `dim://balance` — Wallet balances
+- `dim://games` — Available game types
+- `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:
+
+| Level   | Commission | Description                          |
+| ------- | ---------- | ------------------------------------ |
+| 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`.
+
+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
+
+- **Games:** 1% of bet per player (min 1¢). Referred players get 10% discount.
+- **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: 1000000 }
+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
+```