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)"
              }
            }
          }
        }
      ]
    };
  });