hs_pipeline_summary

Instructions

Implementation Reference

• src/tools/pipelines.ts:18-55 (handler)

  The pipelineSummary function fetches pipeline stages and deals, then aggregates deal counts and total amounts by stage. It queries stages via GET /crm/v3/pipelines/deals/{pipelineId}/stages and searches deals via POST /crm/v3/objects/deals/search filtered by pipeline ID, then groups deal count and total amount by stage, sorted by displayOrder.

  export async function pipelineSummary(args: z.infer<typeof PipelineSummarySchema>) {
    const [stages, deals] = await Promise.all([
      hubspot<{ results: Array<{ id: string; label: string; displayOrder: number; metadata: { probability: string } }> }>(
        `/crm/v3/pipelines/deals/${args.pipelineId}/stages`,
      ),
      hubspot<{ results: Array<{ properties: Record<string, string> }> }>(
        "/crm/v3/objects/deals/search", "POST", {
          filterGroups: [{ filters: [{ propertyName: "pipeline", operator: "EQ", value: args.pipelineId }] }],
          properties: ["dealstage", "amount", "hs_is_closed"],
          limit: 200,
        },
      ),
    ]);
  
    const byStage: Record<string, { label: string; count: number; totalAmount: number }> = {};
    for (const stage of stages.results) {
      byStage[stage.id] = { label: stage.label, count: 0, totalAmount: 0 };
    }
    for (const deal of deals.results) {
      const { dealstage, amount } = deal.properties;
      if (byStage[dealstage]) {
        byStage[dealstage].count++;
        byStage[dealstage].totalAmount += parseFloat(amount ?? "0") || 0;
      }
    }
  
    return {
      pipelineId: args.pipelineId,
      stages: stages.results
        .sort((a, b) => a.displayOrder - b.displayOrder)
        .map((s) => ({
          id: s.id,
          probability: s.metadata?.probability,
          ...byStage[s.id],
          label: s.label,
        })),
    };
  }

• src/tools/pipelines.ts:14-16 (schema)

  PipelineSummarySchema defines a single required input: pipelineId (string) — the pipeline ID from list_pipelines.

  export const PipelineSummarySchema = z.object({
    pipelineId: z.string().describe("Pipeline ID (from list_pipelines)"),
  });

• src/index.ts:186-191 (registration)

  Registration of the 'hs_pipeline_summary' tool on the MCP server with description, schema, and handler invocation.

  server.tool(
    "hs_pipeline_summary",
    "Deal counts and total amounts aggregated by pipeline stage — a quick funnel snapshot for a given pipeline.",
    PipelineSummarySchema.shape,
    async (args) => { try { return ok(await pipelineSummary(args)); } catch (e) { return err(e); } },
  );

• src/tools/pipelines.ts:9-12 (helper)

  A companion helper function listPipelines which fetches all pipelines (deals or tickets) to get pipeline IDs used by pipelineSummary.

  export async function listPipelines(args: z.infer<typeof ListPipelinesSchema>) {
    const type = args.objectType ?? "deals";
    return hubspot(`/crm/v3/pipelines/${type}`);
  }