freshcontext-mcp

Instructions

Implementation Reference

• src/server.ts:121-130 (registration)

  Registration of the 'search_repos' tool in server.ts.

  server.registerTool(
    "search_repos",
    {
      description:
        "Search GitHub for repositories matching a keyword or topic. Returns top results by stars with activity signals. Use to find competitors, similar tools, or related projects.",
      inputSchema: z.object({
        query: z.string().describe("Search query e.g. 'mcp server typescript' or 'cashflow prediction python'"),
        max_length: z.number().optional().default(6000),
      }),
      annotations: { readOnlyHint: true, openWorldHint: true },

• src/server.ts:132-140 (handler)

  The tool handler function in server.ts which calls repoSearchAdapter.

  async ({ query, max_length }) => {
    try {
      const result = await repoSearchAdapter({ url: query, maxLength: max_length });
      const ctx = stampFreshness(result, { url: query, maxLength: max_length }, "github_search");
      return { content: [{ type: "text", text: formatForLLM(ctx) }] };
    } catch (err) {
      return { content: [{ type: "text", text: formatSecurityError(err) }] };
    }
  }

• src/adapters/repoSearch.ts:5-79 (handler)

  The actual implementation of the repoSearch logic.

  export async function repoSearchAdapter(options: ExtractOptions): Promise<AdapterResult> {
    // Sanitize query input
    const query_input = sanitizeQuery(options.url);
    let query = query_input;
  
    // If it's a full URL, extract the query param
    try {
      const parsed = new URL(options.url);
      if (parsed.hostname === "github.com" && parsed.pathname.includes("/search")) {
        query = parsed.searchParams.get("q") ?? options.url;
      } else if (parsed.hostname === "github.com") {
        // It's a direct URL — not a search
        query = parsed.pathname.replace("/search", "").trim().replace(/^\//, "");
      }
    } catch {
      // plain string query, use as-is
    }
  
    const apiUrl = `https://api.github.com/search/repositories?q=${encodeURIComponent(query)}&sort=stars&order=desc&per_page=10`;
  
    const res = await fetch(apiUrl, {
      headers: {
        Accept: "application/vnd.github.v3+json",
        "User-Agent": "freshcontext-mcp/0.1.0",
      },
    });
  
    if (!res.ok) {
      throw new Error(`GitHub Search API error: ${res.status} ${await res.text()}`);
    }
  
    const data = await res.json() as {
      total_count: number;
      items: Array<{
        full_name: string;
        description: string | null;
        html_url: string;
        stargazers_count: number;
        forks_count: number;
        language: string | null;
        topics: string[];
        pushed_at: string;
        created_at: string;
        open_issues_count: number;
      }>;
    };
  
    const raw = [
      `Total matching repos: ${data.total_count.toLocaleString()}`,
      `Top ${data.items.length} by stars:\n`,
      ...data.items.map((r, i) =>
        [
          `[${i + 1}] ${r.full_name}`,
          `⭐ ${r.stargazers_count.toLocaleString()} stars | 🍴 ${r.forks_count} forks | Issues: ${r.open_issues_count}`,
          `Language: ${r.language ?? "unknown"}`,
          `Topics: ${r.topics?.join(", ") || "none"}`,
          `Description: ${r.description ?? "N/A"}`,
          `Last push: ${r.pushed_at}`,
          `Created: ${r.created_at}`,
          `URL: ${r.html_url}`,
        ].join("\n")
      ),
    ]
      .join("\n\n")
      .slice(0, options.maxLength ?? 6000);
  
    // Most recently pushed repo date as content_date
    const dates = data.items.map((r) => r.pushed_at).sort().reverse();
  
    return {
      raw,
      content_date: dates[0] ?? null,
      freshness_confidence: "high",
    };
  }