Skip to main content
Glama
hsiangjenli

GPSS Patent Search MCP

by hsiangjenli
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

Related MCP server: patents-mcp

Quick Start

Requirements: Python 3.12+ (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

Available Tools

3 tools
tool_get_databases_tools_get_available_databases_postC

MCP Tool endpoint for getting available databases.

Responses:

  • 200 (Success): Successful Response

    • Content-Type: application/json

    • Response Properties:

      • databases: Mapping of region -> database code -> description. Each database entry is a human-friendly description derived from the PatDB enum.

    • Example:

{
  "success": true,
  "databases": {
    "key": "value"
  }
}
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
successYes
databasesYesMapping of region -> database code -> description. Each database entry is a human-friendly description derived from the `PatDB` enum.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden. 'Getting' weakly implies a read-only, side-effect-free operation, but it says nothing about auth requirements, caching, rate limits, or whether results are static. Almost all text is spent restating the response shape rather than behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The sentence of actual purpose is front-loaded, but the bulk of the description is a verbose response-schema dump (status codes, content types, sample JSON) that is redundant given the output schema exists. Much of the text does not earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter read tool with an output schema, the core operation is understandable, but the description omits any usage framing or behavioral notes and instead duplicates return-value structure that the output schema already covers. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. There is nothing to document, and the description correctly avoids inventing parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource: 'getting available databases'. An agent can tell it retrieves the list of databases, distinct from the sibling search_patents/get_search_examples tools. It does not explicitly name or differentiate from those siblings, and the 'MCP Tool endpoint' phrasing is meta noise rather than added meaning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no indication of when to use this tool versus alternatives, nor any precondition (e.g. 'call this first to discover valid database codes before searching patents'). Usage must be entirely inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_examples_tools_get_search_examples_postC

MCP Tool endpoint for getting search examples.

Responses:

  • 200 (Success): Successful Response

    • Content-Type: application/json

    • Response Properties:

    • Example:

{
  "success": true,
  "examples": {
    "key": "value"
  }
}
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
successYes
examplesYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, and it does not meet it. It only restates the HTTP success envelope, saying nothing about whether the examples are static, user-specific, or whether the call has side effects or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first line is front-loaded, but the bulk of the text is generated response-schema boilerplate that duplicates structured data already present in the output schema. Roughly half the content does not earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because an output schema exists, the description need not explain return values, yet it spends its length doing exactly that while omitting what an agent actually needs: what the examples demonstrate and when to consult them. Adequate but with clear gaps for a zero-param discovery tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate beyond what the empty schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a verb+resource ('getting search examples'), so an agent can tell it is a read of example queries. However, it never says what the examples are for or how they relate to the sibling search_patents tool, and the prefix 'MCP Tool endpoint for' is filler rather than specification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance at all: no mention of calling this before search_patents to learn query syntax, no prerequisites, and no exclusions. The agent is left to infer the tool's role purely from its name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_search_patents_tools_search_patents_postB

MCP Tool endpoint for patent search.

This tool searches the GPSS (Global Patent Search System) for patents matching your keywords. Authentication is handled automatically via the USER_CODE environment variable.

Simply provide your search keywords and optional filters. The tool will:

  1. Automatically read USER_CODE from the environment

  2. Send the request to GPSS API

  3. Return parsed results with patent numbers, titles, abstracts, and inventor info

Responses:

  • 200 (Success): Successful Response

    • Content-Type: application/json

    • Response Properties:

    • Example:

{
  "success": true,
  "data": "unknown_type",
  "request_params": "unknown_type"
}

  • 422: Validation Error

    • Content-Type: application/json

    • Response Properties:

    • Example:

{
  "detail": [
    "unknown_type"
  ]
}
ParametersJSON Schema
NameRequiredDescriptionDefault
keywordsYesKeyword expression understood by GPSS (e.g., '雲端 AND 轉型')
databasesNoOptional list of GPSS database codes (patDB)
max_resultsNoMaximum number of results to request from GPSS
patent_typesNoOptional list of GPSS patent type codes (patTY)
search_fieldNoWhich GPSS field group(s) to search. Provide a single value or a list to reuse the same keywords across multiple fields (additional fields are combined with OR per GPSS API rules). Supported values include single fields such as: title, abstract, claims, patent_number, publication_date, application_number, application_date, applicant_name, first_applicant_name, applicant_country, first_applicant_country, inventor_name, inventor_country, agent_name, examiner, priority, priority_date, ipc, first_ipc, cpc, first_cpc, loc, fi, f_term, d_term, uspc, and cited_patents.title
application_typesNoOptional list of GPSS application type codes (patAG)
publication_date_toNoUpper bound for publication date (YYYYMMDD)
publication_date_fromNoLower bound for publication date (YYYYMMDD)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
errorNo
successYes
request_paramsNo

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It usefully discloses that authentication is automatic via the USER_CODE environment variable and lists the step sequence (read env, call GPSS, parse results), plus the 200/422 response codes. It omits rate limits, pagination behavior, and what happens if USER_CODE is unset.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening two paragraphs are tight and front-loaded, but the bulk of the description is an auto-generated response block whose examples are placeholder junk ('data': 'unknown_type'), adding length without value since an output schema already exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A full output schema covers return values and the description explains the auth flow, so the core is covered. But for an 8-parameter search tool it lacks guidance on discovering valid database/patent-type codes via the sibling tools and says nothing about result volume or failure modes beyond 422.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description only says 'keywords and optional filters' and adds nothing about search_field semantics, date formats, or how multiple search_fields are OR-combined beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'searches the GPSS (Global Patent Search System) for patents matching your keywords.' An agent can tell what the tool returns (patent numbers, titles, abstracts, inventor info). However, it never names the sibling tools (get_available_databases, get_search_examples) or explains how it differs from them, so it stops short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Simply provide your search keywords and optional filters' implies the basic call pattern, but there is no when-to-use vs. when-not guidance and no mention that database/type codes should come from the sibling lookup tools. Usage is implied rather than explicitly scoped.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.3
    • First observedtool_get_databases_tools_get_available_databases_post
    • First observedtool_get_examples_tools_get_search_examples_post
    • First observedtool_search_patents_tools_search_patents_post
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation5/5

The three tools serve clearly distinct purposes: searching patents, listing available databases, and retrieving search examples. There is no meaningful overlap in intent, so an agent can select the correct tool without confusion.

Naming Consistency3/5

All three names follow the same (verbatim auto-generated) pattern of 'tool_x_tools_x_post', so the convention is technically consistent. However, the redundant, verbose, and double-encoded structure is awkward and hard to read, making names less predictable than a clean verb_noun scheme.

Tool Count4/5

Three tools—one core search plus two metadata helpers—is slightly thin but well-scoped for a focused patent search server. Nothing extraneous is present.

Completeness3/5

The core search, database listing, and example retrieval are covered, but there is no tool to fetch full details for a specific patent number and no apparent support for citation, family, or document retrieval. These are notable gaps for a patent-search domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers