@solworks/poll-mcp 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# poll-mcp
+
+MCP server for [Poll.fun](https://poll.fun). Gives Claude Desktop (and other MCP-compatible AI assistants) access to the Poll.fun betting platform — browse bets, place wagers, manage your account, and more.
+
+## Setup
+
+### 1. Build
+
+```bash
+cd poll-mcp && npm install && npm run build
+```
+
+### 2. Create a token
+
+Use the CLI or web UI to create a Personal Access Token:
+
+```bash
+poll auth token create --name "claude-desktop" --scopes read,bet:write,social:write --expires 90d
+```
+
+### 3. Configure Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "poll-fun": {
+      "command": "node",
+      "args": ["/absolute/path/to/poll-mcp/dist/index.js"],
+      "env": {
+        "POLL_API_TOKEN": "polld_your_token_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see "poll-fun" in the MCP server list.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `POLL_API_TOKEN` | *(required)* | Personal Access Token |
+| `POLL_API_URL` | `https://api.poll.fun` | API endpoint override |
+
+## Tools (27)
+
+### Read (`read` scope)
+
+| Tool | Description |
+|---|---|
+| `get_account` | Your account info |
+| `get_profile` | User profile by UUID (or your own) |
+| `get_balance` | XP and USDC balances |
+| `list_public_bets` | Public bets with pagination |
+| `get_trending_bets` | Currently trending bets |
+| `get_bet` | Bet details by ID or address |
+| `get_my_wagers` | Your wagers (optionally active only) |
+| `get_leaderboard` | Platform leaderboard |
+| `get_my_ranking` | Your leaderboard ranking |
+| `get_wallet_transactions` | Wallet transaction history |
+| `get_friends` | Friends list |
+| `get_notifications` | Notifications with pagination |
+| `get_streak` | Current and longest betting streak |
+| `get_favourite_bets` | Your favourite bets |
+| `get_probability_history` | Probability history for a bet |
+
+### Bet Write (`bet:write` scope)
+
+| Tool | Description |
+|---|---|
+| `create_bet` | Create a bet with question and options |
+| `join_bet` | Join an existing bet |
+| `place_wager` | Place a wager on a bet option |
+| `cancel_wager` | Cancel a placed wager |
+| `initiate_vote` | Start the voting phase |
+| `vote` | Cast a vote on a bet outcome |
+| `settle_bet` | Settle a bet and distribute winnings |
+
+### User Write (`user:write` scope)
+
+| Tool | Description |
+|---|---|
+| `update_display_name` | Change your display name |
+
+### Social Write (`social:write` scope)
+
+| Tool | Description |
+|---|---|
+| `send_friend_request` | Send a friend request |
+| `respond_friend_request` | Accept or decline a friend request |
+| `favourite_bet` | Add a bet to favourites |
+| `unfavourite_bet` | Remove a bet from favourites |
+
+## Resources (5)
+
+| URI | Description |
+|---|---|
+| `poll://user/profile` | Current user profile |
+| `poll://user/balances` | XP and USDC balances |
+| `poll://bets/active` | Your active bets and wagers |
+| `poll://bets/trending` | Currently trending bets |
+| `poll://leaderboard/top10` | Top 10 leaderboard |
+
+## Prompts (3)
+
+| Prompt | Description |
+|---|---|
+| `analyze_bet` | Analyze a specific bet's dynamics and outcomes |
+| `suggest_bets` | Suggest bets from trending, considering your balance |
+| `portfolio_review` | Review your betting portfolio with insights |
+
+## Security
+
+- `wallet:sensitive` scope is never available via PAT — private key endpoints always return 403
+- PATs cannot create other PATs (escalation prevention)
+- Scopes are enforced server-side per-endpoint; a token with only `read` scope cannot place wagers
+- HTTPS enforced for all non-localhost API URLs
+- If the token is invalid or expired, tools return clear error messages (the server stays running)

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { PollClient } from 'poll-api-client';
+export interface McpServerConfig {
+    apiToken: string;
+    apiUrl: string;
+}
+export declare function createServer(config?: McpServerConfig, clientOverride?: PollClient): McpServer;

package/dist/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { PollClient } from 'poll-api-client';
+import { TOOL_DEFINITIONS } from './tools/index.js';
+import { RESOURCE_DEFINITIONS } from './resources/index.js';
+import { PROMPT_DEFINITIONS } from './prompts/index.js';
+/**
+ * Convert a JSON Schema property type to a Zod schema.
+ */
+function jsonPropToZod(prop) {
+    const desc = prop.description ?? '';
+    switch (prop.type) {
+        case 'number':
+            return z.number().describe(desc);
+        case 'boolean':
+            return z.boolean().describe(desc);
+        case 'array':
+            return z.array(z.string()).describe(desc);
+        default:
+            return z.string().describe(desc);
+    }
+}
+export function createServer(config, clientOverride) {
+    const server = new McpServer({ name: 'poll-fun', version: '0.1.0' }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+    const client = clientOverride ??
+        new PollClient({
+            apiUrl: config?.apiUrl ?? 'https://api.poll.fun',
+            token: config?.apiToken ?? '',
+            clientId: 'poll-mcp',
+        });
+    // Register tools
+    for (const tool of Object.values(TOOL_DEFINITIONS)) {
+        const jsonProps = (tool.inputSchema.properties ?? {});
+        const requiredFields = (tool.inputSchema.required ?? []);
+        const hasParams = Object.keys(jsonProps).length > 0;
+        if (hasParams) {
+            const shape = {};
+            for (const [key, prop] of Object.entries(jsonProps)) {
+                let zodType = jsonPropToZod(prop);
+                if (!requiredFields.includes(key)) {
+                    zodType = zodType.optional();
+                }
+                shape[key] = zodType;
+            }
+            // Use the deprecated tool() API which is simpler and avoids deep type recursion
+            server.tool(tool.name, tool.description, shape, async (args) => {
+                return tool.handler(args, client);
+            });
+        }
+        else {
+            server.tool(tool.name, tool.description, async () => {
+                return tool.handler({}, client);
+            });
+        }
+    }
+    // Register resources
+    for (const resource of RESOURCE_DEFINITIONS) {
+        server.resource(resource.name, resource.uri, { description: resource.description, mimeType: resource.mimeType }, async (uri) => {
+            const text = await resource.handler(client);
+            return { contents: [{ uri: uri.href, text, mimeType: resource.mimeType }] };
+        });
+    }
+    // Register prompts
+    for (const prompt of PROMPT_DEFINITIONS) {
+        if (prompt.arguments && prompt.arguments.length > 0) {
+            const argsSchema = {};
+            for (const arg of prompt.arguments) {
+                let zodType = z.string().describe(arg.description);
+                if (!arg.required) {
+                    zodType = zodType.optional();
+                }
+                argsSchema[arg.name] = zodType;
+            }
+            server.prompt(prompt.name, prompt.description, argsSchema, async (args) => {
+                return prompt.handler(args);
+            });
+        }
+        else {
+            server.prompt(prompt.name, prompt.description, async () => {
+                return prompt.handler({});
+            });
+        }
+    }
+    return server;
+}
+async function main() {
+    const config = {
+        apiToken: process.env.POLL_API_TOKEN || '',
+        apiUrl: process.env.POLL_API_URL || 'https://api.poll.fun',
+    };
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/prompts/index.d.ts

@@ -0,0 +1,19 @@
+export interface PromptDefinition {
+    name: string;
+    description: string;
+    arguments?: Array<{
+        name: string;
+        description: string;
+        required: boolean;
+    }>;
+    handler: (args: Record<string, string>) => {
+        messages: Array<{
+            role: 'user' | 'assistant';
+            content: {
+                type: 'text';
+                text: string;
+            };
+        }>;
+    };
+}
+export declare const PROMPT_DEFINITIONS: PromptDefinition[];

package/dist/prompts/index.js

@@ -0,0 +1,100 @@
+export const PROMPT_DEFINITIONS = [
+    {
+        name: 'analyze_bet',
+        description: 'Analyze a specific bet to understand its dynamics, options, and potential outcomes',
+        arguments: [
+            {
+                name: 'betAddress',
+                description: 'The bet address or ID to analyze',
+                required: true,
+            },
+        ],
+        handler(args) {
+            const betAddress = args.betAddress ?? '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: [
+                                `Please analyze the bet with address "${betAddress}".`,
+                                '',
+                                'Use the get_bet tool to fetch the bet details, and get_probability_history to see how odds have changed.',
+                                '',
+                                'In your analysis, please cover:',
+                                '1. What the bet is about and its current status',
+                                '2. The available options and their implied probabilities',
+                                '3. The total volume and level of participation',
+                                '4. How the probabilities have trended over time',
+                                '5. Any notable patterns or insights',
+                                '6. A recommendation on whether this bet presents good value',
+                            ].join('\n'),
+                        },
+                    },
+                ],
+            };
+        },
+    },
+    {
+        name: 'suggest_bets',
+        description: 'Suggest interesting bets from the currently trending bets',
+        arguments: [],
+        handler() {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: [
+                                'Please suggest some interesting bets I could participate in.',
+                                '',
+                                'Use the get_trending_bets tool to see what is currently popular, and also check my balance with get_balance.',
+                                '',
+                                'For each suggestion, please explain:',
+                                '1. What the bet is about',
+                                '2. Why it is interesting or has good value',
+                                '3. Which option you would lean towards and why',
+                                '4. A suggested wager amount based on my balance',
+                            ].join('\n'),
+                        },
+                    },
+                ],
+            };
+        },
+    },
+    {
+        name: 'portfolio_review',
+        description: 'Review your current betting portfolio and provide insights',
+        arguments: [],
+        handler() {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: [
+                                'Please review my betting portfolio.',
+                                '',
+                                'Use these tools to gather my information:',
+                                '- get_balance for my current balances',
+                                '- get_my_wagers for my active and past wagers',
+                                '- get_my_ranking for my leaderboard position',
+                                '- get_streak for my betting streak',
+                                '',
+                                'Please provide:',
+                                '1. A summary of my current positions and exposure',
+                                '2. My win/loss performance',
+                                '3. My leaderboard standing and streak',
+                                '4. Suggestions for improving my betting strategy',
+                                '5. Any risks I should be aware of',
+                            ].join('\n'),
+                        },
+                    },
+                ],
+            };
+        },
+    },
+];

package/dist/resources/index.d.ts

@@ -0,0 +1,9 @@
+import type { PollClient } from 'poll-api-client';
+export interface ResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    handler: (client: PollClient) => Promise<string>;
+}
+export declare const RESOURCE_DEFINITIONS: ResourceDefinition[];

package/dist/resources/index.js

@@ -0,0 +1,83 @@
+export const RESOURCE_DEFINITIONS = [
+    {
+        uri: 'poll://user/profile',
+        name: 'User Profile',
+        description: 'Current user profile information',
+        mimeType: 'text/plain',
+        async handler(client) {
+            const profile = await client.getProfile();
+            const lines = [
+                `User Profile:`,
+                `  Display Name: ${profile.displayName ?? 'Not set'}`,
+                `  UUID: ${profile.uuid}`,
+            ];
+            return lines.join('\n');
+        },
+    },
+    {
+        uri: 'poll://user/balances',
+        name: 'User Balances',
+        description: 'Current XP and USDC balances',
+        mimeType: 'text/plain',
+        async handler(client) {
+            const [xp, usdc] = await Promise.all([
+                client.getXpBalance(),
+                client.getUsdcBalance(),
+            ]);
+            const lines = [
+                `Balances:`,
+                `  XP: ${xp.xp}`,
+                `  USDC: ${usdc.usdc ?? 'N/A'}`,
+            ];
+            return lines.join('\n');
+        },
+    },
+    {
+        uri: 'poll://bets/active',
+        name: 'Active Bets',
+        description: 'Your active bets and wagers',
+        mimeType: 'text/plain',
+        async handler(client) {
+            const [bets, wagers] = await Promise.all([
+                client.getMyBets(),
+                client.getMyWagers(),
+            ]);
+            const betLines = bets.map((b, i) => `  ${i + 1}. ${b.question} — Status: ${b.status}`);
+            const wagerLines = wagers.map((w, i) => `  ${i + 1}. Bet: ${w.betAddress} — Amount: ${w.amount}, Status: ${w.status}`);
+            return [
+                `Your Bets (${bets.length}):`,
+                ...(betLines.length > 0 ? betLines : ['  None']),
+                '',
+                `Your Wagers (${wagers.length}):`,
+                ...(wagerLines.length > 0 ? wagerLines : ['  None']),
+            ].join('\n');
+        },
+    },
+    {
+        uri: 'poll://bets/trending',
+        name: 'Trending Bets',
+        description: 'Currently trending bets on the platform',
+        mimeType: 'text/plain',
+        async handler(client) {
+            const bets = await client.getTrendingBets();
+            if (bets.length === 0)
+                return 'No trending bets found.';
+            const lines = bets.map((b, i) => `${i + 1}. ${b.question} — Volume: ${b.totalVolume ?? 'N/A'}`);
+            return `Trending Bets:\n${lines.join('\n')}`;
+        },
+    },
+    {
+        uri: 'poll://leaderboard/top10',
+        name: 'Leaderboard Top 10',
+        description: 'Top 10 users on the leaderboard',
+        mimeType: 'text/plain',
+        async handler(client) {
+            const entries = await client.getLeaderboard();
+            const top10 = entries.slice(0, 10);
+            if (top10.length === 0)
+                return 'Leaderboard is empty.';
+            const lines = top10.map((e) => `#${e.rank} ${e.displayName ?? 'Anonymous'} — ${e.points} pts`);
+            return `Leaderboard (Top 10):\n${lines.join('\n')}`;
+        },
+    },
+];

package/dist/tools/index.d.ts

@@ -0,0 +1,15 @@
+import type { PollClient } from 'poll-api-client';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    requiredScope: string;
+    handler: (args: Record<string, unknown>, client: PollClient) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
+export declare const TOOL_DEFINITIONS: Record<string, ToolDefinition>;