Skip to main content
Glama

fornsok-mcp

En MCP-server (Model Context Protocol) som ger läsåtkomst till Riksantikvarieämbetets kulturmiljöregister – det som visas i Fornsök: fornlämningar och andra kulturhistoriska lämningar i Sverige. Servern är skriven i TypeScript för Cloudflare Workers och är tillståndslös: en enda ändpunkt, /mcp, över Streamable HTTP.

Projektet är under uppbyggnad (etapp 4–6). Sökning, närhetssök, statistik och grundposten går mot ett eget index över hela registret i Cloudflare D1, laddat från RAÄ:s GeoPackage-uttag och uppdaterat nattligen via RAÄ:s ändringsflöde. Inom ett semantiskt omfång (Dalarnas län) kan sökningen också gå på frågans innebörd (Vectorize och Workers AI). Saknas indexet, är det tomt eller fallerar ett indexanrop, används RAÄ:s levande källor (reservläge). Inventeringsböcker, dokument och historik hämtas alltid från de levande källorna. Servern är förberedd för drift bakom Cloudflare Access. SPEC.md beskriver hela planen.

Verktyg

Verktyg

Vad det gör

sok_lamningar

Sök med fritext och filter: lämningsnummer eller RAÄ-nummer, lämningstyp, kategori, antikvarisk bedömning, kommun, socken, landskap, län, egenskap (t.ex. Material = Koppar) och område (nara, med avstånd till närmaste punkt på geometrin). Ger nummer, typ, bedömning, indelning, koordinat, lägesosäkerhet, ett utdrag på cirka 200 tecken runt träffen och länk. Svaret anger sokkanaler, hamtad_fran och reservlage.

lamningar_nara

Lämningar närmast en punkt (lat/lon i WGS 84) inom en radie, eller inom en ruta. Avståndet räknas till närmaste punkt på lämningens geometri (punkt, linje eller yta), med väderstreck.

lamning

Hela posten för 1–10 lämningar, på lämningsnummer, RAÄ-nummer, UUID eller K-samsök-URI. Grundposten ur indexet; valfritt med geometri (GeoJSON), referenser, dokument (med dokument_ref) och versionshistorik, som hämtas från Fornsök-appen. Ett RAÄ-nummer som delas av flera lämningar ger alla.

lamning_dokument

Dokumenten för en lämning: inventeringsboksuppslag, händelseloggar, bilder och maritim dokumentation, var och en med en dokument_ref.

hamta_dokument

Hämtar ett dokument via dokument_ref. JPEG och PNG upp till 2 MB kommer som bild i svaret (så att en inventeringsbokssida kan läsas direkt); större filer och PDF som länk med metadata.

statistik

Antal lämningar per lämningstyp, kategori, bedömning, län, kommun, socken eller landskap, i en eller två nivåer, med samma filter som sok_lamningar. Högst 200 rader. Kräver indexet.

uppslag

Värdelistor: lämningstyper med kategori, kategorier, bedömningar, egenskapstyper med värden och antal (ur indexet), kommuner, socknar, landskap och län.

hitta_plats

Ortnamn till koordinat: först socknar, kommuner och namngivna lämningar i indexet, sedan OpenStreetMap Nominatim (bara Sverige, högst ett anrop per sekund, svar sparas 30 dygn). Koordinaten kan skickas till lamningar_nara.

Alla verktyg är läsande. Svaren har både läsbar text och structuredContent enligt ett outputSchema. Namn på kommuner, socknar, typer, län och egenskaper slås upp skiftlägesokänsligt; okända namn ger ett fel med närmaste förslag, och en socken som finns i flera län ger en lista att välja ur.

Ordsökningen

Fritexten söks med SQLite FTS5 över typ, namn, beskrivning, tradition och terräng. Alla ord måste finnas (OCH), i valfri ordning och kolumn. Det finns ingen stamning: "källa" hittar inte "källan". Pröva flera böjningsformer, synonymer och äldre stavningar, och använd prefix med * (hytt* hittar hytta, hyttan, hyttområde). Å, ä och ö skiljs från a och o. Träffarna rangordnas med bm25 (typ och namn väger tyngst). Lämnings- och RAÄ-nummer i fritexten söks som nummer.

Semantisk sökning

När bindningarna AI och VECTORIZE finns söker sok_lamningar också på frågans innebörd, men bara när frågans geografiska filter (län, kommun, socken, landskap eller nara) ligger helt inom det semantiska omfånget (SEMANTIC_LAN, standard Dalarna). Rikstäckande frågor och frågor utanför omfånget får bara ordsök, så att de inte får slagsida mot omfånget.

  • lage: "auto" (standard): ordsök och semantisk sökning parallellt; rangordningarna slås ihop med reciprocal rank fusion (src/search/fusion.ts). Varje träff anger kanaler, svaret sokkanaler.

  • lage: "betydelse": bara semantisk sökning. Utanför omfånget, eller utan geografiskt filter, ger den ett fel som förklarar var den gäller.

  • lage: "ord": bara ordsök.

Semantiska träffar kontrolleras alltid mot hela filtret i indexet. Faller den semantiska kanalen blir "auto" ordsök med en anmärkning. Inbäddningen (@cf/baai/bge-m3) görs av de schemalagda körningarna, i delar, tills omfånget är inbäddat; fram till dess ger den semantiska kanalen färre träffar. Utan AI/VECTORIZE är "auto" ordsök och "betydelse" ger ett tydligt fel.

Schemalagda körningar

src/scheduled.ts, med Cron Triggers i wrangler.local.example.jsonc:

Cron

Gör

40 3-6 * * *

Nattsynk (src/sync/): gårdagens ändringar ur RAÄ:s ändringsflöde, varje ändrad lämning hämtas från Fornsök-appen (reserv K-samsök) och skrivs till D1. Fyra tillfällen per natt, så att en lång körning fortsätter där den slutade. Därefter inbäddning.

*/15 * * * *

Inbäddning (src/semantic/): högst 1 500 lämningar per körning, tills omfånget är inbäddat; sedan bara ändrade poster.

Utan DB görs ingenting; utan AI eller VECTORIZE ingen inbäddning. Ett fel i synken hindrar inte inbäddningen. Varje körning skriver en loggrad. Den schemalagda vägen har ingen HTTP-förfrågan och går inte genom Access-kontrollen; fetch-vägen är skyddad som förut.

Indexet och reservläget

Läge

sok_lamningar

lamningar_nara

lamning

statistik, egenskapsfilter

Indexet laddat

Indexet

Indexet (exakt avstånd)

Grundpost ur indexet; referenser, dokument, historik från Fornsök-appen. Poster som saknas i indexet hämtas från appen

Indexet

Ingen DB-bindning, tomt index eller fel i ett indexanrop

K-samsök

OGC API Features

Fornsök-appen, K-samsök som reserv

Tydligt fel

hamtad_fran säger varifrån svaret kom och hur färskt det är: index 2026-11-17 (GeoPackage-uttagets datum, eller nattsynkens datum synk_status.senast_synkat när det är senare), eller t.ex. K-samsök (reservläge: indexet är tomt (inte laddat)), data byggd 2026-11-14. reservlage: true och en anmärkning märker svaret. Efter ett fel i ett indexanrop används reserven i 15 sekunder innan indexet prövas igen; läget (laddat, datum) kontrolleras högst en gång per minut och isolat.

I mycket täta områden prövas högst 5 000 kandidater med exakt avstånd, de närmaste först; svaret anger då radien inom vilken det är fullständigt. Högst 10 000 träffar går att bläddra till (nabara).

dokument_ref är en ogenomskinlig referens som servern skapar. Den valideras strikt, och filen slås upp på nytt i lämningens dokumentlista innan något hämtas; bara filer i den listan kan nås, och bara via dokumentändpunkten. Innan en bild skickas kontrolleras storlek (enligt listan, Content-Length och faktiskt läst mängd), innehållstyp och filsignatur. Versionshistoriken visar publicerade versioner med åtgärd eller uppdrag, inte vad som ändrades.

Related MCP server: Apiverket MCP Server

Källor

Källa

Används till

Status

RAÄ:s GeoPackage-uttag

Indexet (grundladdning och avstämning, se ingest/)

Officiell, öppen, CC0

RAÄ:s ändringsflöde (pub.raa.se/datauttag/lamningar)

Nattsynken: vilka lämningar som ändrats

Officiell, öppen, CC0

OpenStreetMap Nominatim

hitta_plats när indexet saknar namnet

Öppen, ODbL; högst 1 anrop/s, identifierande User-Agent

K-samsök (kulturarvsdata.se/ksamsok/api)

Reserv för sök och nummeruppslag, reserv för hela posten (JSON-LD)

Officiell, öppen, CC0

RAÄ:s OGC API Features

Reserv för närhetssök (ruta + CQL2-filter)

Officiell, öppen, CC0

Fornsök-appens läs-API (app.raa.se/open/fornsok/api)

Hela posten, värdelistor, dokument och filer, versionshistorik

Odokumenterat och inofficiellt – se nedan

All data kommer från Riksantikvarieämbetet, Kulturmiljöregistret, och är CC0. Beskrivningarna i registret är inte kvalitetssäkrade, och den antikvariska bedömningen är registrets – det är länsstyrelsen som avgör i det enskilda fallet. Svaren ska inte användas som underlag för markarbeten. K-samsök ligger några dagar efter registret.

Om Fornsök-appens läs-API

Fornsök-appens API är inte dokumenterat och inte avsett som ett öppet gränssnitt. Det kan ändras eller stängas utan förvarning, och det ska användas sparsamt:

  • Servern anropar bara ett fåtal uttryckligen listade läsanrop: en post, dess dokumentlista, dess versionshistorik och en bildfil i taget, samt värdelistorna. Värdelistorna cachas (24 h i KV, 1 h i minnet) och dokumentlistorna 1 h i KV. Samma bas-URL har skrivande ändpunkter; en fast lista över tillåtna anrop (src/upstream/allowlist.ts) gör att de aldrig kan nås. Filändpunkten är dessutom begränsad till JPEG/PNG – andra filer hämtas aldrig av servern, de ges som länk.

  • Högst fyra samtidiga anrop per källa, tidsgräns 10 s, ett omförsök vid 5xx/429, och en identifierande User-Agent med kontaktväg.

  • Massuttag ska aldrig göras via appen. För hela registret finns RAÄ:s öppna GeoPackage-uttag.

  • Om appen inte svarar hämtas posten från K-samsök i stället, med färre fält.

Kör du en egen instans: sätt din egen kontaktväg (se Inställningar) och fråga RAÄ innan servern öppnas för fler än några få användare.

Köra lokalt

Kräver Node 22 och npm. Ingen Cloudflare-inloggning behövs för lokal körning.

Servern kräver alltid en giltig Cloudflare Access-JWT (se Åtkomst). Lokalt slås ett utvecklingsläge på i en ospårad .dev.vars:

npm install
echo 'ACCESS_DEV_BYPASS=true' > .dev.vars
npm run dev            # wrangler dev, servern svarar på http://localhost:8787/mcp

Utan D1-bindning går allt mot de levande källorna (reservläge). Med ett lokalt index (Falu kommun räcker för att prova) i en ospårad konfiguration med d1_databases-bindningen DB (se wrangler.local.example.jsonc; för lokal körning räcker database_name, database_id kan vara vilket värde som helst):

curl -fo ingest/.cache/falun.gpkg 'https://pub.raa.se/nedladdning/datauttag/lamningar_v1/kommun/l%c3%a4mningar_kommun_falun.gpkg'
npm run ingest -- sql ingest/.cache/falun.gpkg --ut ingest/out/falun
npx wrangler d1 migrations apply fornsok --local -c <din lokala konfiguration>   # 0001 och 0002
for f in ingest/out/falun/*.sql; do npx wrangler d1 execute fornsok --local -c <din lokala konfiguration> --file "$f" -y; done
npx wrangler dev -c <din lokala konfiguration>

Prova med en MCP-klient, till exempel MCP Inspector mot http://localhost:8787/mcp, eller med det medföljande röktestet (gör ett femtontal riktiga anrop mot RAÄ, bland annat hämtning av ett inventeringsboksuppslag; med --index kontrolleras också att indexet används, att statistik svarar och att posterna kommer ur indexet):

node scripts/smoke.mjs http://localhost:8787/mcp
node scripts/smoke.mjs --index http://localhost:8787/mcp             # med lokalt index (Falun)
node scripts/smoke.mjs --index --semantisk <url>                    # mot driftsatt server med AI/Vectorize
node scripts/smoke.mjs --utan-inloggning http://localhost:8787/mcp   # utan .dev.vars: allt ska ge 401

Tester och typkontroll:

npm test               # vitest, mot inspelade svar i test/fixtures – inga nätverksanrop
npm run type-check     # src/, test/ och ingest/

Åtkomst

Servern är tänkt att köras bakom Cloudflare Access och innehåller ingen egen inloggning. Workern litar ändå inte på att Access sitter framför: allra först, före all routing, verifieras Cf-Access-Jwt-Assertion (signatur mot teamets nycklar, aud, iss, giltighetstid) i src/auth/access.ts. Utan giltig JWT blir svaret 401 – för alla sökvägar, och även när Access-inställningarna saknas.

Utvecklingsläget (ACCESS_DEV_BYPASS="true", bara i .dev.vars) hoppar över kontrollen, men bara för anrop till localhost/127.0.0.1/[::1] som saknar cf-ray (som alla anrop via Cloudflares edge bär). Det är kontrollerat mot wrangler dev: där saknas cf-ray och adressen är http://localhost:<port>; ett anrop med annan Host eller med cf-ray kräver JWT.

Efter inloggningen begränsas varje användare (e-post ur JWT:n, eller common_name för tjänstetoken) med Workers Rate Limiting-bindning, förslagsvis 120 anrop per minut. Över gränsen blir svaret 429 med Retry-After: 60 och ett JSON-RPC-fel på svenska. Cloudflare räknar ungefärligt och per plats. Saknas bindningen begränsas inget.

Driftsättning

Den spårade wrangler.jsonc är för lokal utveckling och saknar medvetet allt kontospecifikt. För drift:

  1. Kopiera wrangler.local.example.jsonc till wrangler.local.jsonc (ospårad, står i .gitignore) och fyll i alla platshållare: konto-id, värdnamn (Workers Custom Domain), kontaktväg, Access-teamdomän och AUD-tagg, ett namespace_id för begränsningen, samt id:n för KV (och D1/Vectorize, som används från en senare etapp).

  2. npx wrangler deploy -c wrangler.local.jsonc

workers_dev och förhandsadresser är avstängda, så Workern nås bara via den egna domänen bakom Access. DB är indexet; utan det går servern i reservläge mot de levande källorna. VECTORIZE och AI ger semantisk sökning. Utan CACHE cachas bara i minnet. Migreringarna (migrations/0001_init.sql, 0002_synk_semantik.sql) körs med npx wrangler d1 migrations apply <databas> --remote -c wrangler.local.jsonc.

Indexet laddas från din dator (se kommentaren överst i ingest/cli.ts): npm run ingest -- sql <fil.gpkg> --ut <katalog> skriver idempotenta SQL-filer som körs med wrangler d1 execute --remote --file. Inläsningen stämmer av antalet rader mot källfilen och avbryter med fel om någon lämning tappats.

Inställningar

Inställning

Var

Standard

CONTACT_URL

vars

Projektets förvar på GitHub. Hamnar i User-Agent mot RAÄ: fornsok-mcp/0.1 (+<CONTACT_URL>). Sätt din egen vid driftsättning.

ACCESS_TEAM_DOMAIN, ACCESS_AUD

vars i wrangler.local.jsonc

Saknas – då svarar Workern 401 på allt.

ACCESS_DEV_BYPASS

bara .dev.vars

Av. "true" slår på utvecklingsläget (bara localhost).

RATE_LIMITER

ratelimits i wrangler.local.jsonc

Saknas – ingen begränsning. Håll gränsen i takt med RATE_LIMIT_PER_MINUTE i src/config.ts.

CACHE

kv_namespaces i wrangler.local.jsonc

Saknas – bara minnescache.

DB

d1_databases i wrangler.local.jsonc

Saknas – reservläge (levande källor), ingen statistik, ingen nattsynk.

AI, VECTORIZE

ai, vectorize i wrangler.local.jsonc

Saknas – bara ordsök, ingen inbäddning.

SEMANTIC_LAN

vars

Dalarna. Län i det semantiska omfånget, kommaseparerat.

NOMINATIM

vars

På. "av" stänger av Nominatim i hitta_plats (då bara indexets namn).

triggers.crons

wrangler.local.jsonc

["40 3-6 * * *", "*/15 * * * *"] (se Schemalagda körningar).

CONTACT_URL (miljövariabel)

ingest/referens.ts

Projektets förvar. Kontaktväg i User-Agent när referensdata hämtas från K-samsök.

Inga API-nycklar behövs för källorna. Hemligheter och kontospecifika värden (konto-id, domäner, Access-uppgifter) hör inte hemma i spårade filer; wrangler.local.jsonc, .dev.vars, .dev.env, .env.cloudflare och .local/ är undantagna i .gitignore.

Struktur

src/
  index.ts              Worker: Access-JWT först, sedan begränsning per användare, sedan bara /mcp
  env.ts                Workerns miljö (inställningar och valfria bindningar)
  auth/                 Access-JWT (access.ts) och begränsning per användare (ratelimit.ts)
  cache/                KV-cache för värdelistor och dokumentlistor
  server.ts             McpServer med instruktioner och de åtta verktygen
  scheduled.ts          Schemalagda körningar: nattsynk och inbäddning
  sync/                 Nattsynk via RAÄ:s ändringsflöde
  semantic/             Inbäddning och semantisk sökning (Workers AI, Vectorize)
  deps.ts               Kopplar förmågorna till källorna (index, levande källor, semantisk kanal)
  tools/                Verktygen (scheman, text- och strukturerade svar); via_index.ts väljer index eller reserv
  store/                Indexet i D1: sök, närhet, grundpost, statistik (index.ts), läge och reserv (access.ts)
  search/               Sammanslagning av rangordningar (reciprocal rank fusion)
  sources/              Ett gränssnitt per förmåga, en implementation per källa
    ksamsok/            Frågebyggare och tolkning av K-samsök
    ogc/                OGC API Features och CQL2
    fornsokapp/         Fornsök-appens läs-API
  upstream/             Den enda vägen ut: tillåtna anrop, tidsgräns, omförsök, samtidighet
  lookup/               Värdelistor (cachade) och namnuppslag, fast länstabell
  geo/                  SWEREF 99 TM ⇄ WGS 84, avstånd till geometri, GML
ingest/                 Inläsning av GeoPackage till indexet (Node 22, körs med npm run ingest)
migrations/             D1-schemat
test/                   vitest; inspelade svar under test/fixtures, indexet mot Falu kommun
scripts/smoke.mjs       Röktest mot en körande server (även --utan-inloggning)
wrangler.local.example.jsonc  Mall för driftkonfigurationen (platshållare)

Licens

Ingen licens är vald än; tills vidare gäller full upphovsrätt för koden. Registerdata från RAÄ, även de inspelade testsvaren, är CC0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables users to search and access digital collections from the Swedish National Archives (Riksarkivet) through multiple APIs. Supports searching records by keywords, exploring collections, and downloading historical images and documents.
      2
      27
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Query Swedish public data from AI tools. Includes company data, SCB statistics, weather, transport, public agencies, and more through the Apiverket API.
      2
      53 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables full-text search and retrieval of Kansallisarkisto's machine-transcribed archival corpora, including medieval charters from Diplomatarium Fennicum, with filters and stemming support.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to find, read, and cite digitized primary sources published via IIIF — searching several institutions' catalogues, resolving item pages to manifests, pulling page images or regions for vision models, and generating citations with rights and provenance. Runs read-only over stateless Streamable HTTP with no login.
      AGPL 3.0