{
  "markdown": "# mcp-saos\n\n## Installation (one command)\n\nPublished on npm + the MCP Registry (`io.github.matematicsolutions/mcp-saos`). Run without cloning:\n\n```bash\nnpx -y @matematicsolutions/mcp-saos\n```\n\nMCP client configuration (stdio):\n\n```json\n{ \"mcpServers\": { \"mcp-saos\": { \"command\": \"npx\", \"args\": [\"-y\", \"@matematicsolutions/mcp-saos\"] } } }\n```\n\n(Building from source - below.)\n\n[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![Node](https://img.shields.io/badge/Node-18%2B-brightgreen)](https://nodejs.org)\n\nAn MCP (Model Context Protocol) server for Polish case law - a connector to\nSAOS (System Analizy Orzeczen Sadowych - the courts' public case-law database, run by Fundacja ePanstwo).\n\nPart of the MateMatic \"Polish legal AI\" project. It runs as a separate process\ncommunicating over stdio; the chat template (a fork of mike) calls it through the MCP protocol.\n\n## What SAOS is\n\nAn open database of Polish court judgments. Public REST API, no key required.\n\n**Coverage caveat:** coverage is broad and includes current judgments\n(2024-2026 are well populated), but it is uneven by court type, and some\nSupreme Court resolutions exist only as citations in other judgments.\nVerify anything critical against sn.pl, orzeczenia.ms.gov.pl, trybunal.gov.pl.\n\nThe database covers: common courts (COMMON), the Sad Najwyzszy (Supreme Court, SUPREME),\nthe Trybunal Konstytucyjny (Constitutional Tribunal, CONSTITUTIONAL_TRIBUNAL), the KIO (National Appeal Chamber, NATIONAL_APPEAL_CHAMBER).\nAdministrative courts (WSA/NSA) - no data in SAOS.\n\n## MCP tools\n\n| Tool | Description |\n|---|---|\n| `search` | Full-text and filtered search (court, judge, legal basis, dates) |\n| `get_judgment` | Full judgment by ID from SAOS |\n| `search_by_case` | Shortcut: search by case number (e.g. \"I ACa 772/13\") |\n| `saos_cite_check` | Citator: is the judgment still good law? Finds later citing judgments and scans them for overruling language near the signature |\n\n### saos_cite_check - the citator\n\nGive it a case number (a placeholder here; use a real one):\n\n```json\n{ \"caseNumber\": \"III CZP NN/RR\" }\n```\n\nIt searches SAOS full-text for later judgments citing that signature, scans\ntheir reasoning for departure phrases (\"odstepuje od pogladu wyrazonego\",\n\"nie podziela pogladu\", \"traci moc uchwala\", \"uchwala skladu siedmiu sedziow\"\nand others) within ~500 characters of the signature, and returns one of four\nverdicts: `przelamanie_wykryte`, `uchwala_skladu_powiekszonego`,\n`nadal_cytowany`, `brak_cytowan_w_saos`. Each hit includes a +-200 character\nfragment for human verification.\n\nEvery phrase on the list was verified against live SAOS data - the evidence\ntable, the algorithm and the honest-limits section are in\n[docs/CITE-CHECK.md](./docs/CITE-CHECK.md). The short version: no hits does\nNOT mean the judgment is still good law, and every response says so.\n\n## Requirements\n\n- Node.js >= 18\n- npm >= 9\n- Internet access (live API saos.org.pl)\n\n## Installation and build\n\n```bash\ngit clone https://github.com/matematicsolutions/mcp-saos\ncd mcp-saos\nnpm install\nnpm run build\n```\n\nAfter `npm run build`, the entry point is `dist/index.js`.\n\n## Standalone run (test)\n\n```bash\nnode dist/index.js\n# the server listens on stdin/stdout, diagnostic logs go to stderr\n```\n\n## Wiring into the chat template (fork of mike) - mcp-servers.json\n\nAdd an entry to your client's MCP configuration (e.g. `mcp-servers.json`):\n\n```json\n{\n  \"name\": \"saos\",\n  \"transport\": \"stdio\",\n  \"command\": \"node\",\n  \"args\": [\"C:/Users/<YOUR-USER>/mcp-saos/dist/index.js\"],\n  \"enabled\": true\n}\n```\n\nProvide the absolute path to `dist/index.js`. On Windows use forward slashes `/`\nor double backslashes `\\\\`.\n\n## Tests\n\n```bash\nnpm run build\nnpm test            # offline: drift test + unit tests (parser, window scan, phrase patterns)\nnode test/smoke.mjs # live: 5 checks against the real SAOS API, including the citator\n```\n\nThe smoke test checks `tools/list` (4 tools), `search`, `search_by_case`,\na Constitutional Tribunal lookup and `saos_cite_check` on a Supreme Court\nresolution with known later treatment.\n\n## Architecture\n\n```\nstdin  -->  MCP JSON-RPC (stdio transport)  -->  src/index.ts\n                                                      |\n                                            SAOS REST API\n                                     https://www.saos.org.pl/api\n                                            /search/judgments\n                                            /judgments/{id}\nstdout <--  formatted text responses  <--\n```\n\nNo external dependencies for HTTP/JSON - requests go through the built-in `node:https`.\nThe only production dependency: `@modelcontextprotocol/sdk`.\n\n## Limitations and known pitfalls\n\n- `pageSize` has a hard lower limit of 10 (SAOS returns HTTP 400 for less) -\n  the server automatically enforces a minimum of 10.\n- `courtType=ADMINISTRATIVE` returns empty results - SAOS does not index WSA/NSA.\n- Dates in the database may contain OCR artifacts (e.g. \"3013-12-04\") - the case\n  number is more reliable than the `judgmentDate` field.\n- Coverage is uneven by court type - the server states the relevant caveats\n  in every tool response.\n- `saos_cite_check` is a heuristic. It reads the top citing judgments only,\n  its phrase list cannot cover every way a court departs from a line of case\n  law, and no hits does not confirm the judgment is current.\n\n## License\n\nMIT - see the LICENSE file for details.\nJudgment data: Fundacja ePanstwo, open license (public API with no usage restrictions).\n\n## Part of the MateMatic legal stack\n\nThis server is one of five MCP connectors covering Polish jurisdiction +\nEU law, used by [Patron](https://github.com/matematicsolutions/patron)\n(AGPL-3.0) and any other MCP-aware legal AI agent.\n\n- **mcp-saos** (this repo) - common courts, Supreme Court, Constitutional Tribunal, KIO\n- [mcp-nsa](https://github.com/matematicsolutions/mcp-nsa) - NSA + 16 WSA administrative courts\n- [mcp-isap](https://github.com/matematicsolutions/mcp-isap) - Polish legislation (Dz.U. + M.P.)\n- [mcp-krs](https://github.com/matematicsolutions/mcp-krs) - Polish company registry (KRS)\n- [mcp-eu-sparql](https://github.com/matematicsolutions/mcp-eu-sparql) - EU law + CJEU (EUR-Lex)\n\n\nAll five MCP servers share the same `structuredContent.citations`\ncontract: each tool returns an array of `{title, url, snippet?, ...metadata}`\nthat legal agents can render directly in their citation panel.\n\nSee [matematicsolutions/.github](https://github.com/matematicsolutions)\nfor the full org profile.\n",
  "bytes": 6628,
  "sha": "8e1fd8d667b6dd2ab9b9182102dfa5e8c5d45682f6c0e95cdcac39598f7bbfa4",
  "repo_slug": "matematicsolutions/mcp-saos",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_matematicsolutions_mcp_saos_7598dd23/readme"
}