get_results

Instructions

Implementation Reference

• src/tools.ts:140-181 (handler)

  Main handler for get_results tool case in handleToolCall. Parses pollId from args, fetches poll metadata, options, and votes via client.getResults(), then groups votes by option (yes/maybe/no) and returns a JSON summary with counts and voter names per time slot.

  case "get_results": {
    const { pollId } = z.object({ pollId: z.string() }).parse(args);
    const [poll, options, votes] = await Promise.all([
      client.getPoll(pollId),
      client.getOptions(pollId),
      client.getResults(pollId),
    ]);
  
    // Group votes by option
    const grouped = new Map<string, { option: typeof options[0]; yes: string[]; maybe: string[]; no: string[] }>();
    for (const opt of options) {
      grouped.set(opt.id, { option: opt, yes: [], maybe: [], no: [] });
    }
    for (const v of votes) {
      const group = grouped.get(v.optionId);
      if (!group) continue;
      const name = v.voterName || "Anonymous";
      if (v.availability === "yes") group.yes.push(name);
      else if (v.availability === "maybe") group.maybe.push(name);
      else if (v.availability === "no") group.no.push(name);
    }
  
    const summary = Array.from(grouped.values()).map((g) => ({
      optionId: g.option.id,
      start: g.option.start,
      end: g.option.end,
      yesCount: g.yes.length,
      maybeCount: g.maybe.length,
      noCount: g.no.length,
      yesVoters: g.yes,
      maybeVoters: g.maybe,
      noVoters: g.no,
    }));
  
    return JSON.stringify({
      pollId,
      title: poll.title,
      status: poll.status,
      finalizedOptionId: poll.finalizedOptionId,
      results: summary,
    }, null, 2);
  }

• src/tools.ts:50-59 (schema)

  Tool description for get_results, documenting its purpose and expected usage pattern.

    get_results:
      "Get voting results for a Timergy poll, showing who voted yes/maybe/no for each time slot. " +
      "Use this after participants have voted to see which slot has the most availability. " +
      "To finalize, pick the optionId with the most 'yes' votes and call finalize_poll.",
  
    finalize_poll:
      "Finalize a poll by picking the winning time slot. Call get_results first to find the best optionId. " +
      "Uses the passphrase auto-saved from create_poll. If the MCP server was restarted since poll creation, provide the passphrase manually. " +
      "This locks the poll and notifies participants who provided an email.",
  };

• src/index.ts:99-113 (registration)

  Registers the get_results tool with the MCP server, defining pollId as the sole input parameter with Zod validation, and delegating execution to handleToolCall.

  server.tool(
    "get_results",
    TOOL_DESCRIPTIONS.get_results,
    {
      pollId: z.string().describe("Poll UUID"),
    },
    async (args) => {
      try {
        const text = await handleToolCall("get_results", 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/client.ts:116-119 (helper)

  HTTP client method that fetches the voting results for a poll from the Timergy API (GET /api/open/polls/{pollId}/results). Returns an array of Vote objects.

  async getResults(pollId: string): Promise<Vote[]> {
    const data = await this.request<{ votes: Vote[] }>("GET", `/api/open/polls/${pollId}/results`);
    return data.votes;
  }