# 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):

```bash
export USER_CODE=your_api_code_here
# or add to .env
```

2. Run locally (stdio transport):

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

3. Run the included example client:

```bash
uv run --env-file=.env scripts/example.py
```

### Docker

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

```bash
# 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):

```bash
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:

```bash
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:

```json
{
	"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:

```bash
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