@pipeworx/wipo-pearl

Scientific, technical and IP legal terminology — search a term and get back validated equivalents across 10 languages, each with a reliability rating, defining context, usage note and source. Platform key, with a small keyless fallback.

Part of Pipeworx — an MCP gateway connecting AI agents to 1857+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

Tools

• pearl_search_terms(term, source_language?, target_languages?, subject_field?, abbreviation?, exact_search?, limit?) — search for a term; returns matching concept records (concept id, matched term text, subject field).

• pearl_concept(concept_id, lang_code?) — the full database record for one concept id (from pearl_search_terms): equivalents grouped by language, each with a reliability rating, defining context, usage note and source.

• pearl_subject_fields() — reference list of the 29 subject-field codes and 10 language codes the other two tools accept. No arguments.

Related MCP server: termdat-mcp

Auth

Platform key (PLATFORM_WIPO_KEY) with BYO override via _apiKey. Unlike most platform keys, the stored value is a JSON STRING — {"client_id":"...","client_secret":"..."} — not a bare token, because the WIPO Business Partner Portal issues an application as a client_id/secret pair rather than a single key. Each call JSON.parses it and exchanges the pair for a short-lived Bearer JWT via OAuth2 client_credentials; the token is not cached across calls.

Activation is two gates, not one — registering an application is not the same as being able to call the API. The Business Partner Portal (b2b.wipo.int) issues the client_id/client_secret immediately on registration, but the application also has to be subscribed to the "WIPO Pearl API" product/plan, and that subscription is reviewed and approved by WIPO before it's usable — it is not instant and not guaranteed. A credential that authenticates fine at the OAuth2 token endpoint can still get a 403 from the Pearl API itself if the subscription step hasn't been approved yet; this pack's error message says exactly that rather than a generic "forbidden", so it doesn't read as our outage. If no credential (platform or BYO) is present at all, calls fall back to WIPO's own tiny keyless allowance — its own portal describes this as "5 requests per day" before you're expected to register — which is only useful for a one-off smoke test, never production traffic through a shared gateway.

Data sources

• World Intellectual Property Organization (WIPO), WIPO Pearl terminology database — 250,000+ validated terms in Arabic, Chinese, English, French, German, Japanese, Korean, Portuguese, Russian and Spanish, across 29 subject fields.

Notes for the next person

• The two tools are NOT equally reachable without a credential. pearl_search_terms's underlying search route answers keyless requests with real 200s (subject to the "5 requests/day" allowance above). pearl_concept's underlying detail route answered a flat 500 Internal Server Error on every keyless attempt made while building this pack — it appears to require the OAuth2 credential, and the upstream throws rather than returning a clean 401/403 when it's missing. Expect this route specifically to look "down" if ever called without a working credential; it isn't — it's just gated differently than the sibling route.

• The keyless allowance is per calling IP, not a single global budget — confirmed by exhausting it from one network path (a 429 "Rate limit exceeded! You reached the limit of 5 requests per 1440 minutes") while an identical call from a different egress still returned 200. Don't read one exhausted path as the whole API being down.

• The product page is a Gravitee developer-portal SPA with no endpoint in its rendered HTML. The live entrypoint, the OAuth2 token endpoint, the full request/response contract and the subject-field/language tables all came from the portal's own backend REST API and documentation pages (its assets/config.json, /apis/<id>, /apis/<id>/pages and the portal-wide FAQ pages) — see the file header in src/index.ts for exactly which pages. There is no dedicated subject-fields or languages endpoint; those two tables are from the product's own "Data Models" documentation page, not an API call, which is why pearl_subject_fields is static rather than a proxy.

• The response shape of an authenticated /records/{id} call is inferred from the product's OpenAPI spec, not empirically observed — building this pack had no working credential to test with. pearl_concept raises a loud upstream_parse error (naming the URL and body length) rather than a silent empty success if a real response doesn't match the documented shape, so a mismatch will surface on the first real call instead of sitting unnoticed.

• hits/count in the search response are JSON strings ("70", not 70) despite the spec declaring them as integers — parsed with Number().

• The upstream's own limit/count query parameters were unreliable in testing: a request with neither set returned the full hit set (45-70+ records) rather than the spec's documented 5-record default. This pack passes both anyway but also truncates the result client-side, so the response size is bounded regardless of whether the upstream honors either parameter.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "wipo-pearl": {
      "url": "https://gateway.pipeworx.io/wipo-pearl/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/wipo-pearl/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1857+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

curl -X POST https://gateway.pipeworx.io/v1/tools/pearl_search_terms \
  -H 'Content-Type: application/json' \
  -d '{"term":"satellite","limit":5}'

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/pearl_search_terms. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Run it from npm

@pipeworx/mcp-wipo-pearl is a local stdio bridge to the Pipeworx gateway: your MCP client starts it with npx, and it forwards every call to the same https://gateway.pipeworx.io/wipo-pearl/mcp endpoint shown above. It needs network access; there is no offline mode.

{
  "mcpServers": {
    "wipo-pearl": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-wipo-pearl"]
    }
  }
}

Without a key it calls anonymously, capped at 50 calls a day. A free account raises that to 200 a day: get a key at https://pipeworx.io/signup and add "env": { "PIPEWORX_API_KEY": "<your key>" } to the server entry. The key is sent as a Bearer token, the same way a hosted connection sends it, so calls are metered and billed exactly as they are there.

It lists only this pack's tools by default. Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.

Behind an HTTPS proxy: Node's built-in fetch does not read HTTPS_PROXY by default. Newer Node releases honour it when NODE_USE_ENV_PROXY=1 is set; check your Node version's documentation.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about Wipo Pearl data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides

• pipeworx.io

License

MIT