# US Federal Procurement MCP

**Federal contracting intelligence for small businesses** — as an MCP server. Search contract opportunities, understand set-asides and NAICS codes, and analyze solicitations for small-business fit and risk — from inside Claude, Cursor, or any MCP client.

This fills the biggest gap in US small-business (SBA) contracting: an LLM trained on the public internet cannot know **current** contract opportunities or reliably recall the set-aside rules, FAR thresholds, and NAICS structure that determine whether a bid is even worth pursuing. This server makes that real and queryable.

---

## Tools (9)

| Tool | What it does |
|---|---|
| `search_opportunities` | Search federal opportunities by keyword / agency / set-aside / NAICS / state / value / deadline |
| `market_snapshot_tool` | Set-aside, sector, agency & value overview + urgent deadlines |
| `analyze_solicitation` | **Evidence-backed** small-business fit assessment (insufficient / mismatch / review / potential) + red-flag scan (bonds, turnover, past-performance) |
| `solicitation_review` | **Phase-3 deep review**: fetches full notice + attachments, combines a bidder capability profile with source-linked extraction (instructions, evaluation factors, clauses, amendments) |
| `look_up_naics` | Translate a description into NAICS sectors |
| `look_up_set_aside` | Explain a set-aside (Small Business, 8(a), HUBZone, WOSB, SDVOSBC…) |
| `federal_thresholds` | Micro-purchase, SAT, Miller Act bond, subcontracting-plan thresholds |
| `opportunity_details` | Full record (incl. POC, links, award) + state name for one opportunity — live or sample |
| `opportunity_type` | What a SAM.gov type code means (sources sought, solicitation, J&A…) |

Everything is **deterministic, typed, and honest about its data source**.

---

## Install & run

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest tests/ -q      # 84 tests incl. real MCP stdio integration
.venv/bin/us-gov-mcp            # or: .venv/bin/python -m usgovmcp.server
```

## Connect a client
**Claude Desktop / Claude Code / Cursor** → see [`configs/mcp-config.json`](configs/mcp-config.json)
(canonical example: same JSON works for Claude Desktop and Cursor; for Claude Code,
use `claude mcp add`). Set `PYTHONPATH` to this repo; optionally add a `SAM_GOV_API_KEY`.

---

## Data
- **Default:** a bundled set of **clearly-labeled sample opportunities** so it works and is tested with no key.
- **Live (SAM.gov):** get a **free public API key** from your SAM.gov account → `Account Details → request a public API key`. Set `SAM_GOV_API_KEY`. The provider (`SAMGovProvider`) already talks to `api.sam.gov/opportunities/v2/search` and is unit-tested against the real response shape. Live data is never faked — until a key is set, labeled samples are returned.

---

## Layout
```
us-gov-mcp/
├── usgovmcp/
│   ├── server.py       ← FastMCP server wiring all tools
│   ├── knowledge.py    ← NAICS, set-asides, FAR thresholds, red-flag rules
│   ├── analyzer.py     ← evidence-backed fit assessment + red-flag scan
│   ├── solicit.py      ← bidder capability profile + source-linked extraction (Phase 3)
│   ├── providers.py    ← bundled + SAM.gov live providers
│   ├── models.py       ← typed Opportunity / search params / ProviderResult
│   ├── intel.py        ← market-snapshot aggregation
│   └── sample_data.py  ← labeled demo opportunities
├── configs/
├── scripts/smoke.py          ← CI startup check (fails pipeline on broken server)
├── scripts/secret_scan.sh    ← CI gate: blocks committed credentials
├── cache.py                  ← bounded TTL cache (protects SAM.gov quota)
├── tests/                    ← 84 tests incl. real stdio protocol integration
├── constraints.txt           ← tested/locked dependency set for releases
├── CONTRIBUTING.md SECURITY.md LICENSE CHANGELOG.md
├── pyproject.toml            ← also ruff + mypy config
└── README.md
```

CI runs two jobs: **test** (Python 3.10/3.11/3.12) and **quality** (`ruff`
lint + format check, `mypy`, package build, secret scan).
MIT licensed. Not legal advice — always read the full solicitation before bidding.

---
## Trust & evidence rules
- `analyze_solicitation` never produces a confident fit from missing evidence:
  unknown notices and empty text return `insufficient_information`.
- Provider results are typed (`ProviderResult`): `ok`, `no_matches`,
  `authentication_error`, `rate_limited`, `upstream_error`, `parse_error`,
  `no_key`. Asking for `sam_gov` without a key returns `no_key` — never a silent,
  misleading empty list.
- All data is honestly labeled by source (`bundled_sample` vs `sam_gov`).