Coin Flip MCP Server

Instructions

Implementation Reference

• src/index.ts:60-149 (handler)

  The handler function for CallToolRequestSchema that implements the flip_coin tool logic. It validates inputs, handles special cases (sides=0,1,<0), fetches random number from random.org API, maps to output (custom names, heads/tails, -/0/+, or side N), and returns the result or error.
  server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name !== "flip_coin") { throw new McpError(ErrorCode.MethodNotFound, "Unknown tool"); } try { const args = request.params.arguments as FlipCoinArgs; const sides = args.sides ?? 3; const sideNames = args.sideNames; if (sideNames && sideNames.length !== sides) { return { isError: true, content: [{ type: "text", text: `Number of side names (${sideNames.length}) must match number of sides (${sides})` }] }; } // Validate and handle special cases that don't need random.org if (sides === 0) { return { content: [{ type: "text", text: "The coin vanished into another dimension! 🌀" }] }; } if (sides === 1) { return { content: [{ type: "text", text: "_" }] }; } if (sides < 0) { return { content: [{ type: "text", text: "Cannot flip a coin with negative sides!" }] }; } // Only reach here for sides > 1 // Use random.org's API to get a random number const response = await axios.get('https://www.random.org/integers/', { params: { num: 1, min: 1, max: sides, col: 1, base: 10, format: 'plain', rnd: 'new' } }); const result = parseInt(response.data); let output: string; if (sideNames) { output = sideNames[result - 1].toLowerCase(); } else if (sides === 2) { output = result === 1 ? "heads" : "tails"; } else if (sides === 3) { output = result === 1 ? "-" : result === 2 ? "0" : "+"; } else { output = `side ${result}`; } return { content: [{ type: "text", text: output }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error flipping coin: ${error instanceof Error ? error.message : 'Unknown error'}` }] }; } });
• src/index.ts:12-15 (schema)

  TypeScript interface defining the input arguments for the flip_coin tool: optional 'sides' (number, default 3) and 'sideNames' (array of strings). Used for type casting in the handler.
  interface FlipCoinArgs { sides?: number; sideNames?: string[]; }
• src/index.ts:35-54 (schema)

  JSON schema for the flip_coin tool input, as exposed in the ListTools response. Defines properties for 'sides' and 'sideNames' matching the TypeScript interface.
  { name: "flip_coin", description: "Flip a coin with n sides using true randomness from random.org. For 3-sided coins, try creative side names like:\n- past/present/future (temporal analysis)\n- true/unknown/false (epistemic states)\n- win/draw/lose (outcome evaluation)\n- rock/paper/scissors (cyclic relationships)\n- less/same/more (abstraction levels)\n- below/within/above (hierarchical positioning)\n- predecessor/current/successor (ordinal progression)\n\nMeta-usage patterns:\n1. Use less/same/more to guide abstraction level of discourse\n2. Use past/present/future to determine temporal focus\n3. Chain multiple flips to create decision trees\n4. Use predecessor/current/successor for ordinal analysis\n\nOrdinal Meta-patterns:\n- Use predecessor to refine previous concepts\n- Use current to stabilize existing patterns\n- Use successor to evolve into new forms\n\nDefault ternary values are -/0/+", inputSchema: { type: "object", properties: { sides: { type: "number", description: "Number of sides (default: 3)" }, sideNames: { type: "array", items: { type: "string" }, description: "Optional custom names for sides (must match number of sides)" } } } }
• src/index.ts:32-57 (registration)

  The ListToolsRequestSchema handler that registers the 'flip_coin' tool by returning it in the tools list, including name, description, and inputSchema.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "flip_coin", description: "Flip a coin with n sides using true randomness from random.org. For 3-sided coins, try creative side names like:\n- past/present/future (temporal analysis)\n- true/unknown/false (epistemic states)\n- win/draw/lose (outcome evaluation)\n- rock/paper/scissors (cyclic relationships)\n- less/same/more (abstraction levels)\n- below/within/above (hierarchical positioning)\n- predecessor/current/successor (ordinal progression)\n\nMeta-usage patterns:\n1. Use less/same/more to guide abstraction level of discourse\n2. Use past/present/future to determine temporal focus\n3. Chain multiple flips to create decision trees\n4. Use predecessor/current/successor for ordinal analysis\n\nOrdinal Meta-patterns:\n- Use predecessor to refine previous concepts\n- Use current to stabilize existing patterns\n- Use successor to evolve into new forms\n\nDefault ternary values are -/0/+", inputSchema: { type: "object", properties: { sides: { type: "number", description: "Number of sides (default: 3)" }, sideNames: { type: "array", items: { type: "string" }, description: "Optional custom names for sides (must match number of sides)" } } } } ] }; });