lobid-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Lerche
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# lobid-mcp
+
+Tiny, deterministic, LLM-facing MCP server for semantic reconciliation against the GND authority ecosystem via `lobid` + the GND reconciliation API.
+
+Designed for local MCP clients such as:
+- Claude Code
+- Claude Desktop
+- OpenCode
+- Cursor
+
+Typical workflow:
+1. provide ambiguous names, concepts, or Schlagwörter
+2. MCP returns plausible GND candidates
+3. LLM compares and interprets the results
+4. optionally retrieve enriched authority records
+
+The MCP intentionally stays:
+- tiny
+- deterministic
+- stdio-only
+- token-aware
+- additive instead of transformative
+- KISS/YAGNI-first
+
+## Tools
+
+- `match_gnd_entities`
+- `get_gnd_record`
+- `get_gnd_records`
+
+## Install
+
+No local clone required.
+
+Run directly via `npx`:
+
+```bash
+npx lobid-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g lobid-mcp
+```
+
+Then run:
+
+```bash
+lobid-mcp
+```
+
+## Claude Desktop / OpenCode config
+
+Example MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "lobid-gnd": {
+      "command": "npx",
+      "args": ["lobid-mcp"]
+    }
+  }
+}
+```
+
+## Local development
+
+```bash
+pnpm install
+pnpm build
+pnpm start
+```
+
+## Example prompts
+
+- "Find likely GND entities for the following Schlagwörter"
+- "Search the GND for these ambiguous author names"
+- "Resolve these historical concepts against the GND"
+- "Find plausible GND subject headings for these terms"
+
+## Example `match_gnd_entities`
+
+```json
+{
+  "terms": [
+    "Goethe",
+    "Kafka",
+    "Thomas Mann"
+  ],
+  "limitPerTerm": 5,
+  "entityTypes": [
+    "Person"
+  ]
+}
+```
+
+## Example `get_gnd_records`
+
+```json
+{
+  "ids": [
+    "118540238",
+    "118560239"
+  ]
+}
+```
+
+## Deployment checklist
+
+### Push code to GitHub
+
+```bash
+git status
+git add .
+git commit -m "feat: improve lobid MCP"
+git push
+```
+
+### Publish to npm
+
+Make sure you are logged into npm:
+
+```bash
+npm login
+```
+
+Build the package:
+
+```bash
+pnpm build
+```
+
+Optionally inspect the package contents:
+
+```bash
+npm pack --dry-run
+```
+
+Publish:
+
+```bash
+npm publish
+```
+
+### Verify installation
+
+Test from a clean shell:
+
+```bash
+npx lobid-mcp
+```
+
+Or in Claude Desktop/OpenCode:
+
+```json
+{
+  "mcpServers": {
+    "lobid-gnd": {
+      "command": "npx",
+      "args": ["lobid-mcp"]
+    }
+  }
+}
+```

package/build/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { getGndEntry, matchGndEntities } from "./lobid.js";
+const server = new McpServer({
+    name: "lobid-mcp",
+    version: "1.0.0",
+});
+function jsonContent(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function errorContent(error) {
+    const message = error instanceof Error ? error.message : "unknown MCP error";
+    return jsonContent({
+        error: {
+            message,
+        },
+    });
+}
+server.registerTool("match_gnd_entities", {
+    description: "Search the GND authority ecosystem for plausible entities matching one or more names, concepts, subjects, organizations, places, or works. Use this tool first when resolving ambiguous terms against the GND. If no useful candidates are returned, retry with alternative spellings, singular forms, or related concepts.",
+    inputSchema: z.object({
+        terms: z.array(z.string().min(1).max(200)).min(1).max(50).describe("Research terms to match against GND"),
+        limitPerTerm: z.number().min(1).max(20).optional().default(5),
+        entityTypes: z
+            .array(z.string().min(1).max(100))
+            .max(20)
+            .optional()
+            .describe("Optional GND type filters such as Person, SubjectHeading, PlaceOrGeographicName, or CorporateBody"),
+    }),
+}, async ({ terms, limitPerTerm, entityTypes }) => {
+    try {
+        return jsonContent({
+            matches: await matchGndEntities(terms, limitPerTerm, entityTypes),
+        });
+    }
+    catch (error) {
+        console.error("match_gnd_entities failed", error);
+        return errorContent(error);
+    }
+});
+server.registerTool("get_gnd_record", {
+    description: "Retrieve a compact enriched GND authority record by identifier or canonical GND URL. Use this after candidate matching when additional semantic context is needed.",
+    inputSchema: z.object({
+        id: z.string().min(1).max(200).describe("GND identifier or full GND URL"),
+    }),
+}, async ({ id }) => {
+    try {
+        return jsonContent(await getGndEntry(id));
+    }
+    catch (error) {
+        console.error("get_gnd_record failed", error);
+        return errorContent(error);
+    }
+});
+server.registerTool("get_gnd_records", {
+    description: "Retrieve multiple compact enriched GND authority records by identifier or canonical GND URL. Use this to reduce repeated MCP roundtrips when inspecting several entities.",
+    inputSchema: z.object({
+        ids: z
+            .array(z.string().min(1).max(200))
+            .min(1)
+            .max(50)
+            .describe("GND identifiers or canonical GND URLs"),
+    }),
+}, async ({ ids }) => {
+    try {
+        return jsonContent({
+            records: await Promise.all(ids.map((id) => getGndEntry(id))),
+        });
+    }
+    catch (error) {
+        console.error("get_gnd_records failed", error);
+        return errorContent(error);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/build/lobid.js

@@ -0,0 +1,161 @@
+const GND_BASE = "https://lobid.org/gnd";
+const RECONCILE_BASE = "https://reconcile.gnd.network/gnd/reconcile/";
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_CONCURRENT_FETCHES = 10;
+const MAX_VARIANT_NAMES = 5;
+const MAX_BIOGRAPHICAL_ENTRIES = 2;
+const MAX_TEXT_LENGTH = 240;
+const MAX_ENTITY_REFERENCES = 5;
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const gndEntryCache = new Map();
+export async function getGndEntry(id) {
+    const url = normalizeGndUrl(id);
+    const cached = gndEntryCache.get(url);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+    }
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`lobid-gnd lookup failed: ${res.status} ${res.statusText}`);
+    }
+    const entry = (await res.json());
+    const compactEntry = compactGndEntry(entry);
+    gndEntryCache.set(url, {
+        expiresAt: Date.now() + CACHE_TTL_MS,
+        value: compactEntry,
+    });
+    return compactEntry;
+}
+export async function matchGndEntities(terms, limitPerTerm = 5, entityTypes) {
+    const url = new URL(RECONCILE_BASE);
+    url.searchParams.set("queries", JSON.stringify(Object.fromEntries(terms.map((term, index) => [`q${index}`, { query: term, limit: limitPerTerm }]))));
+    const res = await fetch(url.toString(), {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`gnd reconcile failed: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    return Promise.all(terms.map(async (term, index) => {
+        const candidates = data[`q${index}`]?.result ?? [];
+        const results = [];
+        for (let offset = 0; offset < candidates.length; offset += MAX_CONCURRENT_FETCHES) {
+            const chunk = candidates.slice(offset, offset + MAX_CONCURRENT_FETCHES);
+            const enriched = await Promise.all(chunk.map(async (candidate) => {
+                try {
+                    const entry = await getGndEntry(candidate.id);
+                    const summary = buildSummary(entry);
+                    return {
+                        gndId: entry.gndIdentifier || candidate.id,
+                        preferredName: entry.preferredName || candidate.name,
+                        type: entry.type.filter((t) => t !== "AuthorityResource").sort(),
+                        score: candidate.score,
+                        variantName: truncateArray(entry.variantName ?? [], MAX_VARIANT_NAMES).sort(),
+                        id: entry.id,
+                        ...(summary ? { summary } : {}),
+                        confidence: buildConfidence(candidate.score),
+                        matchSignals: buildMatchSignals(entry, candidate.name),
+                    };
+                }
+                catch (error) {
+                    console.error(`Failed to enrich GND candidate ${candidate.id}:`, error);
+                    return null;
+                }
+            }));
+            results.push(...enriched.filter((candidate) => candidate !== null && matchesEntityTypes(candidate.type, entityTypes)));
+        }
+        return {
+            query: term,
+            candidates: results,
+        };
+    }));
+}
+function matchesEntityTypes(candidateTypes, entityTypes) {
+    if (!entityTypes?.length) {
+        return true;
+    }
+    const normalizedFilters = entityTypes.map((type) => type.toLowerCase());
+    return candidateTypes.some((candidateType) => normalizedFilters.some((filter) => candidateType.toLowerCase().includes(filter)));
+}
+function normalizeGndUrl(id) {
+    if (!id.startsWith("http")) {
+        return `${GND_BASE}/${id}.json`;
+    }
+    const url = new URL(id);
+    const hostname = url.hostname.replace(/\.$/, "");
+    if (!["lobid.org", "d-nb.info"].includes(hostname)) {
+        throw new Error(`unsupported GND host: ${hostname}`);
+    }
+    if (!url.pathname.startsWith("/gnd/")) {
+        throw new Error("only /gnd/ URLs supported");
+    }
+    if (url.search || url.hash) {
+        throw new Error("query parameters and fragments not allowed in GND URLs");
+    }
+    return `${url.origin}${url.pathname.endsWith(".json") ? url.pathname : `${url.pathname}.json`}`;
+}
+function buildDescription(entry) {
+    return [
+        entry.professionOrOccupation?.map((item) => item.label).join(", "),
+        [entry.dateOfBirth, entry.dateOfDeath].filter(Boolean).join("-"),
+    ]
+        .filter(Boolean)
+        .join(" | ");
+}
+function compactGndEntry(entry) {
+    return {
+        ...entry,
+        type: [...entry.type].sort(),
+        variantName: truncateArray(entry.variantName ?? [], MAX_VARIANT_NAMES).sort(),
+        biographicalOrHistoricalInformation: truncateArray((entry.biographicalOrHistoricalInformation ?? []).map(truncateText), MAX_BIOGRAPHICAL_ENTRIES),
+        professionOrOccupation: truncateArray(entry.professionOrOccupation ?? [], MAX_ENTITY_REFERENCES),
+        placeOfBirth: truncateArray(entry.placeOfBirth ?? [], MAX_ENTITY_REFERENCES),
+        placeOfDeath: truncateArray(entry.placeOfDeath ?? [], MAX_ENTITY_REFERENCES),
+        summary: buildSummary(entry),
+    };
+}
+function buildSummary(entry) {
+    const summary = [
+        buildDescription(entry),
+        truncateArray(entry.biographicalOrHistoricalInformation ?? [], MAX_BIOGRAPHICAL_ENTRIES).join(" | "),
+    ]
+        .filter(Boolean)
+        .join(" | ");
+    return truncateText(summary);
+}
+function buildConfidence(score) {
+    if (score >= 90) {
+        return "high";
+    }
+    if (score >= 60) {
+        return "medium";
+    }
+    return "low";
+}
+function buildMatchSignals(entry, candidateName) {
+    const signals = [];
+    if (entry.preferredName?.toLowerCase() === candidateName.toLowerCase()) {
+        signals.push("exact preferred name");
+    }
+    if (entry.variantName?.length) {
+        signals.push("variant names available");
+    }
+    if (entry.type.some((type) => type !== "AuthorityResource")) {
+        signals.push("entity type available");
+    }
+    if (entry.dateOfBirth || entry.dateOfDeath) {
+        signals.push("lifespan available");
+    }
+    return signals;
+}
+function truncateArray(items, limit) {
+    return items.slice(0, limit);
+}
+function truncateText(text) {
+    if (text.length <= MAX_TEXT_LENGTH) {
+        return text;
+    }
+    return `${text.slice(0, MAX_TEXT_LENGTH - 1)}…`;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "lobid-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for lobid-gnd authority data",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lukaslerche/lobid-mcp.git"
+  },
+  "author": {
+    "name": "Lukas Lerche",
+    "email": "lukas.lerche@tu-dortmund.de",
+    "url": "https://lukaslerche.de"
+  },
+  "type": "module",
+  "bin": {
+    "lobid-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsx watch src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "gnd",
+    "lobid",
+    "llm",
+    "authority-data",
+    "claude",
+    "opencode"
+  ],
+  "homepage": "https://github.com/lukaslerche/lobid-mcp",
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0-alpha.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}