mcp-researchpowerpack-http 3.10.0

package/README.md

@@ -0,0 +1,124 @@
+# mcp-researchpowerpack
+
+http mcp server for research. web search, reddit mining, scraping, deep research — all over `/mcp`.
+
+built on [mcp-use](https://github.com/nicepkg/mcp-use). no stdio, http only.
+
+## tools
+
+| tool | what it does | needs |
+|------|-------------|-------|
+| `web-search` | parallel google search across 3–100 keywords, ctr-weighted url ranking | `SERPER_API_KEY` |
+| `search-reddit` | reddit-focused search, 3–50 diverse queries | `SERPER_API_KEY` |
+| `get-reddit-post` | fetch reddit posts + full comment trees, 2–50 urls | `REDDIT_CLIENT_ID` + `REDDIT_CLIENT_SECRET` |
+| `scrape-links` | scrape 1–50 urls with optional ai extraction | `SCRAPEDO_API_KEY` |
+| `deep-research` | multi-question research with optional file attachments | `OPENROUTER_API_KEY` |
+
+also exposes `/health` and `health://status` mcp resource.
+
+## quickstart
+
+```bash
+# from npm
+HOST=127.0.0.1 PORT=3000 npx -y mcp-researchpowerpack-http
+
+# from source
+git clone https://github.com/yigitkonur/mcp-researchpowerpack-http.git
+cd mcp-researchpowerpack-http
+pnpm install && pnpm dev
+```
+
+connect your client to `http://localhost:3000/mcp`:
+
+```json
+{
+  "mcpServers": {
+    "research-powerpack": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+## config
+
+copy `.env.example`, set only what you need. missing keys don't crash — they disable the tool with a clear error.
+
+### server
+
+| var | default | |
+|-----|---------|---|
+| `PORT` | `3000` | http port |
+| `HOST` | `127.0.0.1` | bind address |
+| `ALLOWED_ORIGINS` | unset | comma-separated origins for host validation |
+| `REDIS_URL` | unset | redis-backed sessions + distributed sse |
+
+### providers
+
+| var | enables |
+|-----|---------|
+| `SERPER_API_KEY` | web-search, search-reddit |
+| `REDDIT_CLIENT_ID` + `REDDIT_CLIENT_SECRET` | get-reddit-post |
+| `SCRAPEDO_API_KEY` | scrape-links |
+| `OPENROUTER_API_KEY` | deep-research, ai extraction |
+
+optional tuning: `RESEARCH_MODEL`, `RESEARCH_FALLBACK_MODEL`, `LLM_EXTRACTION_MODEL`, `DEFAULT_REASONING_EFFORT`, `API_TIMEOUT_MS`.
+
+## dev
+
+```bash
+pnpm install
+pnpm dev          # watch mode, serves :3000/mcp
+pnpm typecheck    # tsc --noEmit
+pnpm test         # http integration test
+pnpm build        # compile to dist/
+pnpm inspect      # mcp-use inspector
+```
+
+## deploy
+
+```bash
+pnpm build
+pnpm deploy       # manufact cloud
+```
+
+or self-host anywhere with node 20.19+ / 22.12+:
+
+```bash
+HOST=0.0.0.0 ALLOWED_ORIGINS=https://app.example.com pnpm start
+```
+
+## architecture
+
+```
+index.ts                 server startup, cors, health, shutdown
+src/
+  config/                env parsing, capability detection, lazy proxy config
+  clients/               provider api clients (serper, reddit, scrapedo, openrouter)
+  tools/
+    registry.ts          registerAllTools() — wires tools to mcp server
+    search.ts            web-search handler
+    reddit.ts            search-reddit + get-reddit-post
+    scrape.ts            scrape-links handler
+    research.ts          deep-research handler
+    mcp-helpers.ts       response builders (markdown, error, toolFailure)
+    utils.ts             shared formatters, token budget allocation
+  services/
+    llm-processor.ts     ai extraction/synthesis via openrouter
+    file-attachment.ts   local file reads for deep-research context
+    markdown-cleaner.ts  html/markdown cleanup
+  schemas/               zod v4 input validation per tool
+  utils/
+    errors.ts            structured error codes (retryable classification)
+    concurrency.ts       pMap/pMapSettled — bounded parallel execution
+    retry.ts             exponential backoff with jitter
+    url-aggregator.ts    ctr-weighted url ranking for search consensus
+    response.ts          formatSuccess/formatError/formatBatchHeader
+    logger.ts            mcpLog() — stderr-only (mcp-safe)
+```
+
+key patterns: capability detection at startup, lazy config via proxy, bounded concurrency (scraper:30, reddit:10, research:3), 32k token budgets, ctr-based url ranking, tools never throw (always return toolFailure), structured errors with retry classification.
+
+## license
+
+mit

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import { Logger } from "mcp-use";
+import {
+  InMemorySessionStore,
+  InMemoryStreamManager,
+  MCPServer,
+  RedisSessionStore,
+  RedisStreamManager,
+  object
+} from "mcp-use/server";
+import { createClient } from "redis";
+import { SERVER } from "./src/config/index.js";
+import { registerAllTools } from "./src/tools/registry.js";
+const DEFAULT_PORT = 3e3;
+const SHUTDOWN_TIMEOUT_MS = 1e4;
+const WEBSITE_URL = "https://github.com/yigitkonur/mcp-researchpowerpack-http";
+const LOCAL_DEFAULT_HOST = "127.0.0.1";
+const startupLogger = Logger.get("startup");
+function parseCsvEnv(value) {
+  if (!value) return void 0;
+  const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : void 0;
+}
+function parsePort(value, fallback) {
+  const parsed = Number.parseInt(value ?? "", 10);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+function resolvePort() {
+  const portFlagIndex = process.argv.findIndex((arg) => arg === "--port");
+  if (portFlagIndex >= 0) {
+    return parsePort(process.argv[portFlagIndex + 1], DEFAULT_PORT);
+  }
+  return parsePort(process.env.PORT, DEFAULT_PORT);
+}
+function resolveHost() {
+  const explicitHost = process.env.HOST?.trim();
+  if (explicitHost) {
+    return explicitHost;
+  }
+  if (process.env.PORT?.trim()) {
+    return "0.0.0.0";
+  }
+  return LOCAL_DEFAULT_HOST;
+}
+function buildCors(allowedOrigins) {
+  if (!allowedOrigins || allowedOrigins.length === 0) {
+    return void 0;
+  }
+  return {
+    origin: allowedOrigins,
+    allowMethods: ["GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS"],
+    allowHeaders: [
+      "Content-Type",
+      "Accept",
+      "Authorization",
+      "mcp-protocol-version",
+      "mcp-session-id",
+      "X-Proxy-Token",
+      "X-Target-URL"
+    ],
+    exposeHeaders: ["mcp-session-id"]
+  };
+}
+function configureLogging() {
+  Logger.configure({
+    level: process.env.NODE_ENV === "production" ? "info" : "debug",
+    format: "minimal"
+  });
+  const debug = process.env.DEBUG?.trim();
+  if (debug === "2") {
+    Logger.setDebug(2);
+  } else if (debug) {
+    Logger.setDebug(1);
+  }
+}
+function normalizeOrigin(value, envName) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    throw new Error(`${envName} must contain absolute URLs with protocol. Received: ${value}`);
+  }
+}
+function resolveAllowedOrigins() {
+  const explicitOrigins = parseCsvEnv(process.env.ALLOWED_ORIGINS);
+  if (explicitOrigins && explicitOrigins.length > 0) {
+    return explicitOrigins.map((origin) => normalizeOrigin(origin, "ALLOWED_ORIGINS"));
+  }
+  return void 0;
+}
+async function buildSessionConfig() {
+  const redisUrl = process.env.REDIS_URL?.trim();
+  if (!redisUrl) {
+    return {
+      sessionConfig: {
+        sessionStore: new InMemorySessionStore(),
+        streamManager: new InMemoryStreamManager()
+      },
+      cleanupFns: []
+    };
+  }
+  const commandClient = createClient({ url: redisUrl });
+  const pubSubClient = commandClient.duplicate();
+  await Promise.all([commandClient.connect(), pubSubClient.connect()]);
+  return {
+    sessionConfig: {
+      sessionStore: new RedisSessionStore({
+        client: commandClient
+      }),
+      streamManager: new RedisStreamManager({
+        client: commandClient,
+        pubSubClient
+      })
+    },
+    cleanupFns: [
+      async () => {
+        await pubSubClient.quit();
+      },
+      async () => {
+        await commandClient.quit();
+      }
+    ]
+  };
+}
+function buildHealthPayload(server, startedAt) {
+  return {
+    status: "ok",
+    name: SERVER.NAME,
+    version: SERVER.VERSION,
+    transport: "http",
+    uptime_seconds: Math.floor((Date.now() - startedAt) / 1e3),
+    active_sessions: server.getActiveSessions().length,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function main() {
+  configureLogging();
+  const isProduction = process.env.NODE_ENV === "production";
+  const host = resolveHost();
+  const port = resolvePort();
+  const baseUrl = process.env.MCP_URL?.trim() || void 0;
+  const allowedOrigins = resolveAllowedOrigins();
+  const { sessionConfig, cleanupFns } = await buildSessionConfig();
+  startupLogger.info(`Starting ${SERVER.NAME} v${SERVER.VERSION}`);
+  startupLogger.info(`Binding HTTP server to ${host}:${port}`);
+  if (allowedOrigins && allowedOrigins.length > 0) {
+    startupLogger.info(`Host validation enabled for origins: ${allowedOrigins.join(", ")}`);
+  } else if (isProduction) {
+    startupLogger.warn(
+      "Host validation is disabled because ALLOWED_ORIGINS is not set. Set ALLOWED_ORIGINS to the public deployment URL or custom domain after the first deploy."
+    );
+  } else {
+    startupLogger.info("Host validation disabled for local development");
+  }
+  const server = new MCPServer({
+    name: SERVER.NAME,
+    title: "Research Powerpack",
+    version: SERVER.VERSION,
+    description: SERVER.DESCRIPTION,
+    websiteUrl: WEBSITE_URL,
+    host,
+    baseUrl,
+    cors: buildCors(allowedOrigins),
+    allowedOrigins,
+    ...sessionConfig
+  });
+  registerAllTools(server);
+  const startedAt = Date.now();
+  server.get("/health", (c) => c.json(buildHealthPayload(server, startedAt)));
+  server.get("/healthz", (c) => c.json(buildHealthPayload(server, startedAt)));
+  server.resource(
+    {
+      name: "server-health",
+      uri: "health://status",
+      description: "Current server health, uptime, and active MCP session count.",
+      mimeType: "application/json"
+    },
+    async () => object(buildHealthPayload(server, startedAt))
+  );
+  let isShuttingDown = false;
+  async function shutdown(signal, exitCode) {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+    const forceExit = setTimeout(() => {
+      startupLogger.error(`Forced exit after ${SHUTDOWN_TIMEOUT_MS}ms (${signal})`);
+      process.exit(1);
+    }, SHUTDOWN_TIMEOUT_MS);
+    try {
+      startupLogger.warn(`Shutdown signal received: ${signal}`);
+      await server.close();
+      for (const cleanupFn of cleanupFns) {
+        await cleanupFn();
+      }
+      clearTimeout(forceExit);
+      process.exit(exitCode);
+    } catch (error) {
+      clearTimeout(forceExit);
+      const message = error instanceof Error ? error.stack ?? error.message : String(error);
+      startupLogger.error(`Error while stopping server: ${message}`);
+      process.exit(1);
+    }
+  }
+  process.on("SIGTERM", () => {
+    void shutdown("SIGTERM", 0);
+  });
+  process.on("SIGINT", () => {
+    void shutdown("SIGINT", 0);
+  });
+  process.on("uncaughtException", (error) => {
+    startupLogger.error(`Uncaught exception: ${error.stack ?? error.message}`);
+    void shutdown("uncaughtException", 1);
+  });
+  process.on("unhandledRejection", (reason) => {
+    startupLogger.error(`Unhandled rejection: ${String(reason)}`);
+    void shutdown("unhandledRejection", 1);
+  });
+  await server.listen(port);
+  startupLogger.info(`${SERVER.NAME} v${SERVER.VERSION} listening on http://${host}:${port}/mcp`);
+}
+void main().catch((error) => {
+  const message = error instanceof Error ? error.stack ?? error.message : String(error);
+  startupLogger.error(`Server failed to start: ${message}`);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../index.ts"],
+  "sourcesContent": ["#!/usr/bin/env node\n\nimport { Logger } from 'mcp-use';\nimport {\n  InMemorySessionStore,\n  InMemoryStreamManager,\n  MCPServer,\n  RedisSessionStore,\n  RedisStreamManager,\n  object,\n  type ServerConfig,\n} from 'mcp-use/server';\nimport { createClient, type RedisClientType } from 'redis';\n\nimport { SERVER } from './src/config/index.js';\nimport { registerAllTools } from './src/tools/registry.js';\n\nconst DEFAULT_PORT = 3000 as const;\nconst SHUTDOWN_TIMEOUT_MS = 10_000 as const;\nconst WEBSITE_URL = 'https://github.com/yigitkonur/mcp-researchpowerpack-http' as const;\nconst LOCAL_DEFAULT_HOST = '127.0.0.1' as const;\n\ntype CleanupFn = () => Promise<void>;\n\nconst startupLogger = Logger.get('startup');\n\nfunction parseCsvEnv(value: string | undefined): string[] | undefined {\n  if (!value) return undefined;\n\n  const parts = value\n    .split(',')\n    .map((part) => part.trim())\n    .filter(Boolean);\n\n  return parts.length > 0 ? parts : undefined;\n}\n\nfunction parsePort(value: string | undefined, fallback: number): number {\n  const parsed = Number.parseInt(value ?? '', 10);\n  if (Number.isFinite(parsed) && parsed > 0) {\n    return parsed;\n  }\n\n  return fallback;\n}\n\nfunction resolvePort(): number {\n  const portFlagIndex = process.argv.findIndex((arg) => arg === '--port');\n  if (portFlagIndex >= 0) {\n    return parsePort(process.argv[portFlagIndex + 1], DEFAULT_PORT);\n  }\n\n  return parsePort(process.env.PORT, DEFAULT_PORT);\n}\n\nfunction resolveHost(): string {\n  const explicitHost = process.env.HOST?.trim();\n  if (explicitHost) {\n    return explicitHost;\n  }\n\n  // Cloud runtimes typically inject PORT and expect the process to listen on all interfaces.\n  if (process.env.PORT?.trim()) {\n    return '0.0.0.0';\n  }\n\n  return LOCAL_DEFAULT_HOST;\n}\n\nfunction buildCors(allowedOrigins: string[] | undefined): ServerConfig['cors'] {\n  if (!allowedOrigins || allowedOrigins.length === 0) {\n    return undefined;\n  }\n\n  return {\n    origin: allowedOrigins,\n    allowMethods: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS'],\n    allowHeaders: [\n      'Content-Type',\n      'Accept',\n      'Authorization',\n      'mcp-protocol-version',\n      'mcp-session-id',\n      'X-Proxy-Token',\n      'X-Target-URL',\n    ],\n    exposeHeaders: ['mcp-session-id'],\n  };\n}\n\nfunction configureLogging(): void {\n  Logger.configure({\n    level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',\n    format: 'minimal',\n  });\n\n  const debug = process.env.DEBUG?.trim();\n  if (debug === '2') {\n    Logger.setDebug(2);\n  } else if (debug) {\n    Logger.setDebug(1);\n  }\n}\n\nfunction normalizeOrigin(value: string, envName: string): string {\n  try {\n    return new URL(value).origin;\n  } catch {\n    throw new Error(`${envName} must contain absolute URLs with protocol. Received: ${value}`);\n  }\n}\n\nfunction resolveAllowedOrigins(): string[] | undefined {\n  const explicitOrigins = parseCsvEnv(process.env.ALLOWED_ORIGINS);\n  if (explicitOrigins && explicitOrigins.length > 0) {\n    return explicitOrigins.map(origin => normalizeOrigin(origin, 'ALLOWED_ORIGINS'));\n  }\n\n  return undefined;\n}\n\nasync function buildSessionConfig(): Promise<{\n  sessionConfig: Pick<ServerConfig, 'sessionStore' | 'streamManager'>;\n  cleanupFns: CleanupFn[];\n}> {\n  const redisUrl = process.env.REDIS_URL?.trim();\n\n  if (!redisUrl) {\n    return {\n      sessionConfig: {\n        sessionStore: new InMemorySessionStore(),\n        streamManager: new InMemoryStreamManager(),\n      },\n      cleanupFns: [],\n    };\n  }\n\n  const commandClient = createClient({ url: redisUrl });\n  const pubSubClient = commandClient.duplicate();\n\n  await Promise.all([commandClient.connect(), pubSubClient.connect()]);\n\n  return {\n    sessionConfig: {\n      sessionStore: new RedisSessionStore({\n        client: commandClient as RedisClientType,\n      }),\n      streamManager: new RedisStreamManager({\n        client: commandClient as RedisClientType,\n        pubSubClient: pubSubClient as RedisClientType,\n      }),\n    },\n    cleanupFns: [\n      async () => {\n        await pubSubClient.quit();\n      },\n      async () => {\n        await commandClient.quit();\n      },\n    ],\n  };\n}\n\nfunction buildHealthPayload(server: MCPServer, startedAt: number) {\n  return {\n    status: 'ok',\n    name: SERVER.NAME,\n    version: SERVER.VERSION,\n    transport: 'http',\n    uptime_seconds: Math.floor((Date.now() - startedAt) / 1000),\n    active_sessions: server.getActiveSessions().length,\n    timestamp: new Date().toISOString(),\n  };\n}\n\nasync function main(): Promise<void> {\n  configureLogging();\n\n  const isProduction = process.env.NODE_ENV === 'production';\n  const host = resolveHost();\n  const port = resolvePort();\n  const baseUrl = process.env.MCP_URL?.trim() || undefined;\n  const allowedOrigins = resolveAllowedOrigins();\n\n  const { sessionConfig, cleanupFns } = await buildSessionConfig();\n\n  startupLogger.info(`Starting ${SERVER.NAME} v${SERVER.VERSION}`);\n  startupLogger.info(`Binding HTTP server to ${host}:${port}`);\n  if (allowedOrigins && allowedOrigins.length > 0) {\n    startupLogger.info(`Host validation enabled for origins: ${allowedOrigins.join(', ')}`);\n  } else if (isProduction) {\n    startupLogger.warn(\n      'Host validation is disabled because ALLOWED_ORIGINS is not set. ' +\n      'Set ALLOWED_ORIGINS to the public deployment URL or custom domain after the first deploy.',\n    );\n  } else {\n    startupLogger.info('Host validation disabled for local development');\n  }\n\n  const server = new MCPServer({\n    name: SERVER.NAME,\n    title: 'Research Powerpack',\n    version: SERVER.VERSION,\n    description: SERVER.DESCRIPTION,\n    websiteUrl: WEBSITE_URL,\n    host,\n    baseUrl,\n    cors: buildCors(allowedOrigins),\n    allowedOrigins,\n    ...sessionConfig,\n  });\n\n  registerAllTools(server);\n\n  const startedAt = Date.now();\n\n  server.get('/health', (c) => c.json(buildHealthPayload(server, startedAt)));\n  server.get('/healthz', (c) => c.json(buildHealthPayload(server, startedAt)));\n  server.resource(\n    {\n      name: 'server-health',\n      uri: 'health://status',\n      description: 'Current server health, uptime, and active MCP session count.',\n      mimeType: 'application/json',\n    },\n    async () => object(buildHealthPayload(server, startedAt)),\n  );\n\n  let isShuttingDown = false;\n\n  async function shutdown(signal: string, exitCode: number): Promise<void> {\n    if (isShuttingDown) return;\n    isShuttingDown = true;\n\n    const forceExit = setTimeout(() => {\n      startupLogger.error(`Forced exit after ${SHUTDOWN_TIMEOUT_MS}ms (${signal})`);\n      process.exit(1);\n    }, SHUTDOWN_TIMEOUT_MS);\n\n    try {\n      startupLogger.warn(`Shutdown signal received: ${signal}`);\n      await server.close();\n\n      for (const cleanupFn of cleanupFns) {\n        await cleanupFn();\n      }\n\n      clearTimeout(forceExit);\n      process.exit(exitCode);\n    } catch (error) {\n      clearTimeout(forceExit);\n      const message = error instanceof Error ? (error.stack ?? error.message) : String(error);\n      startupLogger.error(`Error while stopping server: ${message}`);\n      process.exit(1);\n    }\n  }\n\n  process.on('SIGTERM', () => {\n    void shutdown('SIGTERM', 0);\n  });\n\n  process.on('SIGINT', () => {\n    void shutdown('SIGINT', 0);\n  });\n\n  process.on('uncaughtException', (error) => {\n    startupLogger.error(`Uncaught exception: ${error.stack ?? error.message}`);\n    void shutdown('uncaughtException', 1);\n  });\n\n  process.on('unhandledRejection', (reason) => {\n    startupLogger.error(`Unhandled rejection: ${String(reason)}`);\n    void shutdown('unhandledRejection', 1);\n  });\n\n  await server.listen(port);\n\n  startupLogger.info(`${SERVER.NAME} v${SERVER.VERSION} listening on http://${host}:${port}/mcp`);\n}\n\nvoid main().catch((error) => {\n  const message = error instanceof Error ? (error.stack ?? error.message) : String(error);\n  startupLogger.error(`Server failed to start: ${message}`);\n  process.exit(1);\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/mcp-use.json

@@ -0,0 +1,7 @@
+{
+  "includeInspector": false,
+  "buildTime": "2026-03-26T14:07:11.298Z",
+  "buildId": "d76749f7bf0957bb",
+  "entryPoint": "dist/index.js",
+  "widgets": {}
+}

package/dist/src/clients/github.d.ts

@@ -0,0 +1,83 @@
+/**
+ * GitHub API Client
+ * GraphQL + REST client for fetching repository data for quality scoring.
+ * Implements robust error handling that NEVER crashes.
+ */
+import { type StructuredError } from '../utils/errors.js';
+export interface GitHubSearchItem {
+    readonly fullName: string;
+    readonly owner: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly stars: number;
+    readonly forks: number;
+    readonly language: string | null;
+    readonly pushedAt: string;
+    readonly url: string;
+}
+export interface ParticipationData {
+    readonly all: readonly number[];
+    readonly owner: readonly number[];
+}
+export interface ContributorEntry {
+    readonly login: string;
+    readonly contributions: number;
+}
+export interface RepoGraphQLData {
+    readonly stars: number;
+    readonly forks: number;
+    readonly watchers: number;
+    readonly openIssues: number;
+    readonly closedIssues: number;
+    readonly totalCommits: number;
+    readonly totalReleases: number;
+    readonly totalPRs: number;
+    readonly sizeKb: number;
+    readonly language: string | null;
+    readonly license: string | null;
+    readonly archived: boolean;
+    readonly createdAt: string;
+    readonly pushedAt: string;
+    readonly description: string | null;
+    readonly homepage: string | null;
+    readonly hasCI: boolean;
+    readonly hasContributing: boolean;
+    readonly hasIssueTemplate: boolean;
+    readonly hasPrTemplate: boolean;
+    readonly hasCodeOfConduct: boolean;
+    readonly hasTopics: boolean;
+}
+export interface RepoFullData {
+    readonly graphql: RepoGraphQLData;
+    readonly participation: ParticipationData;
+    readonly contributors: readonly ContributorEntry[];
+}
+export declare class GitHubClient {
+    private token;
+    private apiCallCount;
+    constructor(token?: string);
+    get apiCalls(): number;
+    searchRepos(query: string, sort?: string, perPage?: number): Promise<{
+        items: GitHubSearchItem[];
+        totalCount: number;
+        error?: StructuredError;
+    }>;
+    fetchRepoDetails(owner: string, name: string): Promise<{
+        data?: RepoFullData;
+        error?: StructuredError;
+    }>;
+    fetchMultipleRepoDetails(repos: Array<{
+        owner: string;
+        name: string;
+    }>): Promise<Array<{
+        owner: string;
+        name: string;
+        data?: RepoFullData;
+        error?: StructuredError;
+    }>>;
+    private graphqlQuery;
+    private fetchParticipation;
+    private fetchContributors;
+    private restGet;
+}
+//# sourceMappingURL=github.d.ts.map

package/dist/src/clients/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../src/clients/github.ts"],"names":[],"mappings":"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"}