govconapi-mcp 0.1.0__tar.gz

govconapi_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.DS_Store

govconapi_mcp-0.1.0/CLAUDE_CONFIG_EXAMPLE.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "govconapi": {
+      "command": "govconapi-mcp",
+      "env": {
+        "GOVCONAPI_KEY": "gca_REPLACE_WITH_YOUR_KEY"
+      }
+    }
+  }
+}

govconapi_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: govconapi-mcp
+Version: 0.1.0
+Summary: MCP server for GovCon API – federal contract opportunities, awards, and exclusions in Claude/ChatGPT/any MCP client
+Project-URL: Homepage, https://govconapi.com
+Project-URL: Documentation, https://govconapi.com/api-guide
+Project-URL: Repository, https://github.com/rozetyp/sam-api
+Author-email: GovCon API <support@govconapi.com>
+License: MIT
+Keywords: claude,federal-contracts,govcon,mcp,model-context-protocol,sam-gov
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# GovCon API — MCP Server
+
+Federal contract opportunities, awards, and exclusions inside Claude Desktop, ChatGPT, or any MCP-compatible client.
+
+Ask in natural language:
+
+> "Find DoD cybersecurity solicitations posted this month over $1M."
+
+> "What's the canonical SAM.gov agency name for FEMA?"
+
+> "Has Acme Corp ever been excluded from federal contracts?"
+
+> "Show me everything that changed since yesterday."
+
+Powered by [GovCon API](https://govconapi.com) — a clean SAM.gov data layer.
+
+---
+
+## Install
+
+```bash
+pip install govconapi-mcp
+```
+
+You'll need:
+
+- Python 3.10+
+- A GovCon API key — [free 14-day trial](https://govconapi.com), no credit card
+
+---
+
+## Configure Claude Desktop
+
+Add to your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "govconapi": {
+      "command": "govconapi-mcp",
+      "env": {
+        "GOVCONAPI_KEY": "gca_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the GovCon tools appear in the tool picker.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_opportunities` | Search SAM.gov opportunities by NAICS, PSC, agency, state, keywords, set-aside, dates, value range |
+| `get_opportunity` | Fetch one opportunity by notice_id (50+ fields) |
+| `recent_changes` | Incremental sync — what's new since a timestamp |
+| `lookup_agency` | Resolve "FEMA" / "DoD" / "VA" to canonical SAM.gov agency strings |
+| `check_exclusion` | Debarment screening by name, UEI, or CAGE code |
+| `search_awards` | Find who won contracts (company, amount, date) |
+
+---
+
+## Example Claude prompts
+
+- *"Search for HUBZone-set-aside opportunities in NAICS 541330 posted after April 1."*
+- *"What agency string should I use to filter for all FEMA contracts?"*
+- *"Find Award Notice records over $5M in California from the last 30 days."*
+- *"Has [vendor name] ever appeared on the exclusions list?"*
+- *"What's changed in the federal contracts dataset since 2026-04-12?"*
+
+---
+
+## Plan limits
+
+- **Free Trial:** 25 requests/day for 14 days
+- **Developer ($19/mo):** 1,000 requests/hour, all filters, CSV export
+- **Pro Bundle ($39/mo):** Everything in Developer + unlimited GovCon Contacts directory
+
+See [govconapi.com/pricing](https://govconapi.com/pricing).
+
+---
+
+## Troubleshooting
+
+**"GOVCONAPI_KEY environment variable is not set"**
+Add the env var to your Claude Desktop MCP config (see above) and restart Claude.
+
+**"Invalid API key"**
+Get a new one at [govconapi.com](https://govconapi.com) — keys start with `gca_`.
+
+**"At least one filter required"**
+The `search_opportunities` tool requires at least one filter (naics, keywords, state, etc.). If you want a bulk dump, use `recent_changes` instead.
+
+**Rate limited (429)**
+Free trial: 25 calls/day. Developer: 1,000/hour. Wait or upgrade.
+
+---
+
+## License
+
+MIT
+
+## Support
+
+[support@govconapi.com](mailto:support@govconapi.com)

govconapi_mcp-0.1.0/README.md

@@ -0,0 +1,111 @@
+# GovCon API — MCP Server
+
+Federal contract opportunities, awards, and exclusions inside Claude Desktop, ChatGPT, or any MCP-compatible client.
+
+Ask in natural language:
+
+> "Find DoD cybersecurity solicitations posted this month over $1M."
+
+> "What's the canonical SAM.gov agency name for FEMA?"
+
+> "Has Acme Corp ever been excluded from federal contracts?"
+
+> "Show me everything that changed since yesterday."
+
+Powered by [GovCon API](https://govconapi.com) — a clean SAM.gov data layer.
+
+---
+
+## Install
+
+```bash
+pip install govconapi-mcp
+```
+
+You'll need:
+
+- Python 3.10+
+- A GovCon API key — [free 14-day trial](https://govconapi.com), no credit card
+
+---
+
+## Configure Claude Desktop
+
+Add to your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "govconapi": {
+      "command": "govconapi-mcp",
+      "env": {
+        "GOVCONAPI_KEY": "gca_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the GovCon tools appear in the tool picker.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_opportunities` | Search SAM.gov opportunities by NAICS, PSC, agency, state, keywords, set-aside, dates, value range |
+| `get_opportunity` | Fetch one opportunity by notice_id (50+ fields) |
+| `recent_changes` | Incremental sync — what's new since a timestamp |
+| `lookup_agency` | Resolve "FEMA" / "DoD" / "VA" to canonical SAM.gov agency strings |
+| `check_exclusion` | Debarment screening by name, UEI, or CAGE code |
+| `search_awards` | Find who won contracts (company, amount, date) |
+
+---
+
+## Example Claude prompts
+
+- *"Search for HUBZone-set-aside opportunities in NAICS 541330 posted after April 1."*
+- *"What agency string should I use to filter for all FEMA contracts?"*
+- *"Find Award Notice records over $5M in California from the last 30 days."*
+- *"Has [vendor name] ever appeared on the exclusions list?"*
+- *"What's changed in the federal contracts dataset since 2026-04-12?"*
+
+---
+
+## Plan limits
+
+- **Free Trial:** 25 requests/day for 14 days
+- **Developer ($19/mo):** 1,000 requests/hour, all filters, CSV export
+- **Pro Bundle ($39/mo):** Everything in Developer + unlimited GovCon Contacts directory
+
+See [govconapi.com/pricing](https://govconapi.com/pricing).
+
+---
+
+## Troubleshooting
+
+**"GOVCONAPI_KEY environment variable is not set"**
+Add the env var to your Claude Desktop MCP config (see above) and restart Claude.
+
+**"Invalid API key"**
+Get a new one at [govconapi.com](https://govconapi.com) — keys start with `gca_`.
+
+**"At least one filter required"**
+The `search_opportunities` tool requires at least one filter (naics, keywords, state, etc.). If you want a bulk dump, use `recent_changes` instead.
+
+**Rate limited (429)**
+Free trial: 25 calls/day. Developer: 1,000/hour. Wait or upgrade.
+
+---
+
+## License
+
+MIT
+
+## Support
+
+[support@govconapi.com](mailto:support@govconapi.com)

govconapi_mcp-0.1.0/govconapi_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""GovCon API MCP server — federal contract data for AI assistants."""
+__version__ = "0.1.0"

govconapi_mcp-0.1.0/govconapi_mcp/server.py

@@ -0,0 +1,327 @@
+"""GovCon API MCP server.
+
+Exposes federal contract opportunities, awards, exclusions, and the agency
+crosswalk as MCP tools so AI clients (Claude Desktop, etc.) can query
+SAM.gov data through natural language.
+
+Configuration: set GOVCONAPI_KEY in your client's MCP config (see README).
+Get a free trial key at https://govconapi.com.
+"""
+from __future__ import annotations
+
+import os
+import json
+from typing import Optional
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+
+BASE_URL = os.environ.get("GOVCONAPI_BASE", "https://govconapi.com")
+API_KEY = os.environ.get("GOVCONAPI_KEY")
+TIMEOUT = 30.0
+USER_AGENT = "govconapi-mcp/0.1.0"
+
+mcp = FastMCP("govconapi")
+
+
+def _client() -> httpx.AsyncClient:
+    if not API_KEY:
+        raise RuntimeError(
+            "GOVCONAPI_KEY environment variable is not set. "
+            "Get a free trial key at https://govconapi.com and add it to your "
+            "MCP client configuration."
+        )
+    return httpx.AsyncClient(
+        base_url=BASE_URL,
+        headers={
+            "Authorization": f"Bearer {API_KEY}",
+            "User-Agent": USER_AGENT,
+        },
+        timeout=TIMEOUT,
+    )
+
+
+def _drop_none(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v is not None and v != ""}
+
+
+async def _get(path: str, params: dict | None = None) -> dict:
+    """Issue a GET request and return parsed JSON, raising friendly errors."""
+    async with _client() as client:
+        try:
+            r = await client.get(path, params=_drop_none(params or {}))
+        except httpx.TimeoutException:
+            raise RuntimeError(f"GovCon API timed out after {TIMEOUT}s.")
+        except httpx.RequestError as e:
+            raise RuntimeError(f"Network error reaching GovCon API: {e}")
+
+    if r.status_code == 401:
+        raise RuntimeError(
+            "Invalid API key. Check GOVCONAPI_KEY in your MCP config. "
+            "Get a key at https://govconapi.com."
+        )
+    if r.status_code == 402:
+        raise RuntimeError(
+            "Free trial expired. Upgrade at https://govconapi.com/pricing."
+        )
+    if r.status_code == 429:
+        raise RuntimeError("Rate limit exceeded. Try again in a moment.")
+    if r.status_code == 400:
+        try:
+            detail = r.json().get("detail", r.text)
+        except Exception:
+            detail = r.text
+        raise RuntimeError(f"Bad request: {detail}")
+    if r.status_code >= 500:
+        raise RuntimeError(f"GovCon API error {r.status_code}. Please retry.")
+    if r.status_code == 404:
+        return {"data": [], "_status": 404, "_message": "Not found"}
+
+    return r.json()
+
+
+# ─── Tools ────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+async def search_opportunities(
+    naics: Optional[str] = None,
+    psc: Optional[str] = None,
+    naics_multiple: Optional[str] = None,
+    agency: Optional[str] = None,
+    keywords: Optional[str] = None,
+    state: Optional[str] = None,
+    set_aside: Optional[str] = None,
+    notice_type: Optional[str] = None,
+    posted_after: Optional[str] = None,
+    due_before: Optional[str] = None,
+    due_after: Optional[str] = None,
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+    value_min: Optional[float] = None,
+    value_max: Optional[float] = None,
+    has_attachments: Optional[bool] = None,
+    sort_by: Optional[str] = None,
+    limit: int = 20,
+    offset: int = 0,
+) -> str:
+    """Search federal contract opportunities (SAM.gov data) with filters.
+
+    At least one filter is required. Use specific values:
+    - naics: 6-digit NAICS code, e.g. "541330" (engineering services)
+    - psc: 1-4 char Product Service Code, e.g. "D302" (IT services)
+    - naics_multiple: comma-separated NAICS codes, e.g. "541511,541512"
+    - agency: agency name substring (use full names, e.g. "FEDERAL EMERGENCY MANAGEMENT" not "FEMA"; use lookup_agency tool first)
+    - keywords: full-text search across title, agency, description (min 3 chars)
+    - state: 2-letter state code (CA, TX) or full name (California)
+    - set_aside: SBA, 8(a), SDVOSB, HZC, SBP, etc.
+    - notice_type: Solicitation, Award Notice, Presolicitation, Combined Synopsis/Solicitation, Sources Sought
+    - posted_after / due_before / due_after / date_from / date_to: YYYY-MM-DD
+    - value_min / value_max: USD amounts (only Award Notice records have values)
+    - has_attachments: true/false
+    - sort_by: posted_date, due_date, award_amount, title, agency
+    - limit: max 1000
+
+    Returns JSON with `data` (matching opportunities), `pagination`, and `filters_applied`.
+    For full-database sync use the recent_changes tool instead.
+    """
+    params = {
+        "naics": naics, "psc": psc, "naics_multiple": naics_multiple,
+        "agency": agency, "keywords": keywords, "state": state,
+        "set_aside": set_aside, "notice_type": notice_type,
+        "posted_after": posted_after, "due_before": due_before, "due_after": due_after,
+        "date_from": date_from, "date_to": date_to,
+        "value_min": value_min, "value_max": value_max,
+        "has_attachments": has_attachments, "sort_by": sort_by,
+        "limit": limit, "offset": offset,
+    }
+    data = await _get("/api/v1/opportunities/search", params)
+    return json.dumps(data, indent=2, default=str)
+
+
+@mcp.tool()
+async def get_opportunity(notice_id: str) -> str:
+    """Fetch a single contract opportunity by its notice_id.
+
+    Returns the full record including agency, contacts, description, attachments,
+    award data (if applicable), and 50+ structured fields.
+    """
+    data = await _get(f"/api/v1/opportunities/{notice_id}")
+    return json.dumps(data, indent=2, default=str)
+
+
+@mcp.tool()
+async def recent_changes(
+    since: str,
+    limit: int = 100,
+    offset: int = 0,
+) -> str:
+    """List opportunities added or updated since a timestamp.
+
+    Use this for incremental sync instead of paginating through search results.
+    Keyset-based, so depth doesn't degrade performance.
+
+    - since: ISO 8601 timestamp, e.g. "2026-04-12T00:00:00Z"
+    - limit: max 1000 per page
+
+    Returns `data` (changed records), `pagination`, and `sync.server_time` —
+    save server_time and pass it as `since` on your next call.
+    """
+    params = {"since": since, "limit": limit, "offset": offset}
+    data = await _get("/api/v1/opportunities/delta", params)
+    return json.dumps(data, indent=2, default=str)
+
+
+@mcp.tool()
+async def lookup_agency(query: str) -> str:
+    """Resolve an agency acronym or partial name to canonical SAM.gov agency strings.
+
+    SAM.gov stores agency names like "HOMELAND SECURITY, DEPARTMENT OF.FEDERAL
+    EMERGENCY MANAGEMENT AGENCY..." not "FEMA". Use this to find the right
+    substring to use as the `agency` filter in search_opportunities.
+
+    - query: acronym (FEMA, DoD, NASA), partial name, or full agency name
+
+    Returns matching agencies grouped by canonical name with the suggested
+    filter value to use.
+    """
+    # Acronym hints help map common shorthand to canonical phrases the data uses
+    HINTS = {
+        "fema": "federal emergency management",
+        "dod": "defense", "usda": "agriculture", "doj": "justice",
+        "dot": "transportation", "hhs": "health and human", "dhs": "homeland security",
+        "epa": "environmental protection", "nasa": "aeronautics", "nih": "health",
+        "va": "veterans", "irs": "internal revenue", "sec": "securities exchange",
+        "fbi": "investigation", "cia": "intelligence", "dea": "drug enforcement",
+        "atf": "alcohol tobacco", "nsa": "national security", "usps": "postal",
+        "faa": "aviation", "fcc": "communications", "fda": "food and drug",
+        "usaid": "international development", "ssa": "social security",
+        "cms": "medicare medicaid", "cdc": "disease control",
+        "osha": "occupational safety", "uscg": "coast guard",
+        "usaf": "air force", "usmc": "marine", "doe": "energy",
+        "hud": "housing urban", "doi": "interior", "dol": "labor",
+    }
+
+    raw = await _get("/api/agency-crosswalk")
+    rows = raw.get("data", [])
+
+    q = query.lower().strip()
+    expansion = HINTS.get(q)
+
+    def haystack(r: dict) -> str:
+        return (
+            f"{r.get('raw_agency_text','')} "
+            f"{r.get('canonical_agency','')} "
+            f"{r.get('department','')}"
+        ).lower()
+
+    def matches(r: dict) -> bool:
+        h = haystack(r)
+        if expansion:
+            return expansion in h
+        if len(q) <= 4:
+            # Word-boundary match for short queries to avoid e.g. "EPA" in "dEPArtment"
+            import re
+            return bool(re.search(rf"(^|[^a-z]){re.escape(q)}($|[^a-z])", h))
+        return q in h
+
+    matched = [r for r in rows if matches(r)]
+
+    # Group by canonical name
+    groups: dict[str, dict] = {}
+    for row in matched:
+        key = row.get("canonical_agency") or row.get("raw_agency_text") or "(unknown)"
+        g = groups.setdefault(key, {
+            "canonical_agency": key,
+            "department": row.get("department", ""),
+            "suggested_filter_value": key,
+            "total_contracts": 0,
+            "variation_count": 0,
+            "raw_variations": [],
+        })
+        g["total_contracts"] += int(row.get("frequency") or 0)
+        g["variation_count"] += 1
+        g["raw_variations"].append({
+            "raw": row.get("raw_agency_text", ""),
+            "frequency": row.get("frequency", 0),
+        })
+
+    grouped = sorted(groups.values(), key=lambda x: -x["total_contracts"])
+
+    # Trim raw_variations to top 5 per group
+    for g in grouped:
+        g["raw_variations"] = sorted(g["raw_variations"], key=lambda x: -(x.get("frequency") or 0))[:5]
+
+    return json.dumps({
+        "query": query,
+        "expansion_used": expansion,
+        "match_count": len(matched),
+        "agency_count": len(grouped),
+        "agencies": grouped[:15],
+    }, indent=2, default=str)
+
+
+@mcp.tool()
+async def check_exclusion(
+    name: Optional[str] = None,
+    uei: Optional[str] = None,
+    cage_code: Optional[str] = None,
+    limit: int = 10,
+) -> str:
+    """Check the SAM.gov exclusions list (debarred / suspended entities).
+
+    Use this before subcontracting or teaming. Provide at least one of:
+    - name: company or individual name (partial match)
+    - uei: Unique Entity ID
+    - cage_code: CAGE code
+
+    Returns matching exclusion records with the reason, agency, and dates.
+    """
+    if not (name or uei or cage_code):
+        raise RuntimeError("Provide at least one of: name, uei, cage_code")
+    params = {"name": name, "uei": uei, "cage_code": cage_code, "limit": limit}
+    data = await _get("/api/v1/exclusions/search", params)
+    return json.dumps(data, indent=2, default=str)
+
+
+@mcp.tool()
+async def search_awards(
+    awardee: Optional[str] = None,
+    uei: Optional[str] = None,
+    naics: Optional[str] = None,
+    agency: Optional[str] = None,
+    value_min: Optional[float] = None,
+    value_max: Optional[float] = None,
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+    limit: int = 20,
+    offset: int = 0,
+) -> str:
+    """Search federal contract awards (who won, how much, when).
+
+    - awardee: company name (partial match)
+    - uei: Unique Entity ID
+    - naics: 6-digit NAICS code
+    - agency: agency name substring
+    - value_min / value_max: USD
+    - date_from / date_to: YYYY-MM-DD
+    - limit: max 1000
+    """
+    params = {
+        "awardee": awardee, "uei": uei, "naics": naics, "agency": agency,
+        "value_min": value_min, "value_max": value_max,
+        "date_from": date_from, "date_to": date_to,
+        "limit": limit, "offset": offset,
+    }
+    data = await _get("/api/v1/awards/search", params)
+    return json.dumps(data, indent=2, default=str)
+
+
+def main() -> None:
+    """Entry point — runs the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

govconapi_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "govconapi-mcp"
+version = "0.1.0"
+description = "MCP server for GovCon API – federal contract opportunities, awards, and exclusions in Claude/ChatGPT/any MCP client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "GovCon API", email = "support@govconapi.com" }]
+keywords = ["mcp", "model-context-protocol", "federal-contracts", "sam-gov", "govcon", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://govconapi.com"
+Documentation = "https://govconapi.com/api-guide"
+Repository = "https://github.com/rozetyp/sam-api"
+
+[project.scripts]
+govconapi-mcp = "govconapi_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["govconapi_mcp"]