freshcontext-mcp

Instructions

Implementation Reference

• src/server.ts:267-289 (handler)

  Registration of the extract_govcontracts tool.

  server.registerTool(
    "extract_govcontracts",
    {
      description:
        "Fetch US federal government contract awards from USASpending.gov. No API key required. Search by company name (e.g. 'Palantir'), keyword (e.g. 'AI infrastructure'), or NAICS code (e.g. '541511'). Returns award amounts, dates, awarding agency, NAICS code, and contract descriptions — all timestamped. Use this to find buying intent signals (a company that just won a $5M DoD contract is actively hiring and spending), competitive intelligence, or GTM targeting.",
      inputSchema: z.object({
        url: z.string().describe(
          "Company name (e.g. 'Cloudflare'), keyword (e.g. 'machine learning'), NAICS code (e.g. '541511'), or direct USASpending API URL."
        ),
        max_length: z.number().optional().default(6000).describe("Max content length"),
      }),
      annotations: { readOnlyHint: true, openWorldHint: true },
    },
    async ({ url, max_length }) => {
      try {
        const result = await govContractsAdapter({ url, maxLength: max_length });
        const ctx = stampFreshness(result, { url, maxLength: max_length }, "govcontracts");
        return { content: [{ type: "text", text: formatForLLM(ctx) }] };
      } catch (err) {
        return { content: [{ type: "text", text: formatSecurityError(err) }] };
      }
    }
  );

• src/adapters/govcontracts.ts:241-272 (handler)

  The implementation (handler) logic for the govcontracts tool.

  export async function govContractsAdapter(options: ExtractOptions): Promise<AdapterResult> {
    const input = (options.url ?? "").trim();
    const maxLength = options.maxLength ?? 6000;
  
    if (!input) throw new Error("Query required: company name, keyword, or NAICS code");
  
    // Direct GET endpoint (non-search URLs)
    if (input.startsWith("https://api.usaspending.gov") && !input.includes("spending_by_award")) {
      const data = await getJSON(input);
      return {
        raw: JSON.stringify(data, null, 2).slice(0, maxLength),
        content_date: new Date().toISOString(),
        freshness_confidence: "high",
      };
    }
  
    // NAICS code (6 digits)
    if (/^\d{6}$/.test(input)) {
      return searchByKeyword(input, maxLength);
    }
  
    // Company name or keyword — try recipient first, fall back to keyword
    try {
      const result = await searchByRecipient(input, maxLength);
      if (!result.raw.includes("No federal contracts found")) return result;
      const kwResult = await searchByKeyword(input, maxLength);
      if (!kwResult.raw.includes("No federal contracts found")) return kwResult;
      return result;
    } catch {
      return searchByKeyword(input, maxLength);
    }
  }