Open Archives

Servidor MCP para el motor de búsqueda genealógica Open Archives.

Documentación

Servidor MCP de Open Archives

Servidor híbrido de nivel de producción MCP + HTTP + SSE generado a partir de la especificación OpenAPI de Open Archives. Cubre registros genealógicos (nacimientos, defunciones, matrimonios, censos), estadísticas de archivos, clima histórico y transcripciones de texto completo de páginas de documentos históricos.

Fuente OpenAPI utilizada para generar las herramientas:

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

Descripción general

Un servidor consciente del esquema que convierte automáticamente la especificación OpenAPI en herramientas invocables y las expone a través de múltiples transportes:

MCP Remoto (JSON-RPC sobre StreamableHTTP)
API JSON HTTP
Transmisión SSE con paginación automática
Transmisión HTTP fragmentada con paginación automática
Caché Redis (opcional)
Comprobaciones de salud

Uso con Claude

Añadir como conector personalizado

Hay un endpoint alojado disponible: no se requiere instalación.

En claude.ai o Claude Desktop:

Abra Configuración → Conectores.
Haga clic en Añadir conector personalizado.
Introduzca la URL: https://mcp.openarchieven.nl/
Guarde y apruebe cuando se le solicite.

No se requiere autenticación: Open Archives es un conjunto de datos público.

Consultas de ejemplo

Una vez añadido el conector, puede preguntar a Claude, por ejemplo:

"¿Quiénes son los antepasados de Johannes Gregorius Marinus Coret? Dame una visión general, incluyendo citas de fuentes en formato markdown con los enlaces a los archivos originales si es posible; de lo contrario, proporciona los enlaces de Open Archieven y proporciona un árbol en SVG."
"¿Tuvieron descendientes Johannes Coret y Antonia Uphus? Dame una visión general, incluyendo citas de fuentes en formato markdown con los enlaces a los archivos originales si es posible; de lo contrario, proporciona los enlaces de Open Archieven, incluye miniaturas de escaneos de fuentes de archivo si están disponibles y proporciona un árbol en SVG."
"Proporcióname una lista de tipos de fuente por archivo(nombre) donde pueda encontrar información sobre la familia Coret. Muestra el resultado en un documento markdown incluyendo enlaces a las páginas de búsqueda en Open Archieven. En lugar del código de archivo, usa el ISIL si está disponible."
"¿Qué tiempo hacía en Ámsterdam el 1953-02-01?"
"¿Qué dice el censo de 1850 sobre Utrecht?"

Claude llamará a la herramienta correspondiente (search_records, show_record, get_marriages, get_historical_weather, get_census_data, …) y devolverá enlaces a las páginas de registro correspondientes en https://www.openarchieven.nl.

Autoalojado

El servidor habla MCP sobre HTTP Streamable; no hay distribución stdio. Para ejecutar su propia instancia:

git clone https://github.com/coret/openarchieven-mcp-server.git
cd openarchieven-mcp-server
npm install
npm run generate      # builds generated/tools.json from openapi.yaml
npm run build:viewer  # builds dist/viewer.html (the MCP App)
npm start             # listens on http://localhost:3001/

Apunte su cliente MCP a http://localhost:3001/ (o a su propia URL pública) de la misma manera que el endpoint alojado anterior.

Características principales

Generación automática OpenAPI

Cada operación de la API se convierte en una herramienta automáticamente mediante generate.ts.

Las 21 operaciones:

Nombre de la herramienta	Descripción
`search_records`	Buscar registros genealógicos
`show_record`	Mostrar un único registro genealógico
`match_record`	Relacionar una persona con registros de nacimiento y defunción
`get_births_years_ago`	Listar nacimientos de hace N años
`get_births`	Encontrar registros de nacimiento
`get_deaths`	Encontrar registros de defunción
`get_marriages`	Encontrar registros de matrimonio
`get_archives`	Listar todos los archivos con estadísticas
`get_record_stats`	Recuento de registros por archivo
`get_source_type_stats`	Recuento de registros por tipo de fuente
`get_event_type_stats`	Recuento de registros por tipo de evento
`get_comment_stats`	Estadísticas de recuento de comentarios
`get_family_name_stats`	Frecuencia de apellidos
`get_first_name_stats`	Frecuencia de nombres de pila
`get_profession_stats`	Frecuencia de profesiones
`get_breakdown`	Tabulación cruzada agrupada por archivo, tipo de fuente, tipo de evento, lugar o año
`get_historical_weather`	Clima histórico del KNMI
`get_census_data`	Datos del censo neerlandés 1795–1899
`search_transcriptions`	Búsqueda de texto completo en transcripciones de páginas de documentos históricos
`browse_transcriptions`	Navegar jerárquicamente por transcripciones según archivo fuente, número de archivo o inventario
`show_transcription`	Recuperar una transcripción de página individual por id

Nota: El parámetro callback (JSONP) presente en la API ascendente se excluye de todas las herramientas: es irrelevante en un contexto MCP/JSON-RPC.

Visor de transcripciones interactivo (aplicación MCP)

Más allá de las 21 herramientas generadas automáticamente, el servidor registra una herramienta escrita a mano — view_transcription — que abre páginas transcritas en un visor interactivo de zoom profundo IIIF (OpenSeadragon) con el texto de la transcripción al lado, utilizando la extensión Aplicaciones MCP (io.modelcontextprotocol/ui).

Nombre de la herramienta	Descripción
`view_transcription`	Abrir una o más páginas transcritas (`ids: ["NL-SdmGA_1504889_11", …]`) en un visor IIIF de zoom profundo con la transcripción; `highlight_term` opcional

Hosts compatibles con aplicaciones (Claude web/escritorio, conectores personalizados de pago) renderizan el visor (ui://openarchieven/viewer.html) en un iframe aislado que carga imágenes directamente de los hosts de imágenes de transcripción (incluidos en la lista blanca CSP como *.transkribus.eu, *.archief.nl, *.archieven.nl, *.memorix.nl). Transkribus y el servidor iipsrv de archief.nl proporcionan zoom profundo IIIF real; los hosts de miniaturas preserve*.archieven.nl se renderizan como imágenes planas.
Hosts simples reciben una alternativa elegante: un resumen de texto con las URL IIIF/fuente más algunas imágenes de vista previa en línea.

El visor es un único dist/viewer.html autocontenido, empaquetado en tiempo de compilación con npm run build:viewer (vite + vite-plugin-singlefile); no aparece en el endpoint REST GET /tools, solo mediante MCP tools/list.

Validación perfecta del esquema

Utiliza esquemas de parámetros OpenAPI reales. Valida:

parámetros obligatorios
campos enteros
campos numéricos
valores de enumeración
restricciones de mínimo / máximo

Múltiples interfaces

MCP Remoto (StreamableHTTP)

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

Transporte JSON-RPC sin estado: se crea una nueva instancia del servidor MCP por solicitud.

Validación de origen: Las solicitudes del navegador deben provenir de claude.ai, claude.com o cualquier dominio listado en ALLOWED_ORIGINS. Las solicitudes sin encabezado Origin (clientes MCP nativos, curl, servidor a servidor) se aceptan. Los orígenes desconocidos reciben HTTP 403.

HTTP JSON

GET  /tools
POST /tools/:name

Transmisión SSE (paginación automática)

GET /events/:name

Transmisión HTTP fragmentada (paginación automática)

POST /stream/:name

Metadatos de descubrimiento (`/.well-known`)

Archivos JSON estáticos y editables a mano servidos textualmente desde well-known/:

GET /.well-known/mcp/server-card.json   ← SEP-1649 MCP Server Card
GET /.well-known/mcp.json               ← alias of the server card
GET /.well-known/agent-card.json        ← A2A v0.3 Agent Card
GET /.well-known/agent.json             ← alias of the agent card

Edite well-known/mcp-server-card.json y well-known/agent-card.json directamente: no se requiere reinicio (los archivos se leen en cada solicitud). Las respuestas se envían con Content-Type: application/json; charset=utf-8 y Cache-Control: public, max-age=3600.

Paginación

Los endpoints de transmisión (/events/:name, /stream/:name) paginan automáticamente los resultados para endpoints que admiten un desplazamiento start:

Incrementa start en number_show por página
Se detiene cuando los resultados se agotan o después de 20 páginas (límite de seguridad)
SSE envía un comentario : heartbeat cada 10 segundos para mantener las conexiones activas

Caché Redis

Soporte Redis opcional.

Si Redis está en ejecución, las respuestas ascendentes se almacenan en caché con un TTL por herramienta ajustado a la volatilidad de los datos:

Categoría	TTL	Herramientas
Histórico inmutable	nunca expira	`get_historical_weather`, `get_census_data`
Metadatos que cambian lentamente	7 días	`get_archives`
Agregaciones de estadísticas	1 día	`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_breakdown`
Consultas de registros individuales	1 día	`show_record`, `show_transcription`
Tipo búsqueda	6 horas	`search_records`, `match_record`, `get_births`, `get_deaths`, `get_marriages`, `search_transcriptions`, `browse_transcriptions`
Vinculado a fecha	próxima medianoche UTC	`get_births_years_ago`

CACHE_TTL (predeterminado 3600) es la alternativa para cualquier herramienta no incluida en el mapa anterior.

Si Redis no está disponible:

el servidor sigue funcionando normalmente (modo degradado)

Limitación de velocidad

La API ascendente aplica 4 solicitudes por segundo por IP. El servidor pone en cola todas las llamadas ascendentes a través de un limitador de velocidad de depósito de tokens (configurable mediante RATE_LIMIT_RPS).

Comprobaciones de salud

GET /health

Archivos del proyecto

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

Requisitos

Node.js 18+
npm
servidor Redis opcional

Configuración

Copie .env.example a .env y ajuste:

cp .env.example .env

Variable	Predeterminado	Descripción
`PORT`	`3001`	Puerto HTTP
`OPENAPI_PATH`	`../api/openapi.yaml`	Ruta o URL a la especificación OpenAPI
`UPSTREAM_BASE`	`https://api.openarchieven.nl/1.1`	URL base de la API ascendente
`RATE_LIMIT_RPS`	`4`	Solicitudes ascendentes por segundo
`REDIS_URL`	`redis://localhost:6379/5`	URL de conexión Redis (db 5)
`CACHE_TTL`	`3600`	TTL de caché alternativo en segundos (utilizado para herramientas no incluidas en el mapa por herramienta; consulte Caché Redis)
`LOG_LEVEL`	`info`	`trace` `debug` `info` `warn` `error` `fatal`
`NODE_ENV`	(sin definir)	Establezca en `production` para registros JSON (predeterminado: impresión bonita)
`ALLOWED_ORIGINS`	(vacío)	Encabezados de origen adicionales permitidos en el endpoint MCP (separados por comas). Los dominios de Claude y las solicitudes sin encabezado de origen siempre están permitidos.

Instalación

npm install

Generar herramientas desde YAML OpenAPI

Ejecutar desde la especificación local:

npx tsx generate.ts

O desde URL remota:

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

Resultado esperado:

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

Crea:

generated/tools.json
generated/spec.json

Iniciar servidor

npx tsx server.ts

Inicio esperado (desarrollo — impresión bonita):

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

En producción (NODE_ENV=production) cada línea de registro es un único objeto JSON.

El servidor se vincula a:

http://0.0.0.0:3001

Probar todas las características

1. Comprobación de salud

curl http://localhost:3001/health

Esperado:

{
  "ok": true,
  "tools": 21,
  "redis": false,
  "uptime": 1.23
}

2. Listar herramientas

curl http://localhost:3001/tools

Esperado:

[
  "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_transcriptions",
  "browse_transcriptions",
  "show_transcription"
]

3. Llamada a herramienta

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

4. Mostrar un único registro

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

5. Transmisión SSE

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

Flujo esperado:

event: page
data: {...}

event: page
data: {...}

event: done
data: {}

6. Prueba de latido

Deje SSE abierto durante 15+ segundos: espere líneas periódicas de mantenimiento de conexión:

: heartbeat

7. Transmisión HTTP fragmentada

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

Esperado (JSON delimitado por nuevas líneas):

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

8. Inicialización MCP

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" }
  }
}'

9. Listar herramientas MCP

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"
}'

10. Llamada a herramienta MCP

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_records",
    "arguments": { "name": "Coret" }
  }
}'

Pruebas de Redis

Iniciar Redis

redis-server

Reinicie el servidor MCP. Esperado en /health:

{ "redis": true }

Sin Redis

Detenga Redis y reinicie. Esperado:

{ "redis": false }

Comandos comunes

Regenerar después de cambios en la API

npx tsx generate.ts

Reiniciar servidor

npx tsx server.ts

Ejecutar pruebas

npm test

Las pruebas cubren la estrategia TTL por herramienta (cache-ttl.ts) utilizando el ejecutor de pruebas integrado de Node: sin dependencias adicionales. La prueba de cobertura verifica que cada herramienta emitida por generate.ts tenga una entrada TTL explícita, por lo que volver a ejecutar npm run generate después de un cambio en la OpenAPI ascendente revelará cualquier herramienta nueva que necesite una decisión de TTL.

Solución de problemas

Archivos generados faltantes

npx tsx generate.ts

Puerto ya en uso

Linux / macOS:

lsof -i :3001
kill -9 <PID>

Windows:

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

Redis no se conecta

El servidor funciona normalmente sin Redis. Verifique REDIS_URL en .env.

Errores de límite de velocidad (429)

La API ascendente permite 4 solicitudes/segundo por IP. El limitador de velocidad integrado pone en cola las solicitudes automáticamente. Si ejecuta varias instancias del servidor, reduzca RATE_LIMIT_RPS o use una cola compartida.

Política de privacidad

Este servidor es un proxy ligero sobre la API pública de Open Archives. No requiere autenticación de usuario y no recopila datos personales propios. Las políticas de privacidad completas de los operadores se aplican además de esta sección:

Recopilación de datos

Argumentos de herramientas (p. ej., un nombre de búsqueda, un código de archivo, un identificador de registro) se reciben del cliente MCP.
Metadatos de solicitudes HTTP — método, ruta, código de estado, latencia y la IP de origen — son observados por el proxy inverso frente al endpoint alojado en mcp.openarchieven.nl.
No se recopilan cuentas, cookies, tokens ni identificadores de sesión. El servidor es anónimo por diseño.

Uso y almacenamiento

Los argumentos de herramientas se reenvían textualmente a través de HTTPS a https://api.openarchieven.nl/1.1 para cumplir con la solicitud, y la respuesta ascendente se devuelve al llamante.
Registros de aplicación (nombre de la herramienta, argumentos, estado, latencia) se escriben en stdout mediante pino. En el endpoint alojado, estos registros son efímeros: no se escriben en disco y se pierden al reiniciar el proceso. Establezca LOG_LEVEL=warn para suprimir el registro de argumentos.
Caché (opcional): cuando Redis está configurado, las respuestas ascendentes se almacenan en caché bajo claves de la forma mcp:<tool>:<sorted-params-json>. La caché contiene solo cuerpos de respuesta; no se almacenan identificadores de usuario.

Compartición con terceros

No se envían datos a ningún servicio que no sea la API ascendente de Open Archives mencionada anteriormente. No hay terceros involucrados en análisis, telemetría, publicidad ni observabilidad.

Retención de datos

Datos	Retención
Argumentos y respuestas de herramientas	No persistidos por la aplicación
Registros de aplicación	Efímeros (`stdout`, se pierden al reiniciar)
Entradas de caché de Redis	TTL por herramienta (6 horas – 7 días; las búsquedas históricas inmutables nunca expiran). Consulte Caché de Redis.
Registros de acceso del proxy inverso	Según la política de retención estándar del proveedor de alojamiento

Seguridad

El endpoint MCP valida el encabezado Origin en cada solicitud y rechaza orígenes de navegador desconocidos (defensa contra el rebinding de DNS). Todo el transporte es a través de HTTPS.

Enlaces externos mostrados a los clientes

Las respuestas de las herramientas incluyen URL que apuntan a páginas de registros en https://www.openarchieven.nl. La presentación declara el siguiente URI de enlace permitido para que los usuarios no reciban un aviso de confirmación por cada enlace:

https://www.openarchieven.nl

Contacto

Para preguntas o solicitudes de privacidad, contacte con:

Correo electrónico: genealogie@coret.org
GitHub: abra un issue

Actualizaciones recomendadas para producción

Proxy inverso HTTPS (nginx / caddy)
Gestor de procesos PM2 o systemd
Registro JSON estructurado (pino / winston)
Trazado de solicitudes (OpenTelemetry)
Middleware de autenticación si el servidor es de acceso público
Redis compartido para implementaciones de múltiples instancias

Versión

v1.0

Servidor MCP generado por OpenAPI con esquema perfecto para Open Archives.