freshcontext-mcp 0.3.3 → 0.3.5

package/USAGE.md

@@ -0,0 +1,294 @@
+# FreshContext — Usage Guide
+> *13 tools. No API keys. Every result timestamped.*
+
+---
+
+## Quick Start
+
+Add FreshContext to Claude Desktop (no install required):
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude. Done. All 13 tools are now available.
+
+---
+
+## The 13 Tools
+
+| Tool | What it does | Input |
+|---|---|---|
+| `extract_github` | README, stars, forks, last commit | GitHub URL |
+| `extract_hackernews` | Stories + scores with timestamps | HN URL or search query |
+| `extract_scholar` | Research papers ranked by year | Google Scholar URL |
+| `extract_arxiv` | arXiv papers via official API | Search query or arXiv URL |
+| `extract_reddit` | Subreddit posts + community sentiment | Subreddit URL |
+| `extract_yc` | YC company listings by keyword | Topic keyword |
+| `extract_producthunt` | Recent launches by topic | Topic or PH URL |
+| `search_repos` | GitHub repos ranked by stars + recency | Search query |
+| `package_trends` | npm/PyPI metadata + download stats | Package name(s) |
+| `extract_finance` | Live stock data — price, P/E, 52w range | Ticker symbol(s) |
+| `extract_landscape` | 6 sources in one call | Topic keyword |
+| `extract_changelog` | Update history from any product/repo | GitHub URL, npm name, or website URL |
+| `extract_govcontracts` | US federal contract awards | Company name, keyword, or NAICS code |
+
+---
+
+## Command Reference
+
+Copy and paste these directly into Claude.
+
+---
+
+### Competitive Research
+
+```
+Use extract_landscape with topic "AI data freshness"
+```
+*Full picture: who's funded, what's trending, what repos exist, what packages are moving.*
+
+```
+Use search_repos with query "mcp server typescript"
+```
+*GitHub repos ranked by stars. See who's already building in your space.*
+
+```
+Use extract_yc with query "developer infrastructure"
+```
+*Which YC companies are funded in your category.*
+
+```
+Use extract_producthunt with url "developer tools"
+```
+*What launched this week in your category.*
+
+---
+
+### Market Intelligence
+
+```
+Use extract_hackernews with url "https://hn.algolia.com/?q=model+context+protocol+2026"
+```
+*What the developer community is saying about a topic right now.*
+
+```
+Use extract_reddit with url "https://www.reddit.com/r/MachineLearning/"
+```
+*Subreddit sentiment — what problems people are complaining about or excited about.*
+
+```
+Use extract_finance with url "NVDA,MSFT,GOOGL"
+```
+*Live stock data for competitive set. Know the market before a pitch.*
+
+```
+Use extract_govcontracts with url "AI infrastructure"
+```
+*Which companies are winning federal AI contracts. High-signal GTM data.*
+
+```
+Use extract_govcontracts with url "Palantir"
+```
+*How much government business a specific company is doing — and when.*
+
+---
+
+### Job Market Intelligence
+
+```
+Use search_jobs with query "AI engineer" location "remote" max_age_days 7
+```
+*Fresh job listings only. Every result has a freshness badge — never apply to a closed role again.*
+
+```
+Use search_jobs with query "typescript developer" remote_only true
+```
+*Remote-only filtered results with publish dates.*
+
+```
+Use extract_govcontracts with url "541511"
+```
+*NAICS 541511 = Custom Computer Programming Services. See who's hiring via contract awards.*
+
+---
+
+### Developer Ecosystem Research
+
+```
+Use package_trends with url "mcp,wrangler,anthropic"
+```
+*npm download trends for multiple packages. See what's gaining traction.*
+
+```
+Use extract_changelog with url "https://github.com/anthropics/anthropic-sdk-python"
+```
+*Latest releases with dates. Know exactly when a dependency shipped a change.*
+
+```
+Use extract_changelog with url "freshcontext-mcp"
+```
+*npm package changelog — version history and release cadence.*
+
+```
+Use extract_changelog with url "https://linear.app"
+```
+*Auto-discovers the changelog page and extracts update history.*
+
+```
+Use search_repos with query "cloudflare workers MCP 2026"
+```
+*What's being built on a platform right now.*
+
+---
+
+### Academic & Research Intelligence
+
+```
+Use extract_arxiv with url "https://arxiv.org/search/?query=model+context+protocol&searchtype=all"
+```
+*Latest papers on a topic with submission dates.*
+
+```
+Use extract_scholar with url "https://scholar.google.com/scholar?q=AI+agent+grounding"
+```
+*Google Scholar results ranked by recency.*
+
+---
+
+### Full Research Workflows
+
+#### Validate a startup idea
+```
+1. Use extract_landscape with topic "[your idea]"
+2. Use extract_yc with query "[your idea]"
+3. Use extract_govcontracts with url "[your idea keyword]"
+4. Use extract_hackernews with url "https://hn.algolia.com/?q=[your+idea]"
+```
+*Tells you: who's funded, what's trending, is there government demand, what do developers think.*
+
+#### Research a company before a meeting
+```
+1. Use extract_github with url "https://github.com/[company]"
+2. Use extract_changelog with url "https://github.com/[company]/[main-repo]"
+3. Use extract_govcontracts with url "[company name]"
+4. Use extract_finance with url "[ticker]"
+```
+*Tells you: how active is their engineering team, what did they ship recently, do they have government contracts, what's the stock doing.*
+
+#### Find your next job
+```
+1. Use search_jobs with query "[your role]" max_age_days 7
+2. Use extract_govcontracts with url "[target company]"
+3. Use extract_changelog with url "https://github.com/[target-company]/[repo]"
+```
+*Fresh listings only + proof the company is growing + proof they're actively shipping.*
+
+#### Track a competitor
+```
+1. Use extract_changelog with url "https://[competitor].com"
+2. Use extract_github with url "https://github.com/[competitor]/[repo]"
+3. Use package_trends with url "[competitor-npm-package]"
+4. Use extract_hackernews with url "https://hn.algolia.com/?q=[competitor+name]"
+```
+*When did they last ship? Is their repo active? Are downloads growing? What is the community saying?*
+
+---
+
+## Who This Is For
+
+### Jobseekers
+The tool FreshContext was built for. Stop applying to roles that closed months ago. Every job listing comes with a freshness badge — green means posted this week, red means posted 60+ days ago. Filter by `max_age_days` to only see roles posted recently.
+
+**Key tools:** `search_jobs`, `extract_govcontracts`, `extract_changelog`
+
+---
+
+### Founders & Product Teams
+Validate ideas, track competitors, monitor your ecosystem. `extract_landscape` gives you a full competitive picture in one call — YC funding, GitHub activity, HN sentiment, Product Hunt launches, npm traction, all timestamped.
+
+**Key tools:** `extract_landscape`, `extract_yc`, `extract_changelog`, `extract_hackernews`
+
+---
+
+### GTM & Sales Teams
+Government contracts are buying intent signals. A company that just won a $5M DoD contract is hiring, spending, and building. FreshContext is the only MCP server with access to USASpending.gov contract data.
+
+**Key tools:** `extract_govcontracts`, `extract_landscape`, `extract_finance`
+
+---
+
+### Investors & Analysts
+Track portfolio companies, find signals before they're obvious, monitor competitor funding. `extract_govcontracts` shows government contract pipeline. `extract_changelog` shows engineering velocity. `extract_finance` gives live market data.
+
+**Key tools:** `extract_govcontracts`, `extract_landscape`, `extract_finance`, `extract_changelog`
+
+---
+
+### Researchers & Academics
+Fresh papers from arXiv and Google Scholar, ranked by date. Never cite a paper without knowing exactly when it was published and retrieved.
+
+**Key tools:** `extract_arxiv`, `extract_scholar`, `extract_hackernews`
+
+---
+
+### Developers & DevRel Teams
+Monitor your dependencies, track ecosystem traction, see what's getting attention in the community. `extract_changelog` works on any GitHub repo, npm package, or website that has a changelog.
+
+**Key tools:** `extract_changelog`, `package_trends`, `search_repos`, `extract_github`
+
+---
+
+## Understanding the FreshContext Envelope
+
+Every result is wrapped like this:
+
+```
+[FRESHCONTEXT]
+Source: https://github.com/owner/repo
+Published: 2026-03-10
+Retrieved: 2026-03-17T09:19:00Z
+Confidence: high
+---
+... content ...
+[/FRESHCONTEXT]
+```
+
+**Confidence levels:**
+- `high` — date came from a structured API field. Reliable.
+- `medium` — date inferred from page signals or URL patterns. Likely correct.
+- `low` — no date signal found. Treat with caution.
+
+The gap between `Published` and `Retrieved` is your staleness indicator. If a job was published 90 days ago and retrieved today, the role is likely filled. If a GitHub repo was last pushed 2 years ago, the project may be abandoned.
+
+---
+
+## Freshness Score (coming in v0.4.0)
+
+A numeric score from 0–100 will be added to every result:
+
+```
+freshness_score = max(0, 100 - (days_since_retrieved × decay_rate))
+```
+
+Different data types decay at different rates — financial data goes stale faster than academic papers. You'll be able to filter results by `freshness_score > 70` directly in your prompts.
+
+---
+
+## The Standard
+
+FreshContext implements the **FreshContext Specification v1.0** — an open standard for data freshness envelopes. See `FRESHCONTEXT_SPEC.md` for the full specification.
+
+Any tool or agent that wraps its retrieved data in the FreshContext envelope is **FreshContext-compatible**.
+
+---
+
+*Built by Prince Gabriel — Grootfontein, Namibia 🇳🇦*
+*"The work isn't gone. It's just waiting to be continued."*

package/dist/adapters/govcontracts.js

@@ -1,63 +1,84 @@
 /**
  * Government Contracts adapter — fetches awarded contract data from USASpending.gov
  *
- * Why this is unique:
- *   No other MCP server exposes government contract data.
- *   For GTM teams, VC investors, and competitive researchers, knowing when a
- *   company wins a government contract is a high-signal buying intent indicator.
- *   A company that just won a $2M DoD contract is hiring, spending, and building.
+ * No other MCP server has this. USASpending.gov is the official US Treasury
+ * database of all federal contract awards. Updated daily.
  *
  * Accepts:
- *   - Company name: "Cloudflare" → finds contracts awarded to that company
- *   - NAICS code: "541511" → software publishers contracts
- *   - Agency name: "Department of Defense" → all DoD contracts
- *   - Keyword: "AI infrastructure" → contracts with that keyword
- *   - A URL: https://api.usaspending.gov/... → direct API call
- *
- * Data source: USASpending.gov public API (no API key required)
- * Coverage: All US federal contracts, grants, and awards
- * Freshness: Updated daily by the US Treasury
- *
- * What it returns:
- *   - Award recipient name and location
- *   - Contract amount (obligated)
- *   - Award date (high confidence timestamp)
- *   - Awarding agency and sub-agency
- *   - Contract description / award title
- *   - NAICS code and description
- *   - Period of performance dates
+ *   - Company name: "Palantir" → contracts awarded to that company
+ *   - Keyword: "AI infrastructure" → contracts with that keyword in description
+ *   - NAICS code: "541511" → all software publisher contracts
+ *   - Direct URL: https://api.usaspending.gov/... → direct API call
  */
 function sanitize(s) {
     return s.replace(/[^\x20-\x7E]/g, "").trim();
 }
 function formatUSD(amount) {
-    if (amount === null || isNaN(amount))
+    if (amount === null || amount === undefined || isNaN(amount))
         return "N/A";
-    if (Math.abs(amount) >= 1_000_000)
+    const abs = Math.abs(amount);
+    if (abs >= 1_000_000_000)
+        return `$${(amount / 1_000_000_000).toFixed(2)}B`;
+    if (abs >= 1_000_000)
         return `$${(amount / 1_000_000).toFixed(2)}M`;
-    if (Math.abs(amount) >= 1_000)
+    if (abs >= 1_000)
         return `$${(amount / 1_000).toFixed(1)}K`;
     return `$${amount.toFixed(0)}`;
 }
-// ─── Search by recipient (company name) ──────────────────────────────────────
-async function searchByRecipient(query, maxLength) {
+const HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+    "User-Agent": "Mozilla/5.0 (compatible; freshcontext-mcp/1.0; +https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+};
+async function fetchJSON(url, body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 20000);
+    try {
+        const res = await fetch(url, {
+            method: body ? "POST" : "GET",
+            headers: HEADERS,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`);
+        }
+        return await res.json();
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// ─── Search by recipient name using autocomplete then awards ─────────────────
+async function searchByRecipient(name, maxLength) {
+    // Step 1: Use autocomplete to get the exact recipient name USASpending knows
+    let recipientName = name;
+    try {
+        const autoRes = await fetchJSON("https://api.usaspending.gov/api/v2/autocomplete/recipient/", { search_text: name, limit: 1 });
+        if (autoRes.results?.length) {
+            recipientName = autoRes.results[0].recipient_name;
+        }
+    }
+    catch {
+        // Use original name if autocomplete fails
+    }
+    // Step 2: Search awards with the resolved recipient name
     const body = {
         filters: {
-            recipient_search_text: [query],
-            time_period: [
-                {
+            recipient_search_text: [recipientName],
+            time_period: [{
                     start_date: new Date(Date.now() - 365 * 2 * 86400000).toISOString().slice(0, 10),
                     end_date: new Date().toISOString().slice(0, 10),
-                },
-            ],
-            award_type_codes: ["A", "B", "C", "D"], // contracts only
+                }],
+            award_type_codes: ["A", "B", "C", "D"],
         },
         fields: [
-            "Award_ID", "Recipient_Name", "Award_Amount", "Description",
+            "Award_ID", "Recipient_Name", "Award_Amount",
             "Award_Date", "Start_Date", "End_Date",
             "Awarding_Agency_Name", "Awarding_Sub_Agency_Name",
-            "recipient_location_state_name", "recipient_location_city_name",
-            "naics_code", "naics_description",
+            "Description", "recipient_location_state_name",
+            "recipient_location_city_name", "naics_code", "naics_description",
         ],
         page: 1,
         limit: 10,
@@ -65,41 +86,33 @@ async function searchByRecipient(query, maxLength) {
         order: "desc",
         subawards: false,
     };
-    const res = await fetch("https://api.usaspending.gov/api/v2/search/spending_by_award/", {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "User-Agent": "freshcontext-mcp" },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok)
-        throw new Error(`USASpending API error: ${res.status}`);
-    const data = await res.json();
+    const data = await fetchJSON("https://api.usaspending.gov/api/v2/search/spending_by_award/", body);
     if (!data.results?.length) {
         return {
-            raw: `No federal contracts found for "${query}" in the last 2 years.\n\nThis could mean:\n- The company name differs from the registered recipient name\n- The company operates under a subsidiary name\n- No contracts awarded in this period\n\nTry searching by parent company name or NAICS code.`,
+            raw: `No federal contracts found for "${name}" (searched as "${recipientName}") in the last 2 years.\n\nTips:\n- Try the full legal company name (e.g. "Palantir Technologies Inc")\n- Try a keyword search instead (e.g. "AI data analytics")\n- Try a NAICS code (e.g. 541511 for software)`,
             content_date: null,
             freshness_confidence: "high",
         };
     }
-    return formatResults(data.results, `Federal contracts — ${query}`, maxLength);
+    return formatResults(data.results, `Federal contracts — ${recipientName}`, maxLength);
 }
 // ─── Search by keyword ────────────────────────────────────────────────────────
 async function searchByKeyword(keyword, maxLength) {
     const body = {
         filters: {
             keywords: [keyword],
-            time_period: [
-                {
+            time_period: [{
                     start_date: new Date(Date.now() - 365 * 86400000).toISOString().slice(0, 10),
                     end_date: new Date().toISOString().slice(0, 10),
-                },
-            ],
+                }],
             award_type_codes: ["A", "B", "C", "D"],
         },
         fields: [
-            "Award_ID", "Recipient_Name", "Award_Amount", "Description",
+            "Award_ID", "Recipient_Name", "Award_Amount",
             "Award_Date", "Start_Date", "End_Date",
             "Awarding_Agency_Name", "Awarding_Sub_Agency_Name",
-            "recipient_location_state_name", "naics_code", "naics_description",
+            "Description", "recipient_location_state_name",
+            "naics_code", "naics_description",
         ],
         page: 1,
         limit: 10,
@@ -107,17 +120,10 @@ async function searchByKeyword(keyword, maxLength) {
         order: "desc",
         subawards: false,
     };
-    const res = await fetch("https://api.usaspending.gov/api/v2/search/spending_by_award/", {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "User-Agent": "freshcontext-mcp" },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok)
-        throw new Error(`USASpending keyword search error: ${res.status}`);
-    const data = await res.json();
+    const data = await fetchJSON("https://api.usaspending.gov/api/v2/search/spending_by_award/", body);
     if (!data.results?.length) {
         return {
-            raw: `No federal contracts found matching keyword "${keyword}" in the last year.`,
+            raw: `No federal contracts found matching "${keyword}" in the last year.`,
             content_date: null,
             freshness_confidence: "high",
         };
@@ -128,35 +134,30 @@ async function searchByKeyword(keyword, maxLength) {
 function formatResults(results, title, maxLength) {
     const lines = [title, ""];
     results.forEach((award, i) => {
-        const desc = sanitize(award.Description ?? "No description");
+        const desc = sanitize(award.Description ?? "No description").slice(0, 300);
         const location = [award.recipient_location_city_name, award.recipient_location_state_name]
             .filter(Boolean).join(", ") || "N/A";
         lines.push(`[${i + 1}] ${sanitize(award.Recipient_Name ?? "Unknown")}`);
-        lines.push(`    Amount: ${formatUSD(award.Award_Amount)}`);
+        lines.push(`    Amount: ${formatUSD(award.Award_Amount ?? null)}`);
         lines.push(`    Awarded: ${award.Award_Date?.slice(0, 10) ?? "unknown"}`);
         lines.push(`    Period: ${award.Start_Date?.slice(0, 10) ?? "?"} → ${award.End_Date?.slice(0, 10) ?? "?"}`);
         lines.push(`    Agency: ${sanitize(award.Awarding_Agency_Name ?? "N/A")}`);
-        if (award.Awarding_Sub_Agency_Name && award.Awarding_Sub_Agency_Name !== award.Awarding_Agency_Name) {
+        if (award.Awarding_Sub_Agency_Name !== award.Awarding_Agency_Name && award.Awarding_Sub_Agency_Name) {
             lines.push(`    Sub-agency: ${sanitize(award.Awarding_Sub_Agency_Name)}`);
         }
         if (award.naics_code) {
             lines.push(`    NAICS: ${award.naics_code} — ${sanitize(award.naics_description ?? "")}`);
         }
         lines.push(`    Location: ${location}`);
-        lines.push(`    Description: ${desc.slice(0, 200)}`);
+        lines.push(`    Description: ${desc}`);
         lines.push("");
     });
     const raw = lines.join("\n").slice(0, maxLength);
-    // Newest award date for freshness
-    const dates = results
-        .map((r) => r.Award_Date)
-        .filter(Boolean)
-        .sort()
-        .reverse();
+    const dates = results.map(r => r.Award_Date).filter(Boolean).sort().reverse();
     return {
         raw,
         content_date: dates[0] ?? null,
-        freshness_confidence: "high", // USASpending dates are structured API fields
+        freshness_confidence: "high",
     };
 }
 // ─── Main export ──────────────────────────────────────────────────────────────
@@ -167,30 +168,30 @@ export async function govContractsAdapter(options) {
         throw new Error("Query required: company name, keyword, or NAICS code");
     // Direct API URL
     if (input.startsWith("https://api.usaspending.gov")) {
-        const res = await fetch(input, { headers: { "User-Agent": "freshcontext-mcp" } });
-        if (!res.ok)
-            throw new Error(`USASpending direct fetch error: ${res.status}`);
-        const data = await res.json();
-        const raw = JSON.stringify(data, null, 2).slice(0, maxLength);
-        return { raw, content_date: new Date().toISOString(), freshness_confidence: "high" };
+        const data = await fetchJSON(input);
+        return {
+            raw: JSON.stringify(data, null, 2).slice(0, maxLength),
+            content_date: new Date().toISOString(),
+            freshness_confidence: "high",
+        };
     }
-    // NAICS code (6 digits)
+    // NAICS code (6 digits) — treat as keyword
     if (/^\d{6}$/.test(input)) {
         return searchByKeyword(input, maxLength);
     }
-    // Default: try as recipient name first, fall back to keyword
+    // Multi-word input or known company name → try recipient first, fall back to keyword
     try {
         const result = await searchByRecipient(input, maxLength);
-        // If no results found, try keyword search
-        if (result.raw.includes("No federal contracts found")) {
-            const kwResult = await searchByKeyword(input, maxLength);
-            if (!kwResult.raw.includes("No federal contracts found")) {
-                return kwResult;
-            }
-        }
-        return result;
+        if (!result.raw.includes("No federal contracts found"))
+            return result;
+        // Fall back to keyword search
+        const kwResult = await searchByKeyword(input, maxLength);
+        if (!kwResult.raw.includes("No federal contracts found"))
+            return kwResult;
+        return result; // Return the "not found" message from recipient search
     }
-    catch {
+    catch (err) {
+        // If recipient search fails entirely, try keyword
         return searchByKeyword(input, maxLength);
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "freshcontext-mcp",
   "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
   "keywords": [
     "mcp",