e-RUP KNF MCP Server

TypeScript MCP server that wraps the public KNF e-RUP registry API at https://e-rup.knf.gov.pl/JSON.

License

This project is licensed under the MIT License. See LICENSE.

Security

To report vulnerabilities, see SECURITY.md.

Requirements

• Node.js 18+
• npm

Setup

npm install

Run

Development:

npm run dev

Build + start:

npm run build
npm start

MCP Configuration (stdio)

Example MCP client entry:

{
  "mcpServers": {
    "erup": {
      "command": "node",
      "args": ["/absolute/path/to/erup2.0-mcp/dist/index.js"]
    }
  }
}

For local development with tsx:

{
  "mcpServers": {
    "erup-dev": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/erup2.0-mcp/src/index.ts"]
    }
  }
}

Tools

• search_entities: Search and filter entity listing with pagination and sorting.
• get_entity: Full detail record for a single entity id.
• get_entity_services: Authorized services for an entity by service type.
• get_entity_agents: Paged agents list for an entity.
• get_entity_branches: Paged branches list for an entity.
• get_entity_history: Status history timeline for an entity.
• list_entity_types: KNF taxonomy list for ENT_TYP (cached in memory).
• get_registry_stats: Count-only query (limit: 0) for optional filters.

Known KNF API Quirks

• List filters must use internal codes:
  • entity_type: PSD_PI, PSD_EPI@BP, ...
  • status: ES_1, ES_2
• Using display names like Wpisany in list filters returns zero rows without an error.
• Upstream can return HTTP 200 with status: "error" in JSON. The server treats this as a failure.
• SER_LIS encodes commas as ,; this server decodes values before returning structured service lines.

Testing

Run all local unit tests:

npm test

Run opt-in live tests against https://e-rup.knf.gov.pl/JSON:

ERUP_LIVE_TESTS=1 npm run test:live

Live tests are skipped by default unless ERUP_LIVE_TESTS=1.

Quality Gates

npm run lint
npm run typecheck
npm test