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.12+ (Docker optional)

1. Set credentials (example):

export USER_CODE=your_api_code_here
# or add to .env

2. Run locally (stdio transport):

uv run --env-file=.env fastmcp run mcp_tools/main.py

3. 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