Release 2026-09-03: FastMCP 4, MCP 2026-07-28 protocol, verified examples, OCR docs

USPTO Final Petition Decisions MCP server: petition search by application, art unit and criteria, petition details, document content and downloads. Example application 17896175 (no petitions) replaced with 17414168; the accepted identifier forms now match the validator (digits and slash only).

Updated to FastMCP 4.0.1 on the MCP Python SDK 2.x, speaking the 2026-07-28 MCP
protocol revision (MCP Apps now import from fastmcp.apps; a compat shim restores
defer_loading on the wire).

Security and robustness pass from the 2026-09-03 review: INTERNAL_AUTH_SECRET
rotation overlap window with per-purpose derived keys, bounded request bodies,
archives and PDF buffers, USPTO-authored text escaped before it reaches the
view HTML, response-size guard with paging markers on every tool, shared
cross-process USPTO rate limiter, health checks that can actually fail.

Documentation refresh: every example application, patent and proceeding number
verified live against the USPTO API and rewritten in the form the identifier
resolver expects; stale tool counts, env-var tables and response shapes fixed.
Removed the cost and spend wording around OCR; the extraction tiers are now
described by capability (native text layer first, OCR for scanned pages) and a
self-hosted Docling backend can be configured via DOCLING_SERVE_URL. Secrets and
prompt-injection baselines regenerated.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CeSWJpSaEHe9Cx66xzahVV

Author: john-walkoe

.env.example

@@ -1,13 +1,41 @@
 
+# =============================================================================
+# Core configuration
+# =============================================================================
+# USPTO_API_KEY is the only REQUIRED value. Get one (free) from
+# https://data.uspto.gov/myodp/ . On Windows the setup script stores it with
+# DPAPI encryption instead of a plaintext .env; see API_KEY_GUIDE.md.
+# USPTO_API_KEY=
+
+# Document extraction reads the PDF's native text layer with pypdf first.
+# Scanned pages need an OCR backend; either of the two below is sufficient,
+# and neither is required for text-layer PDFs.
+#   - Mistral OCR (hosted, metered):
+# MISTRAL_API_KEY=
+# MISTRAL_OCR_MODEL=mistral-ocr-latest   # pin a dated slug for determinism
+#   - Docling (self-hosted, e.g. docling-serve): base URL of the instance
+# DOCLING_SERVE_URL=https://your-docling-host.example.com
+
+# Transport. "stdio" (Claude Desktop) or "http" (Docker / claude.ai).
+# HTTP mode additionally requires INTERNAL_AUTH_SECRET.
+# FASTMCP_TRANSPORT=stdio
+# FASTMCP_HOST=127.0.0.1
+# FASTMCP_PORT=8000
+# INTERNAL_AUTH_SECRET=          # openssl rand -hex 32; must match PFW's
+
+# Download proxy. See README "Environment variables" for the full list.
+# FPD_PROXY_PORT=8081
+# CENTRALIZED_PROXY_URL=         # full base URL of the PFW centralized proxy
+
 # =============================================================================
 # OAuth sign-in (dual IdP: Google + Entra ID) — HTTP mode only
 # =============================================================================
 # "none" (default) keeps today's behavior. "oauth" turns the HTTP surface into
 # an OAuth 2.1 authorization server: users sign in with Google/Microsoft and
 # must have an active row in the mcp_users table (see
-# scripts/manage_mcp_users.py and the FPD_manage_users tool). In the suite
-# deployment FPD points FPD_AUTH_DB_PATH at the shared paid-tier file
-# hosted by PFW (shared bind mount, same host only).
+# scripts/manage_mcp_users.py and the FPD_manage_users tool). In a suite
+# deployment FPD points FPD_AUTH_DB_PATH at the shared user database
+# hosted alongside PFW (shared bind mount, same host only).
 # FPD_AUTH_MODE=oauth
 # FPD_AUTH_BASE_URL=https://your-public-hostname.example.com
 # FPD_AUTH_JWT_SECRET=  # openssl rand -hex 32 — rotating logs everyone out
@@ -26,6 +54,15 @@
 #                            # this only to whichever internal caller
 #                            # actually needs to manage users; most
 #                            # deployments should leave it unset.
+# FPD_AUTH_ALLOWED_REDIRECT_HOSTS=   # comma-separated EXTRA hosts allowed to
+#                            # dynamically register a redirect_uri. claude.ai,
+#                            # claude.com, anthropic.com, chatgpt.com, openai.com,
+#                            # localhost and 127.0.0.1 are always allowed
+#                            # (subdomains included). Clients already registered
+#                            # are unaffected.
+# FPD_AUTH_OPEN_REGISTRATION=false   # true restores fully open Dynamic Client
+#                            # Registration. Leave false: an arbitrary redirect_uri
+#                            # is the first half of an identity-takeover chain.
 # FPD_AUTH_REGISTER_URL=     # optional "Request access" link
 # FPD_AUTH_ACCESS_TTL=3600
 # FPD_AUTH_REFRESH_TTL=2592000
@@ -56,3 +93,73 @@
 # tool disappears. When enabled + FPD_AUTH_MODE=oauth it is additionally
 # gated behind the fpd:admin scope.
 # FPD_ENABLE_USER_MANAGEMENT=false
+
+# Registration gate for the 10 MCP prompt templates. Default off: no prompts
+# are registered (absent from prompts/list on stdio and HTTP alike) unless
+# this is "true". When enabled, all 10 prompt templates register as before.
+# FPD_ENABLE_PROMPTS=false
+
+# =============================================================================
+# Response-size guard (shared/response_bounds.py)
+# =============================================================================
+# claude.ai replaces an OVERSIZED tool result with a client-side truncation
+# error the server never sees: the model gets no data and no way to recover.
+# The cap applies to the serialized payload, so these budgets are CHARACTER
+# budgets (len(json.dumps(...))), never token estimates. Shared, identically
+# named, across the FPD/PTAB/PFW MCPs.
+#
+# Structured responses (searches, petition details) are slimmed then
+# truncated to fit, always with a `_bounds` marker carrying recovery
+# guidance. Document content (the OCR tool) gets the higher content budget
+# and a `_window` cursor instead — nothing is lost, it is paged via
+# char_offset/max_chars.
+# USPTO_MAX_RESPONSE_CHARS=40000
+# USPTO_MAX_CONTENT_CHARS=120000
+# USPTO_RESPONSE_BOUNDS_ENABLED=true    # false disables the guard entirely
+
+# Per-document page cap for the Mistral OCR tier (was a hard-coded 50).
+# Same variable name in the PFW and PTAB MCPs. A capped extraction is always
+# marked (truncated / truncation_note / _bounds).
+# MISTRAL_OCR_MAX_PAGES=50
+
+# Daily (UTC) ceiling on metered Mistral OCR usage. UNSET NOW MEANS THE
+# BUILT-IN DEFAULT of 5.00, not unlimited: leaving the only bound on a metered
+# third-party API switched off by default was M-21. Set 0 to opt out
+# explicitly. The user-facing message when the ceiling is hit is neutral; the
+# accounting detail stays in the server log.
+# MISTRAL_OCR_DAILY_BUDGET_USD=5.00
+
+# =============================================================================
+# Timeouts (F-R2: these existed but were documented only in main.py's
+# docstring and CLAUDE.md, not anywhere an operator tuning a deployment looks)
+# =============================================================================
+# USPTO_TIMEOUT=30.0            # per USPTO API request
+# USPTO_DOWNLOAD_TIMEOUT=60.0   # PDF download, extraction AND proxy stream
+# DOCLING_TIMEOUT=300.0         # docling-serve extraction (tier 3)
+# DOCLING_MAX_PAGES=25          # tier-3 page gate; a document whose page count
+#                               # cannot be determined is refused, not admitted
+# FPD_TOOL_DEADLINE_SECONDS=150 # overall budget for one content-extraction
+#                               # tool call, so a slow tier returns an envelope
+#                               # instead of a client-side transport timeout
+# FPD_MAX_MCP_BODY_BYTES=4194304 # request body cap on the /mcp surface
+# FPD_MAX_PDF_BYTES=26214400    # per-document extraction byte cap (25 MB)
+
+# Error-detail mode. Unset means "production": error envelopes carry a
+# generic message for 401/403/429/5xx and never a `context` block. F-E8: this
+# variable appeared nowhere in .env.example, the Dockerfile or deploy/, so
+# the detailed branch was unreachable for developers too — a debug mode
+# nobody could turn on without reading the source. Values that enable detail:
+# development, dev, test.
+# ENVIRONMENT=production
+
+# =============================================================================
+# Reverse-proxy trust (M-1)
+# =============================================================================
+# The download-proxy IP allowlist and every rate limiter key on the caller's
+# address. Behind an API gateway or reverse proxy the raw ASGI peer is ONE
+# value for the whole internet, so the allowlist admits everyone the proxy
+# admits and the limiters throttle all callers as a single client. Declare
+# the proxy's own address (IP or CIDR, comma-separated) and X-Forwarded-For
+# is honored FROM THAT PEER ONLY. Leave unset for a direct deployment: the
+# header is then never consulted, which is the historical behavior.
+# FPD_TRUSTED_PROXY_IPS=172.18.0.0/16

.github/dependabot.yml

@@ -0,0 +1,18 @@
+# L-25: no dependency advisory gate existed. uv.lock pins a reproducible
+# resolved set, which is why this was a LOW rather than a HIGH, but nothing
+# told the operator when one of those pins gained an advisory.
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 3

.github/workflows/secret-scan.yaml

@@ -33,15 +33,29 @@ jobs:
             --exclude-files '\.md$' \
             --exclude-files 'package-lock\.json' \
             --exclude-files '\.lock$' \
+            --exclude-files '\.baseline$' \
             --baseline .secrets.baseline
 
       - name: Check for secrets in git history (last 100 commits)
         run: |
-          # Scan recent git history for accidentally committed secrets
+          # Scan recent git history for accidentally committed secrets.
+          # detect-secrets exits 0 even when it finds something, so the results
+          # are inspected explicitly instead of being discarded with `|| true`.
           git log --all --pretty=format: -p -100 | \
           detect-secrets scan --stdin \
             --exclude-files 'configs/.*\.json' \
-            --exclude-files '\.md$' || true
+            --exclude-files '\.md$' \
+            --exclude-files '\.baseline$' > history-scan.json
+          python - history-scan.json <<'PY'
+          import json, sys
+          results = json.load(open(sys.argv[1])).get("results", {})
+          for path, findings in results.items():
+              for finding in findings:
+                  print(f"{path}:{finding.get('line_number')} {finding.get('type')}")
+          if results:
+              sys.exit("Secrets detected in git history")
+          print("No secrets detected in git history")
+          PY
 
       - name: Security scan summary
         if: always()

.github/workflows/security-scan.yaml

@@ -33,15 +33,29 @@ jobs:
             --exclude-files '\.md$' \
             --exclude-files 'package-lock\.json' \
             --exclude-files '\.lock$' \
+            --exclude-files '\.baseline$' \
             --baseline .secrets.baseline
 
       - name: Check for secrets in git history (last 100 commits)
         run: |
-          # Scan recent git history for accidentally committed secrets
+          # Scan recent git history for accidentally committed secrets.
+          # detect-secrets exits 0 even when it finds something, so the results
+          # are inspected explicitly instead of being discarded with `|| true`.
           git log --all --pretty=format: -p -100 | \
           detect-secrets scan --stdin \
             --exclude-files 'configs/.*\.json' \
-            --exclude-files '\.md$' || true
+            --exclude-files '\.md$' \
+            --exclude-files '\.baseline$' > history-scan.json
+          python - history-scan.json <<'PY'
+          import json, sys
+          results = json.load(open(sys.argv[1])).get("results", {})
+          for path, findings in results.items():
+              for finding in findings:
+                  print(f"{path}:{finding.get('line_number')} {finding.get('type')}")
+          if results:
+              sys.exit("Secrets detected in git history")
+          print("No secrets detected in git history")
+          PY
 
       - name: Security scan summary
         if: always()

.github/workflows/tests.yaml

@@ -0,0 +1,54 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, master, develop ]
+  pull_request:
+    branches: [ main, master, develop ]
+
+jobs:
+  test:
+    name: Lint and unit tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run ruff
+        # Q-1: src/ is clean as of the 2026-09-03 fix wave, so this is a
+        # blocking gate there. tests/ still carries pre-existing findings in
+        # the two excluded key-management modules, so it stays advisory.
+        run: uv run ruff check src
+
+      - name: Run ruff over tests (advisory)
+        continue-on-error: true
+        run: uv run ruff check tests
+
+      - name: Run mypy (advisory ratchet)
+        # Q-7: 40 errors under the committed lenient config, down from 48.
+        # Advisory so the count can only be driven down deliberately; the
+        # step exists so a regression is visible in the run log.
+        continue-on-error: true
+        run: uv run mypy src/fpd_mcp
+
+      - name: Run pytest
+        run: uv run pytest -q
+
+      - name: Audit dependencies for known advisories
+        # L-25: the repo had no dependency advisory gate at all. Advisory
+        # because an upstream CVE disclosure must not block an unrelated
+        # merge; it does put the finding in the run log the same day.
+        continue-on-error: true
+        run: uv run --with pip-audit pip-audit

.pre-commit-config.yaml

@@ -16,6 +16,8 @@ repos:
           - '\.md$'
           - '--exclude-files'
           - 'package-lock\.json'
+          - '--exclude-files'
+          - '\.baseline$'
         exclude: ^\.secrets\.baseline$
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -33,8 +35,26 @@ repos:
       - id: check-merge-conflict
       - id: detect-private-key
 
+  # Q-1: the C901 complexity gate, the mypy config and a ~15-second test
+  # suite were all committed and none of them ran automatically — the only
+  # two workflows were security scanners. ruff runs per commit; pytest runs
+  # on push, where 15 seconds is affordable.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      - id: ruff
+        args: [--config, pyproject.toml]
+        files: ^src/
+
   - repo: local
     hooks:
+      - id: pytest
+        name: pytest (fast suite)
+        entry: uv run pytest -q
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
       - id: prompt-injection-check
         name: Check for prompt injection patterns (Unicode steganography & FPD attacks)
         entry: uv run python .security/check_prompt_injections.py