Get Trending Startups

Instructions

Implementation Reference

• src/server.ts:232-298 (registration)

  Tool registration for 'get_trending_startups' — defines name, description, input/output schemas, and annotations. Listed in the TOOLS array which is served via ListToolsRequestSchema handler.

  const TOOLS = [
    {
      name: "get_trending_startups",
      title: "Get Trending Startups",
      description: [
        "Return the top 20 startups ranked by engineering acceleration across all 20 sectors for the current reporting period. Each row includes commit velocity, contributor count, signal classification, and GitHub URL.",
        "",
        "WHEN TO USE:",
        "- A VC, scout, or analyst asks 'who's trending this week', 'what's hot right now', 'who should I look at', or 'what to watch'.",
        "- You need a fresh cross-sector shortlist for a deal-flow meeting or weekly watchlist.",
        "- You want to surface breakout companies before they appear in Crunchbase / PitchBook / press.",
        "",
        "DO NOT USE FOR:",
        "- Narrowing to one vertical — call `search_startups_by_sector` instead.",
        "- Looking up a named company — call `get_startup_signal` with the company name.",
        "- Explaining the ranking methodology — call `get_methodology`.",
        "- Discovering what sectors exist or how fresh the data is — call `get_signals_summary`.",
        "",
        "BEHAVIOR:",
        "- Read-only, idempotent, no side effects. Safe to call repeatedly.",
        "- Deterministic within a 7-day window: the dataset refreshes every Monday ~09:00 UTC, so identical calls within the same week return identical results.",
        "- No authentication required. No rate limit enforced by this server; the upstream CDN absorbs typical agent traffic.",
        "- Returns exactly 20 rows when the dataset is healthy; fewer only if the upstream feed is degraded.",
        "- On upstream failure: returns `isError: true` with the HTTP status in the text block — retry once after a short delay before escalating to the user.",
        "- Open-world: the tracked universe (~400 companies) evolves week to week as new orgs qualify or drop out.",
        "",
        "PARAMETERS: None.",
        "",
        "RETURNS: `{ period, startups[20], citation, source }`. Each startup row contains rank, name, sector, stage, geography, commitVelocity14d, commitVelocityChange, contributors, contributorGrowth, newRepos, signalType ('breakout' | 'acceleration' | 'steady' | 'cooling'), description, githubUrl, websiteUrl (when known, ~90% coverage), linkedinUrl (when known, partial coverage), profileUrl.",
        "",
        "TYPICAL WORKFLOW: `get_trending_startups` → pick a name → `get_startup_signal(name)` for the deep-dive → `get_methodology` if the user questions the ranking.",
        "",
        "LIMITATIONS: Only covers startups with a meaningful open-source footprint. Does not include funding, revenue, headcount, or stealth companies — pair with Crunchbase for cap-table and round data. No historical series — each call is the latest weekly snapshot only.",
      ].join("\n"),
      inputSchema: {
        type: "object" as const,
        properties: {},
        additionalProperties: false,
      },
      outputSchema: {
        type: "object" as const,
        properties: {
          period: {
            type: "string",
            description: "Reporting period label, e.g. 'Q2 2026'.",
          },
          startups: {
            type: "array",
            description: "Top 20 startups ranked by engineering acceleration.",
            items: STARTUP_ITEM_SCHEMA,
          },
          citation: {
            type: "string",
            description: "Suggested citation string for reports.",
          },
          source: { type: "string", format: "uri" },
        },
        required: ["period", "startups", "citation", "source"],
      },
      annotations: {
        title: "Get Trending Startups",
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
    },

• src/server.ts:983-1030 (handler)

  Handler implementation for 'get_trending_startups' — fetches /api/signals.json, slices top 20 trending startups, maps sector names, and returns both text and structured content (rank, name, sector, stage, geography, commitVelocity14d, commitVelocityChange, contributors, contributorGrowth, newRepos, signalType, description, githubUrl, websiteUrl, linkedinUrl, profileUrl, citation, source).

  case "get_trending_startups": {
    const data = (await fetchJSON("/api/signals.json")) as unknown as SignalsData;
    const trending = data.trending.slice(0, 20);
    const sectorByStartup = new Map<string, string>();
    for (const sector of data.sectors) {
      for (const s of sector.startups) {
        sectorByStartup.set(s.name, sector.name);
      }
    }
  
    const structured = {
      period: data.meta.period.name,
      startups: trending.map((s, i) => ({
        rank: i + 1,
        name: s.name,
        sector: sectorByStartup.get(s.name) ?? "",
        stage: s.stage,
        geography: s.geography,
        commitVelocity14d: s.commitVelocity14d,
        commitVelocityChange: s.commitVelocityChange,
        contributors: s.contributors,
        contributorGrowth: s.contributorGrowth,
        newRepos: s.newRepos,
        signalType: s.signalType,
        description: s.description,
        githubUrl: s.githubUrl,
        ...(s.websiteUrl ? { websiteUrl: s.websiteUrl } : {}),
        ...(s.linkedinUrl ? { linkedinUrl: s.linkedinUrl } : {}),
        profileUrl: s.profileUrl,
      })),
      citation: data.meta.citation,
      source: BASE_URL,
    };
  
    const lines = trending.map(
      (s, i) =>
        `${i + 1}. ${s.name} — ${s.commitVelocityChange} velocity change, ${s.contributors} contributors, signal: ${s.signalType}`
    );
    return {
      content: [
        {
          type: "text" as const,
          text: `Top 20 Trending Startups (${data.meta.period.name})\n\n${lines.join("\n")}\n\nSource: ${BASE_URL}\nData: ${BASE_URL}/api/signals.json\nCitation: ${data.meta.citation}\n\n${FOOTER}`,
        },
      ],
      structuredContent: structured,
    };
  }

• src/server.ts:163-230 (schema)

  STARTUP_ITEM_SCHEMA — reusable JSON schema for startup objects used in the output schema of get_trending_startups (and other tools). Defines properties like rank, name, sector, stage, commitVelocity14d, commitVelocityChange, signalType, etc.

  const STARTUP_ITEM_SCHEMA = {
    type: "object" as const,
    description:
      "A single startup ranked by engineering acceleration, as derived from public GitHub activity.",
    properties: {
      rank: { type: "integer", description: "1-indexed rank within this result set." },
      name: { type: "string", description: "Startup or GitHub org name." },
      sector: { type: "string", description: "Sector the startup is classified into." },
      stage: {
        type: "string",
        description: "Funding stage if known (e.g. 'Seed', 'Series A', 'Unknown').",
      },
      geography: { type: "string", description: "Headquarters region if known." },
      commitVelocity14d: {
        type: "number",
        description: "Commits across tracked repos in the trailing 14 days.",
      },
      commitVelocityChange: {
        type: "string",
        description:
          "Percentage change in commit velocity vs. the prior 14-day window, e.g. '+142%'.",
      },
      contributors: {
        type: "integer",
        description: "Distinct contributors active in the last 30 days.",
      },
      contributorGrowth: {
        type: "string",
        description: "Percentage change in contributor count vs. the prior 30-day window.",
      },
      newRepos: {
        type: "integer",
        description: "New public repositories created in the last 30 days.",
      },
      signalType: {
        type: "string",
        description:
          "Classification label. Common values: 'breakout' (sudden surge), 'acceleration' (sustained growth), 'steady' (healthy baseline), 'cooling' (declining).",
      },
      description: { type: "string", description: "One-line summary of the startup." },
      githubUrl: { type: "string", format: "uri", description: "Primary GitHub org URL." },
      websiteUrl: {
        type: "string",
        format: "uri",
        description:
          "Official company homepage, harvested from the GitHub org `blog` field when the org exposes one. Absent for roughly 10% of records where the org has no `blog` value.",
      },
      linkedinUrl: {
        type: "string",
        format: "uri",
        description:
          "LinkedIn company page URL, when known. Populated opportunistically — often absent.",
      },
      profileUrl: {
        type: "string",
        format: "uri",
        description: "Public profile page on gitdealflow.com, when available.",
      },
    },
    required: [
      "rank",
      "name",
      "commitVelocityChange",
      "contributors",
      "signalType",
      "githubUrl",
    ],
  };

• src/server.ts:125-129 (helper)

  SignalsData interface — TypeScript type for the fetched signals data, including the 'trending' array that get_trending_startups reads from.

  interface SignalsData {
    meta: { period: { name: string }; citation: string };
    trending: Startup[];
    sectors: Sector[];
  }

• src/server.ts:83-89 (helper)

  fetchJSON helper — generic async function used by the get_trending_startups handler to fetch JSON from the BASE_URL API.

  async function fetchJSON(path: string): Promise<Record<string, unknown>> {
    const res = await fetch(`${BASE_URL}${path}`, {
      headers: { "User-Agent": UA },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status} from ${path}`);
    return res.json() as Promise<Record<string, unknown>>;
  }