IP-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP server for trademark and company research over public registers. One file, zero dependencies, Node 18+, ESM. It speaks MCP over stdio with a hand-rolled JSON-RPC loop — there is no SDK, no build step and no bundler.

Distribution is npx -y github:AI-AlexBaum/IP-MCP, straight from the repo. Nothing is published to npm, so package.json's bin and files must stay correct or the install path silently breaks.

Commands

npm run smoke              # the entire test suite (24 checks, hits live registers)
node --check src/index.js  # syntax gate
node src/index.js          # speaks MCP on stdin/stdout

To run a single check, pipe one JSON-RPC line in — this is the fastest way to iterate on a tool:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tm_clearance","arguments":{"name":"Northwind"}}}' \
  | node src/index.js

The paid tools need credentials in the environment, never in the repo:

COMPANYINFO_USERNAME=… COMPANYINFO_PASSWORD=… node src/index.js

The smoke test calls live third-party APIs. A failure can mean upstream drift rather than a regression — check the endpoint by hand before assuming the code broke. The four paid nl_company_* tools are deliberately not in the suite: each run would cost money and return real company data. Verify those by hand when you touch them.

Architecture

src/index.js is layered top to bottom:

1. Constants — OFFICES (register codes), LIVE (which statuses count as a live right), VIES_MS (VAT member states).
2. http() — every outbound call goes through it. Three retries with backoff, 90s timeout, throws on non-2xx. It never converts a failure into an empty result.
3. Source adapters, one group per data source: TMview + EUIPO copla (trademarks), GLEIF + VIES (companies), EU_REGISTERS (sixteen national registers), and the Company.info SOAP layer (paid, Dutch Handelsregister).
4. TOOLS — JSON schemas — and HANDLERS — name → function.
5. stdio loop — line-buffered reader plus dispatch(), which tracks in-flight requests so a client closing stdin mid-call does not drop pending replies.