matchawards-mcp 0.1.0__tar.gz

matchawards_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/matchawards-mcp
+    permissions:
+      id-token: write   # PyPI trusted publishing (OIDC)
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Tag must equal the package version and both server.json versions
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(python3 -c "import re; print(re.search(r'__version__ = \"([^\"]+)\"', open('src/matchawards_mcp/__init__.py').read())[1])")
+          listing=$(python3 -c "import json; d = json.load(open('server.json')); print(d['version'], d['packages'][0]['version'])")
+          echo "tag=$GITHUB_REF_NAME package=$pkg server.json=$listing"
+          [ "$GITHUB_REF_NAME" = "v$tag" ] && [ "$pkg" = "$tag" ] && [ "$listing" = "$tag $tag" ]
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+
+      - name: Check metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # mcp-publisher login github-oidc
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mcp-publisher (pinned, sha256 from the release's checksums file)
+        env:
+          MCP_PUBLISHER_VERSION: v1.8.1
+          MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+        run: |
+          curl -fsSL -o mcp-publisher.tar.gz "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz"
+          echo "${MCP_PUBLISHER_SHA256}  mcp-publisher.tar.gz" | sha256sum -c -
+          tar -xzf mcp-publisher.tar.gz mcp-publisher
+          chmod +x mcp-publisher
+
+      - name: Log in with GitHub OIDC
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish server.json to the official MCP Registry
+        run: ./mcp-publisher publish

matchawards_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,58 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: pip install -e ".[test]"
+
+      - run: pytest -q
+
+  wheel-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build and check
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Install the wheel in a fresh venv and run the stdio discover handshake
+        run: |
+          python -m venv "$RUNNER_TEMP/smoke"
+          "$RUNNER_TEMP/smoke/bin/pip" install dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/smoke/bin/python" - <<'EOF'
+          import os
+          import anyio
+          from mcp import Client, StdioServerParameters
+
+          async def main():
+              server = StdioServerParameters(command=os.path.join(os.environ["RUNNER_TEMP"], "smoke/bin/matchawards-mcp"))
+              async with Client(server) as client:
+                  names = [t.name for t in (await client.list_tools()).tools]
+                  assert client.protocol_version == "2026-07-28", client.protocol_version
+                  assert len(names) == 6, names
+                  print("smoke ok:", client.server_info.version, names)
+
+          anyio.run(main)
+          EOF

matchawards_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

matchawards_mcp-0.1.0/Dockerfile

@@ -0,0 +1,7 @@
+# The server speaks MCP over stdio, so run it with -i: docker run -i --rm matchawards-mcp
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir .
+CMD ["matchawards-mcp"]

matchawards_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MatchAwards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matchawards_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: matchawards-mcp
+Version: 0.1.0
+Summary: MCP server for MatchAwards: search US government contracts, grants and jobs from matchawards.com.
+Project-URL: Homepage, https://matchawards.com
+Project-URL: Repository, https://github.com/matchawards/matchawards-mcp
+Project-URL: Issues, https://github.com/matchawards/matchawards-mcp/issues
+Author: MatchAwards
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,claude,cursor,federal-contracts,government-contracts,grants,jobs,matchawards,mcp,model-context-protocol,naics,sam-gov
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]==2.3.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MatchAwards MCP server
+
+<!-- mcp-name: io.github.matchawards/matchawards-mcp -->
+
+*MatchAwards gives AI agents direct access to continuously updated government and business contracts, grants, jobs, awards and collaboration opportunities.*
+
+This is the [Model Context Protocol](https://modelcontextprotocol.io) server for [MatchAwards](https://matchawards.com). It lets Claude, Cursor, VS Code and other MCP clients search US government contract opportunities, grants and jobs. It only reads data, and it needs no account and no API key.
+
+## Tools
+
+| Tool | What it returns | Example prompt |
+|---|---|---|
+| `search_contracts` | Federal and state contract opportunities. Filters: NAICS, state, keyword, set-aside, federal or state only, posted within N days, open only, paging. | "Find open roofing contracts in Virginia posted in the last week." |
+| `search_grants` | Federal grant and funding opportunities. Filters: NAICS, keyword, posted within N days, open only, paging (grant notices carry no state). | "Are there open broadband grants?" |
+| `search_jobs` | Job postings from the last 30 days. Filters: NAICS, state, keyword, posted within N days, paging. | "Show electrician jobs in Texas from the last 7 days." |
+| `search_by_naics` | The newest opportunities for up to 10 NAICS codes, of one type: contract, federal, state, grant or job. | "What is new for NAICS 541511 and 541512 at the federal level?" |
+| `get_opportunity` | The full record of one opportunity: description, deadline, agency and contacts (name and title). | "Tell me more about the second result." |
+| `find_contacts` | Only the published points of contact for one opportunity. | "Who do I contact about that solicitation?" |
+
+Every result carries a `url` on matchawards.com, and the server asks the model to show it to you as a link.
+
+## Install
+
+The server runs with [`uvx`](https://docs.astral.sh/uv/), which comes with uv.
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "matchawards": {
+      "command": "uvx",
+      "args": ["matchawards-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add matchawards -- uvx matchawards-mcp
+```
+
+### Cursor
+
+Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "matchawards": {
+      "command": "uvx",
+      "args": ["matchawards-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add this to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "matchawards": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["matchawards-mcp"]
+    }
+  }
+}
+```
+
+### Other clients
+
+Any MCP client that can start a stdio server works. The command is `uvx matchawards-mcp`.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MATCHAWARDS_API_BASE` | `https://matchawards.com` | API base URL. Change it only for development. |
+
+## Data
+
+The data is US federal and state contract opportunities, grants and jobs from [matchawards.com](https://matchawards.com). Only public posts are returned, and each result links back to its page on matchawards.com.
+
+- Contract and grant searches return open items by default: a response deadline of today or later, US Eastern. An item with no deadline counts as closed.
+- Job search covers the last 30 days.
+- Results come newest first. When `has_more` is true, the model can ask for the next page with `cursor`.
+- If the first request of a search fails, the tool returns an error. If a later page fails, the tool returns the rows it already has, with a `warning` that says why it stopped.
+- The API is rate-limited per IP: 60 requests per minute, plus a burst limit of 20 requests per 5 seconds. One search call can use up to three requests when the filters are narrow and results are sparse. When the limit is reached, the tool returns an error that tells the model how many seconds to wait.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/pytest
+```
+
+The tests make no network calls.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

matchawards_mcp-0.1.0/README.md

@@ -0,0 +1,110 @@
+# MatchAwards MCP server
+
+<!-- mcp-name: io.github.matchawards/matchawards-mcp -->
+
+*MatchAwards gives AI agents direct access to continuously updated government and business contracts, grants, jobs, awards and collaboration opportunities.*
+
+This is the [Model Context Protocol](https://modelcontextprotocol.io) server for [MatchAwards](https://matchawards.com). It lets Claude, Cursor, VS Code and other MCP clients search US government contract opportunities, grants and jobs. It only reads data, and it needs no account and no API key.
+
+## Tools
+
+| Tool | What it returns | Example prompt |
+|---|---|---|
+| `search_contracts` | Federal and state contract opportunities. Filters: NAICS, state, keyword, set-aside, federal or state only, posted within N days, open only, paging. | "Find open roofing contracts in Virginia posted in the last week." |
+| `search_grants` | Federal grant and funding opportunities. Filters: NAICS, keyword, posted within N days, open only, paging (grant notices carry no state). | "Are there open broadband grants?" |
+| `search_jobs` | Job postings from the last 30 days. Filters: NAICS, state, keyword, posted within N days, paging. | "Show electrician jobs in Texas from the last 7 days." |
+| `search_by_naics` | The newest opportunities for up to 10 NAICS codes, of one type: contract, federal, state, grant or job. | "What is new for NAICS 541511 and 541512 at the federal level?" |
+| `get_opportunity` | The full record of one opportunity: description, deadline, agency and contacts (name and title). | "Tell me more about the second result." |
+| `find_contacts` | Only the published points of contact for one opportunity. | "Who do I contact about that solicitation?" |
+
+Every result carries a `url` on matchawards.com, and the server asks the model to show it to you as a link.
+
+## Install
+
+The server runs with [`uvx`](https://docs.astral.sh/uv/), which comes with uv.
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "matchawards": {
+      "command": "uvx",
+      "args": ["matchawards-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add matchawards -- uvx matchawards-mcp
+```
+
+### Cursor
+
+Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "matchawards": {
+      "command": "uvx",
+      "args": ["matchawards-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add this to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "matchawards": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["matchawards-mcp"]
+    }
+  }
+}
+```
+
+### Other clients
+
+Any MCP client that can start a stdio server works. The command is `uvx matchawards-mcp`.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MATCHAWARDS_API_BASE` | `https://matchawards.com` | API base URL. Change it only for development. |
+
+## Data
+
+The data is US federal and state contract opportunities, grants and jobs from [matchawards.com](https://matchawards.com). Only public posts are returned, and each result links back to its page on matchawards.com.
+
+- Contract and grant searches return open items by default: a response deadline of today or later, US Eastern. An item with no deadline counts as closed.
+- Job search covers the last 30 days.
+- Results come newest first. When `has_more` is true, the model can ask for the next page with `cursor`.
+- If the first request of a search fails, the tool returns an error. If a later page fails, the tool returns the rows it already has, with a `warning` that says why it stopped.
+- The API is rate-limited per IP: 60 requests per minute, plus a burst limit of 20 requests per 5 seconds. One search call can use up to three requests when the filters are narrow and results are sparse. When the limit is reached, the tool returns an error that tells the model how many seconds to wait.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/pytest
+```
+
+The tests make no network calls.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

matchawards_mcp-0.1.0/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["matchawards"]
+}

matchawards_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "matchawards-mcp"
+dynamic = ["version"]
+description = "MCP server for MatchAwards: search US government contracts, grants and jobs from matchawards.com."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "MatchAwards" }]
+keywords = [
+  "mcp", "model-context-protocol", "ai-agent", "claude", "cursor",
+  "matchawards", "government-contracts", "federal-contracts", "grants",
+  "jobs", "sam-gov", "naics",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "mcp[cli]==2.3.0",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://matchawards.com"
+Repository = "https://github.com/matchawards/matchawards-mcp"
+Issues = "https://github.com/matchawards/matchawards-mcp/issues"
+
+[project.scripts]
+matchawards-mcp = "matchawards_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/matchawards_mcp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matchawards_mcp"]

matchawards_mcp-0.1.0/server.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.matchawards/matchawards-mcp",
+  "title": "MatchAwards",
+  "description": "Search US government contracts, grants and jobs from matchawards.com. Read-only, no key.",
+  "version": "0.1.0",
+  "websiteUrl": "https://matchawards.com",
+  "repository": {
+    "url": "https://github.com/matchawards/matchawards-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "matchawards-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "MATCHAWARDS_API_BASE",
+          "description": "Base URL of the MatchAwards API. Leave unset to use https://matchawards.com; set only for development.",
+          "isRequired": false,
+          "isSecret": false,
+          "default": "https://matchawards.com"
+        }
+      ]
+    }
+  ]
+}

matchawards_mcp-0.1.0/smithery.yaml

@@ -0,0 +1,8 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties: {}
+  commandFunction: |-
+    () => ({ command: "uvx", args: ["matchawards-mcp"] })
+  exampleConfig: {}

matchawards_mcp-0.1.0/src/matchawards_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MatchAwards MCP server: US government contracts, grants and jobs for AI agents."""
+
+__version__ = "0.1.0"

matchawards_mcp-0.1.0/src/matchawards_mcp/server.py

@@ -0,0 +1,330 @@
+"""MatchAwards MCP server: read-only search over the public matchawards.com API.
+
+Six tools, no auth, no state. Each call is a GET to `{MATCHAWARDS_API_BASE}/api/public/v1/opportunities`
+(a search tool may follow the cursor for up to MAX_PAGES requests) or to `.../opportunities/{id}`.
+"""
+
+import inspect
+import os
+from typing import Annotated, Any, Literal
+
+import httpx
+from mcp.server.caching import CacheHint
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from . import __version__
+
+API_BASE = os.environ.get("MATCHAWARDS_API_BASE", "https://matchawards.com").rstrip("/")
+USER_AGENT = f"matchawards-mcp/{__version__} (+https://github.com/matchawards/matchawards-mcp)"
+TIMEOUT_S = 20.0
+SEARCH_PATH = "/api/public/v1/opportunities"
+MAX_PAGES = 3  # API requests one search tool call may make while filling `limit`
+
+LINK_RULE = (
+    "Show each item's url to the user verbatim as a markdown link, [title](url); "
+    "it opens the full posting on matchawards.com."
+)
+INSTRUCTIONS = (
+    "Search US government contract opportunities (federal and state), grants and jobs from matchawards.com. "
+    f"Read-only. Every result row has a matchawards.com `url`. {LINK_RULE}"
+)
+
+# Tests swap this for an httpx.AsyncClient on a MockTransport.
+client = httpx.AsyncClient(
+    base_url=API_BASE,
+    headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+    timeout=TIMEOUT_S,
+)
+
+mcp = MCPServer(
+    name="matchawards",
+    title="MatchAwards",
+    instructions=INSTRUCTIONS,
+    website_url="https://matchawards.com",
+    version=__version__,
+    # The tool list is static: let clients cache it for a day, shared across users.
+    cache_hints={"tools/list": CacheHint(ttl_ms=86_400_000, scope="public")},
+    # No server-initiated notifications, so do not serve subscriptions/listen.
+    subscriptions=False,
+)
+
+READ_ONLY = ToolAnnotations(
+    read_only_hint=True, destructive_hint=False, idempotent_hint=True, open_world_hint=True
+)
+
+
+def _tool(fn):
+    """Register a read-only tool; its cleaned docstring is the description the model reads."""
+    return mcp.tool(annotations=READ_ONLY, description=inspect.cleandoc(fn.__doc__))(fn)
+
+
+# Optional filters are Annotated[X | None, Field(...)] so the description sits at the top level of
+# the JSON schema while the constraint still applies to the non-null value.
+_NAICS = Field(
+    pattern=r"^\s*\d{6}(\s*,\s*\d{6}){0,9}\s*$",
+    description="Up to 10 six-digit NAICS codes, comma-separated, e.g. '236220' or '541511,541512'. "
+    "Unknown codes are ignored.",
+)
+Naics = Annotated[str, _NAICS]
+OptNaics = Annotated[str | None, _NAICS]
+State = Annotated[
+    str | None,
+    Field(pattern=r"^[A-Za-z]{2}$", description="Two-letter US state code, e.g. 'VA'. Many federal notices "
+          "have no state, so this filter skips them."),
+]
+Keyword = Annotated[
+    str | None, Field(min_length=2, max_length=100, description="2 to 100 characters matched against the title only.")
+]
+SetAside = Annotated[str | None, Field(description="Set-aside code, e.g. 'SBA' or 'SDVOSBC'. Federal contracts only.")]
+PostedWithin = Annotated[
+    int | None, Field(ge=1, le=180, description="Only items posted in the last N days, 1 to 180 (default 180).")
+]
+JobsPostedWithin = Annotated[int, Field(ge=1, le=30, description="Only jobs posted in the last N days, 1 to 30.")]
+Open = Annotated[
+    bool | None,
+    Field(description="true (the default): only items with a response deadline of today or later, US Eastern; "
+          "an item with no deadline counts as closed. false: include closed ones."),
+]
+Limit = Annotated[int, Field(ge=1, le=50, description="Number of results to return, 1 to 50.")]
+Cursor = Annotated[
+    str | None,
+    Field(description="next_cursor from the previous response. Pass it with the same filters to get the next page."),
+]
+OppId = Annotated[
+    str, Field(pattern=r"^[A-Za-z0-9_-]{1,128}$", description="The id field of a search result.")
+]
+NaicsType = Annotated[
+    Literal["contract", "federal", "state", "grant", "job"],
+    Field(description="contract = federal and state contracts; federal or state = one level only; grant; job."),
+]
+
+
+def _error_message(r: httpx.Response) -> str:
+    """Turn an API error response ({error, parameter?} JSON) into advice the model can act on."""
+    try:
+        body = r.json()
+    except ValueError:
+        body = None
+    body = body if isinstance(body, dict) else {}
+    error = body.get("message") or body.get("error") or r.text.strip()[:200] or r.reason_phrase
+    if r.status_code == 429:
+        wait = r.headers.get("Retry-After") or body.get("retry_after") or 60
+        return (
+            f"MatchAwards rate limit reached (per IP: 60 requests per minute, 20 per 5 seconds). "
+            f"Wait {wait} seconds, then retry."
+        )
+    if body.get("error") == "grants_unavailable":
+        return "Grant search is temporarily unavailable on MatchAwards. Try again later; contracts and jobs still work."
+    if r.status_code >= 500:
+        return f"MatchAwards server error (HTTP {r.status_code}). It is temporary; retry in a minute."
+    if r.status_code == 400 and body.get("parameter"):
+        return f"MatchAwards rejected the parameter '{body['parameter']}': {error}. Fix it and call again."
+    if r.status_code == 404:
+        return f"Not found on MatchAwards ({error}). Use an id from a search result."
+    return f"MatchAwards rejected the request (HTTP {r.status_code}): {error}"
+
+
+async def _get(path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    """GET one API path; turn every failure into a ToolError the model can act on."""
+    query = {k: v for k, v in (params or {}).items() if v is not None and v != ""}  # "" = unset, e.g. cursor=""
+    try:
+        r = await client.get(path, params=query)
+    except httpx.TimeoutException:
+        raise ToolError(
+            f"MatchAwards did not answer within {TIMEOUT_S:.0f} seconds. Retry once; if it fails again, "
+            "narrow the search (fewer NAICS codes, a shorter posted_within_days) or try later."
+        ) from None
+    except httpx.RequestError as e:
+        raise ToolError(
+            f"Could not reach MatchAwards at {API_BASE} ({type(e).__name__}). Check the network and retry later."
+        ) from None
+    if r.status_code >= 400:
+        raise ToolError(_error_message(r))
+    try:
+        data = r.json()
+    except ValueError:
+        data = None
+    if not isinstance(data, dict):
+        raise ToolError(
+            f"MatchAwards returned an unexpected response (HTTP {r.status_code}, not a JSON object). Retry later."
+        )
+    return data
+
+
+async def _get_one(id: str) -> dict[str, Any]:
+    """One opportunity: the API answers {as_of, result: {row..., description, contacts}}; return the row with as_of."""
+    data = await _get(f"{SEARCH_PATH}/{id}")
+    result = data.get("result")
+    if not isinstance(result, dict):
+        raise ToolError("MatchAwards returned an unexpected API response (no result object).")
+    return {**result, "as_of": data.get("as_of")}
+
+
+async def _search(type_: str, limit: int = 20, keyword: str | None = None, **filters: Any) -> dict[str, Any]:
+    """Collect up to `limit` unique rows. A sparse filter can return a short page with has_more, so
+    follow next_cursor with the same filters, for at most MAX_PAGES requests."""
+    if filters.get("naics"):
+        filters["naics"] = ",".join(c.strip() for c in filters["naics"].split(","))
+    if filters.get("state"):
+        filters["state"] = filters["state"].upper()
+    params = {"type": type_, "q": keyword, **filters}
+    rows: dict[Any, dict[str, Any]] = {}
+    page: dict[str, Any] = {}
+    as_of = warning = None
+    for _ in range(MAX_PAGES):
+        try:
+            # Ask only for what is still missing, so no row is read past the cursor and then dropped.
+            next_page = await _get(SEARCH_PATH, {**params, "limit": limit - len(rows)})
+            results = next_page.get("results")
+            if not isinstance(results, list) or not all(isinstance(r, dict) for r in results):
+                raise ToolError("MatchAwards returned an unexpected API response (results is not a list of objects).")
+        except ToolError as e:
+            if not page:
+                raise  # first page: nothing to return, so the call fails
+            # Follow-up page: keep what we have; the last good page's next_cursor still points at the rest.
+            warning = f"Stopped after {len(rows)} rows: {e} More results may exist; call again with next_cursor."
+            break
+        page = next_page
+        as_of = as_of or page.get("as_of")
+        for row in results:
+            rows.setdefault(row.get("id"), row)
+        if len(rows) >= limit or not (page.get("has_more") and page.get("next_cursor")):
+            break
+        params["cursor"] = page["next_cursor"]
+    out = {
+        "as_of": as_of,
+        "results": list(rows.values()),
+        "has_more": bool(page.get("has_more")),
+        "next_cursor": page.get("next_cursor"),
+        "note": LINK_RULE,
+    }
+    return {**out, "warning": warning} if warning else out
+
+
+@_tool
+async def search_contracts(
+    naics: OptNaics = None,
+    state: State = None,
+    keyword: Keyword = None,
+    set_aside: SetAside = None,
+    type: Annotated[
+        Literal["federal", "state"] | None,
+        Field(description="Narrow to federal or to state contracts. Leave empty for both."),
+    ] = None,
+    posted_within_days: PostedWithin = None,
+    open: Open = None,
+    limit: Limit = 20,
+    cursor: Cursor = None,
+) -> dict[str, Any]:
+    """Search US federal and state government contract opportunities (bids, RFPs, solicitations).
+
+    Use this when the user wants contracts to bid on. Returns {as_of, results, has_more, next_cursor};
+    each result has id, type, title, agency, office, naics {code, title}, set_aside, state, city,
+    posted_at, response_deadline, url (matchawards.com), sam_url and solicitation_number.
+    Filters: naics, state, keyword, set_aside (federal only), type (federal or state), posted_within_days,
+    open (default true), limit, cursor. If has_more is true, call again with cursor=next_cursor and the
+    same filters. Example: naics="238160", state="VA", keyword="roof".
+    For grants use search_grants, for jobs search_jobs.
+    """
+    return await _search(
+        type or "contract", naics=naics, state=state, keyword=keyword, set_aside=set_aside,
+        posted_within_days=posted_within_days, open=open, limit=limit, cursor=cursor,
+    )
+
+
+@_tool
+async def search_grants(
+    naics: OptNaics = None,
+    keyword: Keyword = None,
+    posted_within_days: PostedWithin = None,
+    open: Open = None,
+    limit: Limit = 20,
+    cursor: Cursor = None,
+) -> dict[str, Any]:
+    """Search US federal grant and funding opportunities.
+
+    Use this when the user wants grants or funding, not contracts. Returns {as_of, results, has_more,
+    next_cursor}; each result has id, title, agency, naics, posted_at, response_deadline and a matchawards.com
+    url. Filters: naics, keyword, posted_within_days, open (default true: open grants of any age), limit,
+    cursor. Grant notices carry no state, so there is no state filter. If has_more is true, call again with
+    cursor=next_cursor and the same filters. Example: keyword="broadband" or naics="541715".
+    """
+    return await _search(
+        "grant", naics=naics, keyword=keyword, posted_within_days=posted_within_days, open=open, limit=limit,
+        cursor=cursor,
+    )
+
+
+@_tool
+async def search_jobs(
+    naics: OptNaics = None,
+    state: State = None,
+    keyword: Keyword = None,
+    posted_within_days: JobsPostedWithin = 30,
+    limit: Limit = 20,
+    cursor: Cursor = None,
+) -> dict[str, Any]:
+    """Search job postings from the last 30 days listed on MatchAwards.
+
+    Use this when the user is looking for a job or for hiring signals, not for contracts or grants.
+    Returns {as_of, results, has_more, next_cursor}; each result has id, title, agency (the employer),
+    state, city, posted_at and a matchawards.com url; other fields are null. Filters: naics, state,
+    keyword, posted_within_days (up to 30), limit, cursor. If has_more is true, call again with
+    cursor=next_cursor and the same filters. Example: keyword="electrician", state="TX", posted_within_days=7.
+    """
+    return await _search(
+        "job", naics=naics, state=state, keyword=keyword,
+        posted_within_days=posted_within_days, limit=limit, cursor=cursor,
+    )
+
+
+@_tool
+async def search_by_naics(naics: Naics, type: NaicsType = "contract", cursor: Cursor = None) -> dict[str, Any]:
+    """List the newest opportunities for one or more NAICS industry codes.
+
+    Use this when the user gives NAICS codes and nothing else. Returns up to 20 results, {as_of, results,
+    has_more, next_cursor}, each with a matchawards.com url. Filters: naics (required), type (contract,
+    federal, state, grant or job), cursor (next_cursor of the previous call, same naics and type). For
+    keyword, state or other filters use search_contracts, search_grants or search_jobs.
+    Example: naics="541511,541512", type="federal".
+    """
+    return await _search(type, naics=naics, cursor=cursor)
+
+
+@_tool
+async def get_opportunity(id: OppId) -> dict[str, Any]:
+    """Get the full record of one opportunity by its id from a search result.
+
+    Use this when the user wants details on one result. Returns the search row plus description
+    (up to 2000 characters) and contacts [{name, title}], with the matchawards.com url. Example: id="abc123".
+    """
+    return {**await _get_one(id), "note": LINK_RULE}
+
+
+@_tool
+async def find_contacts(id: OppId) -> dict[str, Any]:
+    """Get only the published points of contact for one opportunity by its id.
+
+    Use this when the user asks who to contact about a result. Returns {id, title, url, contacts}, where
+    contacts is [{name, title}] as the public matchawards.com page shows them; an empty list means none
+    are published. Example: id="abc123".
+    """
+    data = await _get_one(id)
+    return {
+        "id": data.get("id", id),
+        "title": data.get("title"),
+        "url": data.get("url"),
+        "contacts": data.get("contacts") or [],
+    }
+
+
+def main() -> None:
+    """Console entry point. v0.1.0 serves stdio only.
+
+    The tools live on the module-level `mcp`, so a later `--http` flag can serve the same set with
+    `mcp.streamable_http_app(stateless_http=True, json_response=True)` from here.
+    """
+    mcp.run(transport="stdio")

matchawards_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,264 @@
+import json
+import sys
+from importlib.metadata import version
+from pathlib import Path
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from mcp import Client, StdioServerParameters
+from mcp.server.mcpserver.exceptions import ToolError
+
+from matchawards_mcp import __version__, server
+
+ROOT = Path(__file__).resolve().parents[1]
+PATH = "/api/public/v1/opportunities"
+TOOLS = ["search_contracts", "search_grants", "search_jobs", "search_by_naics", "get_opportunity", "find_contacts"]
+NOTE = server.LINK_RULE
+
+
+def row(i):
+    return {"id": str(i), "type": "contract", "title": f"Notice {i}", "url": f"https://matchawards.com/a/posts/{i}"}
+
+
+def page(ids, has_more=False, cursor=None):
+    return {"as_of": "2026-10-07T12:00:00Z", "results": [row(i) for i in ids], "has_more": has_more,
+            "next_cursor": cursor}
+
+
+DETAIL = {**row(7), "description": "Replace the roof.", "contacts": [{"name": "Jo Smith", "title": "Contracting Officer"}]}
+
+
+@pytest.fixture
+def anyio_backend():
+    return "asyncio"
+
+
+@pytest.fixture
+def api(monkeypatch):
+    """Point the server's HTTP client at a mock. api.replies is a queue; the last reply repeats."""
+    # The default reply suits both shapes: a search page and a single opportunity ({result: ...}).
+    api = SimpleNamespace(requests=[], replies=[lambda req: httpx.Response(200, json={**page([1]), "result": row(1)})])
+
+    def handler(req):
+        api.requests.append(req)
+        reply = api.replies.pop(0) if len(api.replies) > 1 else api.replies[0]
+        return reply(req)
+
+    monkeypatch.setattr(server, "client", httpx.AsyncClient(
+        transport=httpx.MockTransport(handler), base_url="https://api.test",
+        headers=dict(server.client.headers),
+    ))
+    return api
+
+
+def ok(body):
+    return lambda req: httpx.Response(200, json=body)
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("call, path, params", [
+    (lambda: server.search_contracts(), PATH, {"type": "contract", "limit": "20"}),
+    (lambda: server.search_contracts(
+        naics="236220, 238210", state="va", keyword="roof", set_aside="SBA", type="federal",
+        posted_within_days=7, open=False, limit=5, cursor="abc=",
+    ), PATH, {"type": "federal", "naics": "236220,238210", "state": "VA", "q": "roof", "set_aside": "SBA",
+              "posted_within_days": "7", "open": "false", "limit": "5", "cursor": "abc="}),
+    (lambda: server.search_grants(keyword="broadband", naics="541715", open=True),
+     PATH, {"type": "grant", "naics": "541715", "q": "broadband", "open": "true", "limit": "20"}),
+    (lambda: server.search_by_naics("541715", type="grant"),
+     PATH, {"type": "grant", "naics": "541715", "limit": "20"}),
+    (lambda: server.search_jobs(), PATH, {"type": "job", "posted_within_days": "30", "limit": "20"}),
+    (lambda: server.search_jobs(keyword="electrician", posted_within_days=7),
+     PATH, {"type": "job", "q": "electrician", "posted_within_days": "7", "limit": "20"}),
+    (lambda: server.search_contracts(cursor="", set_aside=""), PATH, {"type": "contract", "limit": "20"}),
+    (lambda: server.search_by_naics("541511", cursor=""), PATH, {"type": "contract", "naics": "541511", "limit": "20"}),
+    (lambda: server.search_by_naics("541511,541512", type="federal", cursor="c1"),
+     PATH, {"type": "federal", "naics": "541511,541512", "limit": "20", "cursor": "c1"}),
+    (lambda: server.get_opportunity("abc123"), f"{PATH}/abc123", {}),
+    (lambda: server.find_contacts("abc-123_x"), f"{PATH}/abc-123_x", {}),
+])
+async def test_query_building(api, call, path, params):
+    await call()
+    [req] = api.requests
+    assert req.method == "GET"
+    assert req.url.path == path
+    assert dict(req.url.params) == params
+    assert req.headers["User-Agent"] == f"matchawards-mcp/{__version__} (+https://github.com/matchawards/matchawards-mcp)"
+
+
+@pytest.mark.anyio
+async def test_search_returns_rows_cursor_and_link_note(api):
+    api.replies = [ok(page([1, 2], has_more=True, cursor="c1"))]
+    assert await server.search_contracts(limit=2) == {**page([1, 2], has_more=True, cursor="c1"), "note": NOTE}
+
+
+@pytest.mark.anyio
+async def test_sparse_pages_are_followed_with_same_filters_and_deduplicated(api):
+    api.replies = [
+        ok(page([1, 2], has_more=True, cursor="c1")),
+        ok(page([2, 3], has_more=True, cursor="c2")),  # 2 repeats across pages
+        ok(page([4, 5], has_more=True, cursor="c3")),
+    ]
+    out = await server.search_contracts(state="TX", limit=5)
+    assert [r["id"] for r in out["results"]] == ["1", "2", "3", "4", "5"]
+    assert (out["has_more"], out["next_cursor"]) == (True, "c3")
+    sent = [dict(r.url.params) for r in api.requests]
+    assert [(p.get("cursor"), p["limit"]) for p in sent] == [(None, "5"), ("c1", "3"), ("c2", "2")]
+    assert all(p["state"] == "TX" and p["type"] == "contract" for p in sent)
+
+
+@pytest.mark.anyio
+async def test_following_stops_after_three_requests(api):
+    api.replies = [ok(page([], has_more=True, cursor="c"))]
+    out = await server.search_grants(limit=10)
+    assert len(api.requests) == 3
+    assert (out["results"], out["has_more"], out["next_cursor"]) == ([], True, "c")
+
+
+@pytest.mark.anyio
+async def test_following_stops_when_the_api_has_no_more(api):
+    api.replies = [ok(page([1], has_more=False))]
+    out = await server.search_jobs()
+    assert len(api.requests) == 1
+    assert (out["has_more"], out["next_cursor"]) == (False, None)
+
+
+@pytest.mark.anyio
+async def test_failed_follow_up_keeps_the_rows_already_collected(api):
+    api.replies = [ok(page([1], has_more=True, cursor="c1")), lambda req: httpx.Response(429, headers={"Retry-After": "5"})]
+    out = await server.search_contracts(limit=5)
+    assert [r["id"] for r in out["results"]] == ["1"]
+    assert (out["has_more"], out["next_cursor"]) == (True, "c1")
+    assert out["warning"].startswith("Stopped after 1 rows: MatchAwards rate limit reached")
+    assert "Wait 5 seconds" in out["warning"] and out["warning"].endswith("call again with next_cursor.")
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("body", [
+    {"results": ["1", "2"], "has_more": False},
+    {"results": {"id": "1"}, "has_more": False},
+    {"has_more": False},
+])
+async def test_malformed_results_are_a_tool_error(api, body):
+    api.replies = [ok(body)]
+    with pytest.raises(ToolError, match="unexpected API response"):
+        await server.search_contracts()
+
+
+@pytest.mark.anyio
+async def test_malformed_follow_up_page_keeps_rows_with_warning(api):
+    api.replies = [ok(page([1], has_more=True, cursor="c1")), ok({"results": [None], "has_more": False})]
+    out = await server.search_contracts(limit=5)
+    assert [r["id"] for r in out["results"]] == ["1"]
+    assert "unexpected API response" in out["warning"]
+
+
+@pytest.mark.anyio
+async def test_complete_search_has_no_warning(api):
+    api.replies = [ok(page([1, 2], has_more=True, cursor="c1"))]
+    assert "warning" not in await server.search_contracts(limit=2)
+
+
+@pytest.mark.anyio
+async def test_get_opportunity_passes_json_through_with_link_note(api):
+    api.replies = [ok({"as_of": "2026-10-07T12:00:00Z", "result": DETAIL})]
+    assert await server.get_opportunity("7") == {**DETAIL, "as_of": "2026-10-07T12:00:00Z", "note": NOTE}
+
+
+@pytest.mark.anyio
+async def test_find_contacts_returns_only_id_title_url_and_contacts(api):
+    api.replies = [ok({"as_of": "x", "result": DETAIL})]
+    assert await server.find_contacts("7") == {
+        "id": "7", "title": "Notice 7", "url": "https://matchawards.com/a/posts/7", "contacts": DETAIL["contacts"],
+    }
+    api.replies = [ok({"as_of": "x", "result": row(8)})]
+    assert (await server.find_contacts("8"))["contacts"] == []
+    api.replies = [ok(row(9))]  # old top-level shape: not accepted
+    with pytest.raises(ToolError, match="no result object"):
+        await server.find_contacts("9")
+
+
+def _raise(exc_type):
+    def reply(req):
+        raise exc_type("boom", request=req)
+    return reply
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("reply, message", [
+    (lambda req: httpx.Response(429, headers={"Retry-After": "30"}, json={"error": "rate_limited", "retry_after": 30}),
+     "Wait 30 seconds"),
+    (lambda req: httpx.Response(429, json={"error": "rate_limited", "retry_after": 12}), "Wait 12 seconds"),
+    (lambda req: httpx.Response(429), "Wait 60 seconds"),
+    (lambda req: httpx.Response(400, json={"error": "unsupported_filter", "parameter": "set_aside",
+                                           "message": "set_aside is only for contract or federal"}),
+     "parameter 'set_aside': set_aside is only for contract or federal"),
+    (lambda req: httpx.Response(400, json={"error": "invalid_parameter", "parameter": "state"}),
+     "parameter 'state': invalid_parameter"),
+    (lambda req: httpx.Response(404, json={"error": "not_found"}), "Not found on MatchAwards"),
+    (lambda req: httpx.Response(503, json={"error": "grants_unavailable", "message": "open grant list is stale"}),
+     "Grant search is temporarily unavailable"),
+    (lambda req: httpx.Response(500, json={"error": "internal_error"}), "server error \\(HTTP 500\\)"),
+    (lambda req: httpx.Response(502, text="<html>bad gateway</html>"), "server error \\(HTTP 502\\)"),
+    (_raise(httpx.ReadTimeout), "did not answer within 20 seconds"),
+    (_raise(httpx.ConnectError), "Could not reach MatchAwards"),
+    (lambda req: httpx.Response(200, text="<html>maintenance</html>"), "not a JSON object"),
+    (lambda req: httpx.Response(200, json=[1, 2]), "not a JSON object"),
+])
+async def test_http_failures_become_tool_errors(api, reply, message):
+    api.replies = [reply]
+    with pytest.raises(ToolError, match=message):
+        await server.search_contracts()
+    with pytest.raises(ToolError, match=message):
+        await server.get_opportunity("7")
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("tool, args", [
+    ("search_contracts", {"naics": "12345"}),
+    ("search_contracts", {"naics": ",".join(["541511"] * 11)}),
+    ("search_contracts", {"type": "grant"}),
+    ("search_contracts", {"posted_within_days": 181}),
+    ("search_grants", {"keyword": "a"}),
+    ("search_jobs", {"posted_within_days": 31}),
+    ("search_jobs", {"limit": 0}),
+    ("search_jobs", {"limit": 51}),
+    ("search_by_naics", {"naics": "541511", "type": "award"}),
+    ("get_opportunity", {"id": "../admin"}),
+    ("find_contacts", {"id": ""}),
+])
+async def test_bad_input_is_rejected_before_any_request(api, tool, args):
+    with pytest.raises(ToolError):
+        await server.mcp.call_tool(tool, args)
+    assert api.requests == []
+
+
+def test_version_is_the_same_everywhere():
+    listing = json.loads((ROOT / "server.json").read_text())
+    assert version("matchawards-mcp") == __version__  # pyproject reads it from __init__
+    assert listing["version"] == listing["packages"][0]["version"] == __version__
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("mode", ["auto", "legacy"])  # auto = 2026-07-28 server/discover; legacy = initialize
+async def test_stdio_handshake(mode):
+    params = StdioServerParameters(
+        command=sys.executable,
+        args=["-c", "from matchawards_mcp.server import main; main()"],
+        env={"MATCHAWARDS_API_BASE": "http://127.0.0.1:9"},  # never reached: only a bad-input call is made
+    )
+    async with Client(params, mode=mode) as client:
+        assert (client.server_info.name, client.server_info.version) == ("matchawards", __version__)
+        assert client.instructions == server.INSTRUCTIONS
+        if mode == "auto":
+            assert client.protocol_version == "2026-07-28"
+        listed = await client.list_tools()
+        assert [t.name for t in listed.tools] == TOOLS
+        for t in listed.tools:
+            a = t.annotations
+            assert (a.read_only_hint, a.destructive_hint, a.idempotent_hint, a.open_world_hint) == (True, False, True, True)
+        if mode == "auto":
+            assert (listed.ttl_ms, listed.cache_scope) == (86_400_000, "public")
+        bad = await client.call_tool("search_contracts", {"naics": "12"})
+        assert bad.is_error