mcp-fetch-patents: Instructions file for Codex

AGENTS.md — mcp-fetch-patents

Project Overview

Dual-implementation MCP server for patent fetching, caching, and search.

• Python (src/python/) — reference implementation
• Rust (src/rust/) — production implementation, feature parity with Python

Both expose MCP tools over stdio JSON-RPC. Rust and the Python entrypoints also expose localhost HTTP at /mcp via serve-http; the shared guarantee is the default URL, not wire-identical HTTP behavior across implementations.

Build & Test Commands

Must use CC=gcc for all cargo commands (default cc is a wrapper that breaks aws-lc-sys).

just test-rust              # Run all Rust tests (237 tests)
just build-rust             # Debug build
just build-rust-release     # Release build
just check-rust             # Quick type-check
just lint-rust              # Clippy with -D warnings
just test                   # Python fast tests
just ci                     # Python fast + Rust tests
just serve-rust             # Run Rust MCP server
just serve-rust-http        # Run Rust MCP server over localhost HTTP
just serve-http             # Run Python fetch MCP server over localhost HTTP
just serve-search-http      # Run Python search MCP server over localhost HTTP
just install-rs

For direct cargo commands:

CC=gcc cargo test --manifest-path src/rust/Cargo.toml
CC=gcc cargo build --manifest-path src/rust/Cargo.toml

After you have completed a your tasks, commit your work and run 'just install-rs'.

Rust Module Layout

src/rust/src/
  lib.rs              — crate root, pub mod declarations
  main.rs             — binary entrypoint
  config/mod.rs       — PatentConfig (env vars, .patentrc)
  id_canon/           — patent ID canonicalization
  cache/              — SQLite-backed patent cache
  fetchers/           — HTTP fetch backends (USPTO, EPO, Google)
    http/             — HTTP fetcher implementations (per-source files)
    browser.rs        — Playwright/chromiumoxide browser fetcher
    web_search/       — web search utilities
    mod.rs            — FetcherOrchestrator, PatentSource trait
  converters/         — format conversion (XML, JSON, etc.)
  journal.rs          — activity journal
  planner.rs          — NL query planner (deterministic, rule-based)
  ranking.rs          — PatentHit scoring/reranking
  search/             — search MCP tools
    mod.rs            — module root, SearchBackends struct
    orchestrator.rs   — search orchestration (NL search + enrichment)
    session_manager.rs — session persistence (atomic JSON, path traversal guard)
    searchers/        — search backends
      mod.rs          — re-exports, shared helpers
      serpapi.rs      — SerpAPI Google Patents backend
      uspto.rs        — USPTO text search backend
      epo_ops.rs      — EPO OPS backend (OAuth, citations, family, XML/JSON)
    profile_manager.rs — browser profile dirs with file-based locking
    browser_search.rs  — Google Patents via chromiumoxide
  server/mod.rs       — MCP server: tool descriptors + handlers (fetch + search)