{
  "markdown": "> **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide/swiss-public-data-mcp)** — a collection of open-source MCP servers connecting AI agents to Swiss public and open data.\n> This is a private project. It is not affiliated with, endorsed by, or operated on behalf of any employer or public authority.\n\n# lindas-mcp\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-orange.svg)](https://modelcontextprotocol.io/)\n[![Data: LINDAS](https://img.shields.io/badge/data-LINDAS%20%7C%20SPARQL-red.svg)](https://lindas.admin.ch)\n\n**MCP server for LINDAS — the linked-data knowledge graph of the Swiss administration.**\n\n🇩🇪 [Deutsche Version](README.de.md)\n\n---\n\n## What LINDAS is\n\nLINDAS (Linked Data Service) is the Swiss Confederation's SPARQL knowledge\ngraph, run by the Federal Archives. Instead of tables, it publishes data as RDF\ntriples: around 2000 statistical **data cubes** (cube.link) from federal\noffices, plus the geo-linked data that powers visualize.admin.ch.\n\n> **Mnemonic: «I14Y is the library catalogue, LINDAS is the library itself.»**\n> [i14y-mcp](https://github.com/malkreide/i14y-mcp) tells you a dataset exists.\n> LINDAS holds the data and lets you query across all of it at once.\n\nThis server wraps LINDAS in guarded tools rather than exposing raw SPARQL,\nbecause the store rewards precise queries and times out on broad ones.\n\n---\n\n## 🎯 Anchor Demo Query\n\n> *«Which forest-fire danger level currently applies, who publishes it, and\n> under which licence?»*\n\n```\nsearch_cubes(query=\"waldbrand\")\n  → «Waldbrandgefahr» — BAFU, published\n\nget_cube_structure(cube_uri=...)\n  → dimensions: Warnregion (key), Gefahrenstufe (measure)\n  → licence: fedlex.data.admin.ch/eli/cc/1984/... (a Fedlex URI!)\n\nquery_cube_observations(cube_uri=...)\n  → Warnregion: \"Dorneck / Thierstein (SO)\", Gefahrenstufe: \"grosse Gefahr\"\n```\n\nThe codes come back as labels — «grosse Gefahr», not `4`. And the licence is a\nFedlex URI you can resolve with [fedlex-mcp](https://github.com/malkreide/fedlex-mcp).\n\n### Demo\n\n![Demo: Claude using search_cubes, get_cube_structure and query_cube_observations](docs/assets/demo.svg)\n\n---\n\n## The two-phase access pattern\n\nLINDAS cubes are self-describing but coded. Reading them well means two steps,\nwhich this server enforces:\n\n1. **Structure first** — `get_cube_structure` reads the cube's SHACL shape: its\n   dimensions (filterable axes), its measures (the numbers), and which\n   dimensions carry code lists.\n2. **Data second** — `query_cube_observations` reads the observations and\n   resolves coded values to human labels using the structure from step 1.\n\n> **Mnemonic: «LINDAS speaks in postcodes, not place names.»** An observation\n> says region `1805`; the server turns that into «Alpennordhang» for you.\n\n---\n\n## Architecture\n\n```\n                 ┌──────────────────────────────┐\n                 │      MCP Host (Claude)       │\n                 └───────────────┬──────────────┘\n                                 │ stdio | streamable-http\n                 ┌───────────────▼──────────────┐\n                 │          lindas-mcp          │\n                 │  ┌────────────────────────┐  │\n                 │  │ server.py  (7 tools)   │  │  talks only to cube.py\n                 │  ├────────────────────────┤  │\n                 │  │ lindas/cube.py         │  │  ← vocabulary guardrail,\n                 │  │                        │  │    two-phase access,\n                 │  │                        │  │    code→label resolution\n                 │  ├────────────────────────┤  │\n                 │  │ lindas/queries.py      │  │  SPARQL templates,\n                 │  │                        │  │    all anchored on a class\n                 │  ├────────────────────────┤  │\n                 │  │ lindas/client.py       │  │  raw SPARQL over HTTP,\n                 │  │                        │  │    knows nothing of cubes\n                 │  └────────────────────────┘  │\n                 └───────────────┬──────────────┘\n                                 │ HTTPS, no auth\n                 ┌───────────────▼──────────────┐\n                 │  lindas.admin.ch/query       │\n                 │  SPARQL 1.1 · ~2000 cubes    │\n                 └──────────────────────────────┘\n```\n\nThe `lindas/` package is deliberately layered so it can be lifted into other\nLINDAS-backed servers unchanged. `client.py` knows only HTTP and SPARQL;\n`cube.py` knows the cube.link vocabulary; the tools know only `cube.py`. Raw\nSPARQL never reaches the agent except through the guarded `run_sparql` escape\nhatch.\n\n### Architecture decision\n\n**Architecture A (live SPARQL only), with a strict vocabulary guardrail.**\n\nVerified live on 2026-07-21:\n- The endpoint is stable, needs no authentication, and returns a clean HTTP 400\n  with a diagnostic on malformed queries.\n- Blind scans (`SELECT *`, `COUNT(*)` over the whole store) time out at\n  60–90 s; the same question anchored on `?x a cube:Cube` answers in ~2 s.\n\nConsequences, baked into the tools:\n- Every query template is anchored on a known class. No unbounded scans.\n- Two-phase access is enforced; the agent never sees raw codes.\n- `run_sparql` is capped at 500 rows and 30 s and marked as advanced.\n- The client timeout sits at 45 s, in front of the store's own 60–90 s abort.\n\nFull probe report: [`docs/probe-lindas.md`](docs/probe-lindas.md).\n\n---\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `search_cubes` | Find cubes by topic. Entry point. Deduplicates versions. |\n| `get_cube_structure` | Phase 1: dimensions, measures, licence. |\n| `query_cube_observations` | Phase 2: data points with codes resolved to labels. |\n| `list_publishers` | Federal bodies publishing cubes, with counts. |\n| `resolve_municipality` | Name ↔ URI ↔ BFS number — the portfolio join key. |\n| `run_sparql` | Advanced escape hatch. Capped, guarded. |\n| `api_status` | Reachability check with cube count. |\n\nAll tools are annotated `readOnlyHint: true`.\n\n---\n\n## Installation\n\n```bash\nuvx lindas-mcp\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"lindas\": {\n      \"command\": \"uvx\",\n      \"args\": [\"lindas-mcp\"]\n    }\n  }\n}\n```\n\n### Remote deployment\n\n```bash\nLINDAS_MCP_TRANSPORT=sse PORT=8000 lindas-mcp\n```\n\n`LINDAS_MCP_TRANSPORT` accepts `stdio` (default), `sse` or `streamable-http`.\nThe SSE / streamable-http transport binds to `HOST`, **default `127.0.0.1`**;\nset `HOST=0.0.0.0` explicitly to expose it (only behind a reverse proxy). For a\nhosted HTTP deployment, set `ALLOWED_ORIGINS` to a comma-separated list of\nbrowser origins — **unset means no browser client is permitted at all**, which\nis the default. `*` is still accepted and logs a warning. `LOG_LEVEL` tunes the\nJSON stderr logs.\n\n### Docker\n\n```bash\ndocker compose up --build          # binds 0.0.0.0 inside the container, publishes :8000\n```\n\nThe image runs as a non-root user, read-only, with resource limits and a\nTCP health check (see [`Dockerfile`](Dockerfile) and [`compose.yaml`](compose.yaml)).\n\n---\n\n## Join keys\n\nLINDAS is a connector layer, and two of its identifiers make it composable with\nthe rest of the portfolio:\n\n| Key | Where | Joins to |\n|---|---|---|\n| BFS commune number | `resolve_municipality` → `bfs_number` | swiss-statistics-mcp, zurich-opendata-mcp |\n| Fedlex URI | cube `licence` field | [fedlex-mcp](https://github.com/malkreide/fedlex-mcp) |\n\nThe Fedlex link is the quiet surprise: many cubes declare their licence as a\nlegal-basis URI (`fedlex.data.admin.ch/eli/cc/...`), so you can go from a data\npoint straight to the law that governs it.\n\n---\n\n## Known limitations\n\nVerified live on 2026-07-21.\n\n1. **Broad SPARQL times out.** The store aborts unanchored scans at 60–90 s.\n   The guarded tools avoid this; `run_sparql` warns about it and caps runtime.\n2. **Observations are coded.** Dimension values are URIs, not labels. The server\n   resolves them via each dimension's code list, but resolution costs one extra\n   query per coded dimension. Set `resolve_labels=False` to skip it.\n3. **No server-side observation filtering by arbitrary value.** LINDAS has no\n   cheap way to filter observations by a dimension value inside a cube, so\n   `query_cube_observations` reads the first N observations. Analytical slicing\n   belongs in `run_sparql`.\n4. **Licences vary per cube** and are declared as `dcterms:license`, frequently\n   a Fedlex URI rather than a plain name. Always surface the `licence` field.\n5. **Version handling is heuristic.** `search_cubes` deduplicates by stripping\n   the version suffix from the cube URI and keeping the highest `schema:version`\n   among published cubes. Unusual URI shapes may not collapse cleanly; use\n   `latest_only=False` to inspect every version.\n\n---\n\n## MCP Protocol Version\n\nThis server speaks **two protocol eras** over the same endpoint. The client's\nfirst request on a connection decides which one applies; a later claim from the\nother era is refused.\n\n| Era | Revision | Who reaches it |\n|---|---|---|\n| `initialize` handshake | `2024-11-05` … **`2025-11-25`** | What today's clients speak. The server answers with the revision asked for, or with the `2025-11-25` ceiling when the request asks for something newer. |\n| Per-request envelope | **`2026-07-28`** | A request carrying the `2026-07-28` `_meta` envelope opens a modern connection. |\n\nBoth revisions are pinned in\n[`tests/test_protocol_version.py`](tests/test_protocol_version.py) and asserted\nagainst the installed SDK, so a Dependabot bump of `mcp` cannot move either one\nsilently. The handshake ceiling is measured against a live `initialize` through\nthe assembled ASGI stack, not read off a constant name.\n\nNote that the SDK's `LATEST_PROTOCOL_VERSION` is an alias for the **modern**\nera, not for the handshake era — pinning against it alone would leave the era\nthat current clients actually negotiate free to drift.\n\n**Update policy.** When the gate fails, do not edit the constant blindly: read\nthe spec changelog between the two revisions, verify the server still behaves,\nthen move the constant, this section, `README.de.md` and\n[`CHANGELOG.md`](CHANGELOG.md) together.\n\n---\n\n## Testing\n\n```bash\nPYTHONPATH=src pytest tests/ -m \"not live\"   # offline, used in CI\nPYTHONPATH=src pytest tests/ -m \"live\"       # hits the real endpoint\npython -m ruff check src tests\n```\n\nThe live tests earn their place: the `observationSet` indirection (a cube's\nobservations hang off `cube:observationSet`, never directly off the cube) is a\nstructural assumption that a mock cannot validate. It is covered by a live test.\n\n---\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for the ground rules (read-only, one\negress host, anchored queries) and the local dev loop. Further reading:\n[`EXAMPLES.md`](EXAMPLES.md) for use cases by audience with the tool-selection\ntable, [`docs/roadmap.md`](docs/roadmap.md) for the project phase, and\n[`PUBLISHING.md`](PUBLISHING.md) for the PyPI / MCP Registry release process.\n\n---\n\n## Security\n\nSee [`SECURITY.md`](SECURITY.md) for the security posture and how to report a\nvulnerability.\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE). The LINDAS data remains subject to the\nlicence each publisher declares on the cube.\n\n---\n\n## Author\n\n**Hayal Oezkan** · [github.com/malkreide](https://github.com/malkreide)\n\n---\n\n## Credits & related projects\n\n- Data: [LINDAS Linked Data Service](https://lindas.admin.ch), Swiss Federal Archives\n- Vocabulary: [cube.link](https://cube.link)\n- Visualisation frontend on the same cubes: [visualize.admin.ch](https://visualize.admin.ch)\n- Source discovery inspired by [rnckp/awesome-ogd-switzerland](https://github.com/rnckp/awesome-ogd-switzerland)\n- Portfolio: [swiss-public-data-mcp](https://github.com/malkreide/swiss-public-data-mcp)\n\nLicence: MIT. The cube data remains subject to the licence each publisher declares.\n\n---\n\n## MCP Registry\n\nOwnership marker used by the [MCP Registry](https://registry.modelcontextprotocol.io)\nto link this PyPI package to the GitHub namespace:\n\n```\nmcp-name: io.github.malkreide/lindas-mcp\n```\n\n---\n\n## MCP protocol version\n\nThe negotiated MCP protocol version is managed by the pinned `mcp` SDK\n(`mcp>=1.28.1` in `pyproject.toml`), which Dependabot keeps current. SDK upgrades\nare therefore a reviewed change: any protocol-affecting bump is called out in\n`CHANGELOG.md`, and the tool contract is guarded independently by\n`tool-definitions.lock.json` (SEC-022) so a change to the tool surface fails CI\nuntil reviewed.\n",
  "bytes": 12613,
  "sha": "8b648368d3dfd6a93e992c77ec40f7039aa8ca10a28c3e1c8292592078d200b8",
  "repo_slug": "malkreide/lindas-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_malkreide_lindas_mcp_090cb131/readme"
}