vote_on_poll

Instructions

Implementation Reference

• src/index.ts:77-97 (registration)

  MCP server registration of the 'vote_on_poll' tool with Zod input schema (pollId, voterName, voterEmail, votes array) and a handler that delegates to handleToolCall.

  server.tool(
    "vote_on_poll",
    TOOL_DESCRIPTIONS.vote_on_poll,
    {
      pollId: z.string().describe("Poll UUID"),
      voterName: z.string().describe("Name of the voter"),
      voterEmail: z.string().optional().describe("Optional voter email for finalization notification"),
      votes: z.array(z.object({
        optionId: z.string().describe("Time slot option UUID (from get_poll)"),
        availability: z.enum(["yes", "maybe", "no"]).describe("yes = available, maybe = might work, no = unavailable"),
      })).describe("One vote per time slot"),
    },
    async (args) => {
      try {
        const text = await handleToolCall("vote_on_poll", args, client, stdioSession());
        return { content: [{ type: "text", text }] };
      } catch (e) {
        return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
      }
    },
  );

• src/tools.ts:107-138 (handler)

  Core handler for 'vote_on_poll'. Parses args with Zod, retrieves/generates a voterToken per voter name via session state, calls client.vote() via HTTP, and returns success JSON.

  case "vote_on_poll": {
    const input = z.object({
      pollId: z.string(),
      voterName: z.string(),
      voterEmail: z.string().optional(),
      votes: z.array(z.object({
        optionId: z.string(),
        availability: z.enum(["yes", "maybe", "no"]),
      })),
    }).parse(args);
  
    // Reuse or generate voterToken per voter name
    const tokenKey = `${input.pollId}:${input.voterName}`;
    let voterToken = voterTokenMap.get(tokenKey);
    if (!voterToken) {
      voterToken = randomUUID();
      voterTokenMap.set(tokenKey, voterToken);
    }
  
    await client.vote(input.pollId, {
      voterName: input.voterName,
      voterToken,
      voterEmail: input.voterEmail,
      votes: input.votes,
    });
  
    return JSON.stringify({
      success: true,
      voterName: input.voterName,
      votesSubmitted: input.votes.length,
    }, null, 2);
  }

• src/tools.ts:45-48 (helper)

  Descriptive text for the 'vote_on_poll' tool explaining usage: map optionId to yes/maybe/no, auto-generates voter token, resubmitting updates votes.

  vote_on_poll:
    "Submit votes on a Timergy poll. First call get_poll to retrieve the available optionId values. " +
    "Each vote maps an optionId to an availability: 'yes' (available), 'maybe' (might work), or 'no' (unavailable). " +
    "A unique voter token is auto-generated per voter name. Resubmitting with the same voter name updates previous votes.",

• src/index.ts:80-87 (schema)

  Zod schema for vote_on_poll input: pollId (string), voterName (string), voterEmail (optional string), votes (array of {optionId, availability: yes|maybe|no}).

  {
    pollId: z.string().describe("Poll UUID"),
    voterName: z.string().describe("Name of the voter"),
    voterEmail: z.string().optional().describe("Optional voter email for finalization notification"),
    votes: z.array(z.object({
      optionId: z.string().describe("Time slot option UUID (from get_poll)"),
      availability: z.enum(["yes", "maybe", "no"]).describe("yes = available, maybe = might work, no = unavailable"),
    })).describe("One vote per time slot"),

• src/client.ts:54-59 (schema)

  VoteInput interface used by client.vote() – defines the structure sent to the API: voterName, voterToken, voterEmail?, votes array.

  export interface VoteInput {
    voterName: string;
    voterToken: string;
    voterEmail?: string;
    votes: Array<{ optionId: string; availability: "yes" | "maybe" | "no" }>;
  }