Open Archieven MCP Server v1.0

Production-grade hybrid MCP + HTTP + SSE server generated from the Open Archieven OpenAPI specification.

OpenAPI source used to generate tools:

../api/openapi.yaml   (local)
https://api.openarchieven.nl/openapi.yaml   (remote)

Overview

A schema-aware server that automatically converts the OpenAPI specification into callable tools and exposes them through multiple transports:

MCP Remote (JSON-RPC over StreamableHTTP)
HTTP JSON API
SSE streaming with auto-pagination
Chunked HTTP streaming with auto-pagination
Redis caching (optional)
Health checks

Core Features

OpenAPI Auto-Generation

Every API operation becomes a tool automatically via generate.ts.

All 17 operations:

Tool Name	Description
`search_records`	Search genealogical records
`show_record`	Show a single genealogical record
`match_record`	Match a person to birth and death records
`get_births_years_ago`	List births from N years ago
`get_births`	Find birth records
`get_deaths`	Find death records
`get_marriages`	Find marriage records
`get_archives`	List all archives with statistics
`get_record_stats`	Record count per archive
`get_source_type_stats`	Record count per source type
`get_event_type_stats`	Record count per event type
`get_comment_stats`	Comment count statistics
`get_family_name_stats`	Family name frequency
`get_first_name_stats`	First name frequency
`get_profession_stats`	Profession frequency
`get_historical_weather`	Historical weather from KNMI
`get_census_data`	Dutch census data 1795–1899

Note: The callback (JSONP) parameter present in the upstream API is excluded from all tools — it is irrelevant in an MCP/JSON-RPC context.

Schema-Perfect Validation

Uses actual OpenAPI parameter schemas. Validates:

required parameters
integer fields
number fields
enum values
minimum / maximum constraints

Tool Aliases

Friendly aliases are included:

Alias	Real Tool
`search_person`	`search_records`
`get_record`	`show_record`
`list_archives`	`get_archives`

Multiple Interfaces

MCP Remote (StreamableHTTP)

POST /       ← canonical public endpoint (mcp.openarchieven.nl)
POST /mcp    ← local / legacy alias

Stateless JSON-RPC transport — a new MCP server instance is created per request.

Required header: All MCP POST requests must include Accept: application/json, text/event-stream. Omitting it returns a -32000 Not Acceptable error. MCP clients (Claude Desktop, etc.) send this automatically.

HTTP JSON

GET  /tools
POST /tools/:name

SSE Streaming (auto-paginating)

GET /events/:name

Chunked HTTP Streaming (auto-paginating)

POST /stream/:name

Pagination

Streaming endpoints (/events/:name, /stream/:name) automatically paginate through results for endpoints that support a start offset:

Increments start by number_show per page
Stops when results are exhausted or after 20 pages (safety cap)
SSE sends a : heartbeat comment every 10 seconds to keep connections alive

Redis Cache

Optional Redis support.

If Redis is running:

responses are cached for 1 hour (configurable via CACHE_TTL)

If Redis is unavailable:

server still runs normally (degraded mode)

Rate Limiting

The upstream API enforces 4 requests per second per IP. The server queues all upstream calls through a token-bucket rate limiter (configurable via RATE_LIMIT_RPS).

Health Checks

GET /health

Project Files

generate.ts
server.ts
tsconfig.json
package.json
.env.example
generated/
  tools.json
  spec.json

Requirements

Node.js 18+
npm
optional Redis server

Configuration

Copy .env.example to .env and adjust:

cp .env.example .env

Variable	Default	Description
`PORT`	`3001`	HTTP port
`OPENAPI_PATH`	`../api/openapi.yaml`	Path or URL to OpenAPI spec
`UPSTREAM_BASE`	`https://api.openarchieven.nl/1.1`	Upstream API base URL
`RATE_LIMIT_RPS`	`4`	Upstream requests per second
`REDIS_URL`	`redis://localhost:6379/5`	Redis connection URL (db 5)
`CACHE_TTL`	`3600`	Cache TTL in seconds
`LOG_LEVEL`	`info`	`trace` `debug` `info` `warn` `error` `fatal`
`NODE_ENV`	(unset)	Set to `production` for JSON logs (default: pretty-printed)

Install

npm install

Generate Tools from OpenAPI YAML

Run from local spec:

npx tsx generate.ts

Or from remote URL:

npx tsx generate.ts https://api.openarchieven.nl/openapi.yaml

Expected result:

Generated 17 tools
Output: generated/tools.json, generated/spec.json

Creates:

generated/tools.json
generated/spec.json

Start Server

npx tsx server.ts

Expected startup (development — pretty-printed):

[12:00:00] INFO: Open Archieven MCP server started
    port: 3001
    tools: 17
    aliases: 3
    upstream: "https://api.openarchieven.nl/1.1"
    rateLimit: "4 req/s"
    redis: "redis://localhost:6379/5"
    env: "development"

In production (NODE_ENV=production) each log line is a single JSON object.

Server binds to:

http://0.0.0.0:3001

Test All Features

1. Health Check

curl http://localhost:3001/health

Expected:

{
  "ok": true,
  "tools": 17,
  "aliases": 3,
  "redis": false,
  "uptime": 1.23
}

2. List Tools

curl http://localhost:3001/tools

Expected:

[
  "search_records",
  "show_record",
  "match_record",
  "get_births_years_ago",
  "get_births",
  "get_deaths",
  "get_marriages",
  "get_archives",
  "get_record_stats",
  "get_source_type_stats",
  "get_event_type_stats",
  "get_comment_stats",
  "get_family_name_stats",
  "get_first_name_stats",
  "get_profession_stats",
  "get_historical_weather",
  "get_census_data",
  "search_person",
  "get_record",
  "list_archives"
]

3. Normal Tool Call (via alias)

curl -X POST http://localhost:3001/tools/search_person \
-H "Content-Type: application/json" \
-d '{"name":"Jansen"}'

4. Canonical Tool Call

curl -X POST http://localhost:3001/tools/search_records \
-H "Content-Type: application/json" \
-d '{"name":"Jansen"}'

5. Show a Single Record

curl -X POST http://localhost:3001/tools/show_record \
-H "Content-Type: application/json" \
-d '{"archive":"hua","identifier":"E13B9821-C0B0-4AED-B20B-8DE627ED99BD"}'

6. SSE Streaming

curl -N "http://localhost:3001/events/search_records?name=Coret"

Expected stream:

event: page
data: {...}

event: page
data: {...}

event: done
data: {}

7. Heartbeat Test

Leave SSE open for 15+ seconds — expect periodic keep-alive lines:

: heartbeat

8. Chunked HTTP Streaming

curl -N -X POST http://localhost:3001/stream/search_records \
-H "Content-Type: application/json" \
-d '{"name":"Jansen"}'

Expected (newline-delimited JSON):

{"query":{...},"response":{"number_found":...,"docs":[...]}}
{"query":{...},"response":{"number_found":...,"docs":[...]}}

9. MCP Initialize

curl -X POST http://localhost:3001/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "test", "version": "1.0" }
  }
}'

10. MCP List Tools

curl -X POST http://localhost:3001/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}'

11. MCP Call Tool

curl -X POST http://localhost:3001/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_person",
    "arguments": { "name": "Jansen" }
  }
}'

Redis Testing

Start Redis

redis-server

Restart the MCP server. Expected in /health:

{ "redis": true }

Without Redis

Stop Redis and restart. Expected:

{ "redis": false }

Common Commands

Regenerate after API changes

npx tsx generate.ts

Restart server

npx tsx server.ts

Troubleshooting

Generated files missing

npx tsx generate.ts

Port already in use

Linux / macOS:

lsof -i :3001
kill -9 <PID>

Windows:

netstat -ano | findstr :3001
taskkill /PID <PID> /F

Redis not connecting

Server runs normally without Redis. Check REDIS_URL in .env.

Rate limit errors (429)

The upstream API allows 4 req/s per IP. The built-in rate limiter queues requests automatically. If you are running multiple server instances, reduce RATE_LIMIT_RPS or use a shared queue.

Recommended Production Upgrades

HTTPS reverse proxy (nginx / caddy)
PM2 or systemd process manager
Structured JSON logging (pino / winston)
Request tracing (OpenTelemetry)
Auth middleware if server is public-facing
Shared Redis for multi-instance deployments

Version

v1.0

Schema-perfect OpenAPI-generated MCP server for Open Archieven.

Open Archives