GPSS Patent Search MCP

AI-ready MCP (Model Context Protocol) server for searching patents in the Global Patent Search System (GPSS).

Core Features

  • Flexible search across GPSS fields using keywords and boolean operators
  • Returns raw GPSS XML responses (parsed when available)
  • Code-first schemas (Pydantic) and autogenerated documentation (MkDocs)
  • Works locally or in Docker

Quick Start

Requirements: Python 3.11+ (Docker optional)

  1. Set credentials (example):
export USER_CODE=your_api_code_here
# or add to .env
  1. Run locally (stdio transport):
uv run --env-file=.env fastmcp run mcp_tools/main.py
  1. Run the included example client:
uv run --env-file=.env scripts/example.py

Docker

Build the image locally (or use ./scripts/build_image.sh to build+push):

# build locally
docker build -t mcp-tw-gpss:latest .

# or use the helper (this script also tags and pushes if configured)
./scripts/build_image.sh

Run the container using stdio (the image default CMD runs the MCP with stdio transport):

docker run -i --rm \
    -e USER_CODE=your_api_code_here \
    mcp-tw-gpss:latest

If you prefer the HTTP transport expose port 8000 and override the container command:

docker run -d --rm -p 8000:8000 \
    -e USER_CODE=your_api_code_here \
    mcp-tw-gpss:latest \
    uv run fastmcp run mcp_tools/main.py --transport http

VS Code MCP client example (stdio via docker):

Add to .vscode/settings.json or your MCP client config:

{
    "servers": {
        "tw-gpss": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "-e",
                "USER_CODE=YOUR_USER_CODE",
                "--rm",
                "hsiangjenli/mcp-tw-gpss:latest"
            ]
        }
    },
}

Tools

  • search_patents — search patents with filters (keywords, fields, databases, date range, etc.)
  • get_available_databases — list supported database codes
  • get_search_examples — example payloads to use as templates

Docs & Details

Field mappings and full schema descriptions are authored in code (mcp_tools/schemas.py and FIELD_ALIAS_MAP in mcp_tools/main.py) and published to the site by MkDocs. To regenerate the docs locally:

chmod +x scripts/build_docs.sh
./scripts/build_docs.sh
uv run mkdocs serve
# then open http://127.0.0.1:8000

Reference

  • GPSS API Documentation: https://tiponet.tipo.gov.tw/gpss1/gpsskm/API/API_instructions.pdf
  • MCP Protocol: https://modelcontextprotocol.io
  • FastAPI: https://fastapi.tiangolo.com
  • FastMCP: https://gofastmcp.com/getting-started/welcome
  • Pydantic: https://docs.pydantic.dev