# 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](./LICENSE).

## Security

To report vulnerabilities, see [SECURITY.md](./SECURITY.md).

## Requirements

- Node.js 18+
- npm

## Setup

```bash
npm install
```

## Run

Development:

```bash
npm run dev
```

Build + start:

```bash
npm run build
npm start
```

## MCP Configuration (stdio)

Example MCP client entry:

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

For local development with `tsx`:

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

```bash
npm test
```

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

```bash
ERUP_LIVE_TESTS=1 npm run test:live
```

Live tests are skipped by default unless `ERUP_LIVE_TESTS=1`.

## Quality Gates

```bash
npm run lint
npm run typecheck
npm test
```