github_api_insights_get_subject_stats

Instructions

Implementation Reference

• src/tools/orgs.ts:386-401 (handler)

  The tool definition for 'github_api_insights_get_subject_stats' with schema and handler. The handler makes a GET request to `/orgs/${args.org}/insights/api/subject-stats` with query parameters for min_timestamp, max_timestamp, page, per_page, direction, sort, and subject_name_substring.

    name: "github_api_insights_get_subject_stats",
    description: "Get subject stats",
    inputSchema: z.object({
      org: z.string().describe("org"),
      min_timestamp: z.string().describe("The minimum timestamp to query for stats. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`."),
      max_timestamp: z.string().optional().describe("The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`."),
      page: z.number().optional().describe("The page number of the results to fetch. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\""),
      per_page: z.number().optional().describe("The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\""),
      direction: z.enum(["asc", "desc"]).optional().describe("The direction to sort the results by."),
      sort: z.array(z.enum(["last_rate_limited_timestamp", "last_request_timestamp", "rate_limited_request_count", "subject_name", "total_request_count"])).optional().describe("The property to sort the results by."),
      subject_name_substring: z.string().optional().describe("Providing a substring will filter results where the subject name contains the substring. This is a case-insensitive search.")
    }),
    handler: async (args: Record<string, any>) => {
      return githubRequest("GET", `/orgs/${args.org}/insights/api/subject-stats`, undefined, { min_timestamp: args.min_timestamp, max_timestamp: args.max_timestamp, page: args.page, per_page: args.per_page, direction: args.direction, sort: args.sort, subject_name_substring: args.subject_name_substring });
    },
  },

• src/index.ts:87-100 (registration)

  The orgsTools module is imported and registered in the MCP server. The tool array (orgsTools) is included in allToolModules under the 'orgs' category, and each tool is registered via server.tool() in the registration loop.

    { category: "orgs", tools: orgsTools },
    { category: "packages", tools: packagesTools },
    { category: "private-registries", tools: privateRegistriesTools },
    { category: "projects", tools: projectsTools },
    { category: "pulls", tools: pullsTools },
    { category: "rate-limit", tools: rateLimitTools },
    { category: "reactions", tools: reactionsTools },
    { category: "repos", tools: reposTools },
    { category: "search", tools: searchTools },
    { category: "secret-scanning", tools: secretScanningTools },
    { category: "security-advisories", tools: securityAdvisoriesTools },
    { category: "teams", tools: teamsTools },
    { category: "users", tools: usersTools },
  ];

• src/client.ts:9-59 (helper)

  The githubRequest helper function used by the handler to make HTTP requests to the GitHub API.

  export async function githubRequest<T>(
    method: string,
    path: string,
    body?: Record<string, unknown>,
    params?: Record<string, string | number | boolean | string[] | undefined>
  ): Promise<T> {
    const url = new URL(`${BASE_URL}${path}`);
  
    if (params) {
      for (const [key, value] of Object.entries(params)) {
        if (value === undefined || value === null || value === "") continue;
        if (Array.isArray(value)) {
          url.searchParams.set(key, value.join(","));
        } else {
          url.searchParams.set(key, String(value));
        }
      }
    }
  
    const headers: Record<string, string> = {
      Authorization: `Bearer ${getToken()}`,
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      "User-Agent": "github-mcp/1.0.0",
    };
  
    if (body) {
      headers["Content-Type"] = "application/json";
    }
  
    const res = await fetch(url.toString(), {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });
  
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      let detail = text;
      try {
        const json = JSON.parse(text);
        detail = json.message || text;
        if (json.errors) detail += ` -- ${JSON.stringify(json.errors)}`;
      } catch {}
      throw new Error(`GitHub API error ${res.status}: ${detail}`);
    }
  
    if (res.status === 204) return {} as T;
  
    return res.json() as Promise<T>;
  }