Open Archives

Servidor MCP para o mecanismo de busca genealógica Open Archives.

Documentação

Servidor MCP Open Archives

Servidor híbrido MCP + HTTP + SSE de nível de produção gerado a partir da especificação OpenAPI do Open Archives. Abrange registros genealógicos (nascimentos, óbitos, casamentos, censos), estatísticas de arquivos, clima histórico e transcrições de páginas em texto completo de documentos históricos.

Fonte OpenAPI usada para gerar as ferramentas:

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

Visão Geral

Um servidor ciente de esquema que converte automaticamente a especificação OpenAPI em ferramentas chamáveis e as expõe por meio de múltiplos transportes:

MCP Remoto (JSON-RPC sobre StreamableHTTP)
API HTTP JSON
Streaming SSE com paginação automática
Streaming HTTP em blocos com paginação automática
Cache Redis (opcional)
Verificações de saúde

Uso com Claude

Adicionar como conector personalizado

Um endpoint hospedado está disponível — sem necessidade de instalação.

No claude.ai ou Claude Desktop:

Abra Configurações → Conectores.
Clique em Adicionar conector personalizado.
Insira a URL: https://mcp.openarchieven.nl/
Salve e aprove quando solicitado.

Nenhuma autenticação é necessária — Open Archives é um conjunto de dados público.

Exemplos de consultas

Depois que o conector for adicionado, você pode perguntar ao Claude, por exemplo:

"Quem são os ancestrais de Johannes Gregorius Marinus Coret? Dê-me uma visão geral, incluindo citações de fontes em formato markdown com links para os arquivos originais se possível, caso contrário forneça os links do Open Archieven e forneça uma árvore em SVG."
"Johannes Coret e Antonia Uphus tiveram descendentes? Dê-me uma visão geral, incluindo citações de fontes em formato markdown com links para os arquivos originais se possível, caso contrário forneça os links do Open Archieven, inclua miniaturas de digitalizações de fontes de arquivo se disponíveis e forneça uma árvore em SVG."
"Forneça-me uma lista de tipos de fonte por arquivo(nome) onde posso encontrar informações sobre a família Coret. Mostre o resultado em um documento markdown incluindo links para as páginas de busca no Open Archieven. Em vez do código do arquivo, use o ISIL se disponível."
"Como estava o tempo em Amsterdã em 01/02/1953?"
"O que o censo de 1850 diz sobre Utrecht?"

Claude chamará a ferramenta correspondente (search_records, show_record, get_marriages, get_historical_weather, get_census_data, …) e retornará links para as páginas de registro correspondentes em https://www.openarchieven.nl.

Auto-hospedado

O servidor fala MCP sobre Streamable HTTP; não há distribuição via stdio. Para executar sua própria instância:

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/

Aponte seu cliente MCP para http://localhost:3001/ (ou sua própria URL pública) da mesma forma que o endpoint hospedado acima.

Recursos Principais

Geração Automática via OpenAPI

Cada operação da API se torna uma ferramenta automaticamente via generate.ts.

Todas as 21 operações:

Nome da Ferramenta	Descrição
`search_records`	Buscar registros genealógicos
`show_record`	Exibir um único registro genealógico
`match_record`	Corresponder uma pessoa a registros de nascimento e óbito
`get_births_years_ago`	Listar nascimentos de N anos atrás
`get_births`	Encontrar registros de nascimento
`get_deaths`	Encontrar registros de óbito
`get_marriages`	Encontrar registros de casamento
`get_archives`	Listar todos os arquivos com estatísticas
`get_record_stats`	Contagem de registros por arquivo
`get_source_type_stats`	Contagem de registros por tipo de fonte
`get_event_type_stats`	Contagem de registros por tipo de evento
`get_comment_stats`	Estatísticas de contagem de comentários
`get_family_name_stats`	Frequência de sobrenomes
`get_first_name_stats`	Frequência de nomes próprios
`get_profession_stats`	Frequência de profissões
`get_breakdown`	Tabulação cruzada agrupada por arquivo, tipo de fonte, tipo de evento, local ou ano
`get_historical_weather`	Clima histórico do KNMI
`get_census_data`	Dados do censo holandês 1795–1899
`search_transcriptions`	Busca em texto completo nas transcrições de páginas de documentos históricos
`browse_transcriptions`	Navegar hierarquicamente pelas transcrições por arquivo de origem, número de arquivo ou inventário
`show_transcription`	Recuperar uma única transcrição de página por id

Nota: O parâmetro callback (JSONP) presente na API upstream é excluído de todas as ferramentas — é irrelevante em um contexto MCP/JSON-RPC.

Visualizador Interativo de Transcrições (App MCP)

Além das 21 ferramentas geradas automaticamente, o servidor registra uma ferramenta escrita manualmente — view_transcription — que abre páginas transcritas em um visualizador interativo de zoom profundo IIIF (OpenSeadragon) com o texto da transcrição ao lado, usando a extensão MCP Apps (io.modelcontextprotocol/ui).

Nome da Ferramenta	Descrição
`view_transcription`	Abrir uma ou mais páginas transcritas (`ids: ["NL-SdmGA_1504889_11", …]`) em um visualizador IIIF de zoom profundo com a transcrição; `highlight_term` opcional

Hosts compatíveis com Apps (Claude web/desktop, conectores personalizados pagos) renderizam o visualizador (ui://openarchieven/viewer.html) em um iframe com sandbox que carrega imagens diretamente dos hosts de imagens de transcrição (incluídos na allowlist CSP como *.transkribus.eu, *.archief.nl, *.archieven.nl, *.memorix.nl). Transkribus e o servidor iipsrv do archief.nl fornecem zoom profundo IIIF real; os hosts de miniaturas preserve*.archieven.nl renderizam como imagens planas.
Hosts simples recebem um fallback elegante: um resumo em texto com as URLs IIIF/fonte além de algumas imagens de pré-visualização inline.

O visualizador é um único dist/viewer.html autocontido, empacotado em tempo de build com npm run build:viewer (vite + vite-plugin-singlefile); ele não é listado pelo endpoint REST GET /tools, apenas via MCP tools/list.

Validação Perfeita de Esquema

Usa os esquemas de parâmetros reais do OpenAPI. Valida:

parâmetros obrigatórios
campos inteiros
campos numéricos
valores de enum
restrições de mínimo / máximo

Múltiplas Interfaces

MCP Remoto (StreamableHTTP)

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

Transporte JSON-RPC sem estado — uma nova instância do servidor MCP é criada por requisição.

Validação de origem: Requisições de navegador devem vir de claude.ai, claude.com, ou qualquer domínio listado em ALLOWED_ORIGINS. Requisições sem cabeçalho Origin (clientes MCP nativos, curl, servidor para servidor) são aceitas. Origens desconhecidas recebem HTTP 403.

HTTP JSON

GET  /tools
POST /tools/:name

Streaming SSE (com paginação automática)

GET /events/:name

Streaming HTTP em Blocos (com paginação automática)

POST /stream/:name

Metadados de Descoberta (`/.well-known`)

Arquivos JSON estáticos, editáveis manualmente, servidos verbatim de 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 e well-known/agent-card.json diretamente — sem necessidade de reiniciar (os arquivos são lidos a cada requisição). As respostas são enviadas com Content-Type: application/json; charset=utf-8 e Cache-Control: public, max-age=3600.

Paginação

Endpoints de streaming (/events/:name, /stream/:name) paginam automaticamente pelos resultados para endpoints que suportam um deslocamento start:

Incrementa start por number_show por página
Para quando os resultados são esgotados ou após 20 páginas (limite de segurança)
SSE envia um comentário : heartbeat a cada 10 segundos para manter as conexões ativas

Cache Redis

Suporte Redis opcional.

Se o Redis estiver em execução, as respostas upstream são armazenadas em cache com um TTL por ferramenta ajustado à volatilidade dos dados:

Categoria	TTL	Ferramentas
Histórico imutável	nunca expira	`get_historical_weather`, `get_census_data`
Metadados que mudam lentamente	7 dias	`get_archives`
Agregações de estatísticas	1 dia	`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 individuais	1 dia	`show_record`, `show_transcription`
Estilo busca	6 horas	`search_records`, `match_record`, `get_births`, `get_deaths`, `get_marriages`, `search_transcriptions`, `browse_transcriptions`
Vinculado a data	próximo meia-noite UTC	`get_births_years_ago`

CACHE_TTL (padrão 3600) é o fallback para qualquer ferramenta não presente no mapa acima.

Se o Redis estiver indisponível:

o servidor ainda funciona normalmente (modo degradado)

Limitação de Taxa

A API upstream impõe 4 requisições por segundo por IP. O servidor enfileira todas as chamadas upstream através de um limitador de taxa token-bucket (configurável via RATE_LIMIT_RPS).

Verificações de Saúde

GET /health

Arquivos do Projeto

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

Requisitos

Node.js 18+
npm
servidor Redis opcional

Configuração

Copie .env.example para .env e ajuste:

cp .env.example .env

Variável	Padrão	Descrição
`PORT`	`3001`	Porta HTTP
`OPENAPI_PATH`	`../api/openapi.yaml`	Caminho ou URL para a especificação OpenAPI
`UPSTREAM_BASE`	`https://api.openarchieven.nl/1.1`	URL base da API upstream
`RATE_LIMIT_RPS`	`4`	Requisições upstream por segundo
`REDIS_URL`	`redis://localhost:6379/5`	URL de conexão Redis (db 5)
`CACHE_TTL`	`3600`	TTL de cache fallback em segundos (usado para ferramentas não presentes no mapa por ferramenta; veja Cache Redis)
`LOG_LEVEL`	`info`	`trace` `debug` `info` `warn` `error` `fatal`
`NODE_ENV`	(não definido)	Defina como `production` para logs JSON (padrão: impressão formatada)
`ALLOWED_ORIGINS`	(vazio)	Cabeçalhos Origin extras permitidos no endpoint MCP (separados por vírgula). Domínios Claude e requisições sem cabeçalho Origin são sempre permitidos.

Instalação

npm install

Gerar Ferramentas a partir do YAML OpenAPI

Execute a partir da especificação local:

npx tsx generate.ts

Ou a partir de URL remota:

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

Resultado esperado:

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

Cria:

generated/tools.json
generated/spec.json

Iniciar Servidor

npx tsx server.ts

Inicialização esperada (desenvolvimento — impressão formatada):

[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"

Em produção (NODE_ENV=production) cada linha de log é um único objeto JSON.

O servidor vincula a:

http://0.0.0.0:3001

Testar Todos os Recursos

1. Verificação de Saúde

curl http://localhost:3001/health

Esperado:

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

2. Listar Ferramentas

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. Chamada de Ferramenta

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

4. Exibir um Ú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. Streaming SSE

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

Stream esperado:

event: page
data: {...}

event: page
data: {...}

event: done
data: {}

6. Teste de Heartbeat

Deixe o SSE aberto por 15+ segundos — espere linhas periódicas de keep-alive:

: heartbeat

7. Streaming HTTP em Blocos

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

Esperado (JSON delimitado por nova linha):

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

8. Inicialização 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 Ferramentas 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. Chamada de Ferramenta 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" }
  }
}'

Teste do Redis

Iniciar Redis

redis-server

Reinicie o servidor MCP. Esperado em /health:

{ "redis": true }

Sem Redis

Pare o Redis e reinicie. Esperado:

{ "redis": false }

Comandos Comuns

Regenerar após mudanças na API

npx tsx generate.ts

Reiniciar servidor

npx tsx server.ts

Executar testes

npm test

Os testes cobrem a estratégia de TTL por ferramenta (cache-ttl.ts) usando o executor de testes integrado do Node — sem dependências extras. O teste de cobertura verifica que toda ferramenta emitida por generate.ts tem uma entrada TTL explícita, então re-executar npm run generate após uma mudança no OpenAPI upstream revelará qualquer nova ferramenta que precise de uma decisão de TTL.

Solução de Problemas

Arquivos gerados ausentes

npx tsx generate.ts

Porta já em uso

Linux / macOS:

lsof -i :3001
kill -9 <PID>

Windows:

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

Redis não conectando

O servidor funciona normalmente sem Redis. Verifique REDIS_URL em .env.

Erros de limite de taxa (429)

A API upstream permite 4 req/s por IP. O limitador de taxa integrado enfileira requisições automaticamente. Se você estiver executando múltiplas instâncias do servidor, reduza RATE_LIMIT_RPS ou use uma fila compartilhada.

Política de Privacidade

Este servidor é um proxy leve sobre a API pública do Open Archives. Não requer autenticação de usuário e não coleta dados pessoais próprios. As políticas de privacidade completas dos operadores se aplicam além desta seção:

Coleta de dados

Argumentos de ferramentas (por exemplo, um nome de busca, um código de arquivo, um identificador de registro) são recebidos do cliente MCP.
Metadados de requisição HTTP — método, caminho, código de status, latência e IP de origem — são observados pelo proxy reverso em frente ao endpoint hospedado em mcp.openarchieven.nl.
Nenhuma conta, cookie, token ou identificador de sessão é coletado. O servidor é anônimo por design.

Uso e armazenamento

Os argumentos das ferramentas são encaminhados literalmente via HTTPS para https://api.openarchieven.nl/1.1 para atender à requisição, e a resposta upstream é retornada ao chamador.
Logs de aplicação (nome da ferramenta, argumentos, status, latência) são gravados em stdout via pino. No endpoint hospedado, esses logs são efêmeros: não são gravados em disco e são perdidos na reinicialização do processo. Defina LOG_LEVEL=warn para suprimir o registro de argumentos.
Cache (opcional): quando o Redis está configurado, as respostas upstream são armazenadas em cache sob chaves no formato mcp:<tool>:<sorted-params-json>. O cache contém apenas corpos de resposta; nenhum identificador de usuário é armazenado.

Compartilhamento com terceiros

Nenhum dado é enviado a qualquer serviço além da API upstream Open Archives listada acima. Não há terceiros envolvidos em analytics, telemetria, publicidade ou observabilidade.

Retenção de dados

Dados	Retenção
Argumentos e respostas de ferramentas	Não persistidos pela aplicação
Logs de aplicação	Efêmeros (`stdout`, perdidos na reinicialização)
Entradas de cache Redis	TTL por ferramenta (6 horas – 7 dias; consultas históricas imutáveis nunca expiram). Veja Redis Cache.
Logs de acesso do proxy reverso	Conforme a política de retenção padrão do provedor de hospedagem

Segurança

O endpoint MCP valida o cabeçalho Origin em cada requisição e rejeita origens de navegador desconhecidas (defesa contra DNS rebinding). Todo o transporte é via HTTPS.

Links externos exibidos aos clientes

As respostas das ferramentas incluem URLs que apontam para páginas de registros em https://www.openarchieven.nl. A submissão declara o seguinte URI de link permitido para que os usuários não sejam solicitados a confirmar cada link:

https://www.openarchieven.nl

Contato

Para dúvidas ou solicitações de privacidade, entre em contato:

Email: genealogie@coret.org
GitHub: abra uma issue

Atualizações de Produção Recomendadas

Proxy reverso HTTPS (nginx / caddy)
Gerenciador de processos PM2 ou systemd
Registro estruturado em JSON (pino / winston)
Rastreamento de requisições (OpenTelemetry)
Middleware de autenticação se o servidor for público
Redis compartilhado para implantações multi-instância

Versão

v1.0

Servidor MCP gerado por OpenAPI com schema perfeito para Open Archives.