kio-orzeczenia-mcp

kio-orzeczenia-mcp

面向 Urzad Zamowien Publicznych（公共采购办公室）旗下 Krajowa Izba Odwolawcza (KIO)（国家上诉委员会） 裁决公开数据库 orzeczenia.uzp.gov.pl 的 MCP 服务（Model Context Protocol）。

它使 Claude / Cursor / VS Code MCP Agent 能够获取 KIO 裁决，并提供可验证的引文（案号 + URL + 日期）。

状态：POC v0.1.0 | 许可证：Apache-2.0 | 维护者：MateMatic

初步警告。 v0.1.0 连接器是概念验证版本。它通过 HTML 从 UZP 公开裁决数据库获取数据（没有官方 REST API）。完整的法律免责声明请参阅下方的“法律免责声明”部分。投入生产部署前，需要进行专门的冒烟测试并通知 UZP。

---

KIO 简介

Krajowa Izba Odwolawcza（国家上诉委员会）是 Urzad Zamowien Publicznych（公共采购办公室）下属的行政（准司法）机构——KIO 成员在裁决时享有独立性（《公共采购法》第 471 条）——负责审理针对公共采购程序中采购机关决定提出的上诉（2019 年 9 月 11 日颁布的《公共采购法》）。根据《公共信息获取法》，UZP 会公开发布 KIO 裁决。

根据波兰共和国宪法第 87 条，KIO 裁决并非法律渊源——它们是广泛用于处理公共采购事务的律师事务所法律实务中的参考资料。

快速入门

# Clone and enter the directory
git clone https://github.com/matematicsolutions/kio-orzeczenia-mcp.git
cd kio-orzeczenia-mcp

# Virtualenv
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install
pip install -e ".[dev]"

# Offline test (signature parser)
pytest tests/test_signature.py -v

# Smoke test (online - hits UZP, rate-limited 1 req/s)
pytest tests/test_smoke.py -v -m smoke

# Run the server (stdio)
python -m kio_orzeczenia_mcp.server

接入 Claude Code

在 ~/.claude.json（或项目中的 .mcp.json）添加：

{
  "mcpServers": {
    "kio-orzeczenia": {
      "command": "python",
      "args": ["-m", "kio_orzeczenia_mcp.server"],
      "env": {
        "KIO_MCP_RATE_LIMIT": "1.0",
        "KIO_MCP_CACHE_DIR": "~/.matematic/cache/kio"
      }
    }
  }
}

重启 Claude Code。启动后，应能看到 6 个工具。

在启用了 Smart App Control 的 Windows 11 上

Smart App Control 会拦截未签名的可执行文件，包括 uvx.exe、pip.exe 以及 pip 安装时生成的 kio-orzeczenia-mcp.exe 启动器。来自 python.org 安装程序的 python.exe 和 py.exe 已由 Python Software Foundation 签名，因此可以通过解释器运行模块：

python -m pip install kio-orzeczenia-mcp
python -m kio_orzeczenia_mcp

出于相同原因，pip.exe 也会被拦截，因此请使用 python -m pip 安装，而不要使用 pip install。如果 python 不在 PATH 中，请使用 Windows 启动器：py -3 -m kio_orzeczenia_mcp。

{ "mcpServers": { "kio-orzeczenia-mcp": { "command": "python", "args": ["-m", "kio_orzeczenia_mcp"] } } }

请勿为了绕过此问题而关闭 Smart App Control——关闭后，除非重新安装 Windows，否则无法重新启用。

6 个 MCP 工具

1. kio_search(query: SearchQuery) -> SearchResult

搜索 KIO 裁决。所有字段均为可选。

// Arguments:
{
  "phrase": "razaco niska cena",
  "signature": null,
  "date_from": "2024-01-01",
  "date_to": "2024-12-31",
  "pzp_article": "226",
  "subject_index": null,
  "inflection": true,
  "page": 1,
  "size": 20
}

返回 {total, page, items: [OrzeczenieSummary]}。

2. kio_get_orzeczenie(signature_or_id: str | int) -> Orzeczenie

获取单份裁决的全文。

// Arguments:
"KIO 2924/21"   // string -> first search by signature to resolve internal_id (+1 req)
15903           // int -> directly GET /Home/Details/15903 + /Home/ContentHtml/15903

返回完整的 Orzeczenie，包含 content_text、sentence、reasoning（如果解析器能够提取）、pzp_articles、subject_index、doc_type、outcome、chamber_composition、parties。

issue_date 可能为 null——UZP 的一些较早记录没有发布日期。我们不会以占位日期替代。

3. kio_recent(days: int = 30, limit: int = 20) -> list[OrzeczenieSummary]

获取最近 N 天的最新裁决，按日期降序排列。

// Arguments:
{ "days": 30, "limit": 20 }

4. kio_by_pzp_article(article: str, limit: int = 20) -> list[OrzeczenieSummary]

获取引用特定 PZP 条款的裁决。使用 UZP 服务端的 Art 筛选器，该筛选器匹配条文词典，并且对格式敏感（"art. 226 ust. 1 pkt 5" 可匹配，单独的 "226" 则不会）。若结果为空，该工具会回退到全文短语搜索。

// Arguments:
{ "article": "art. 226 ust. 1 pkt 5", "limit": 20 }
{ "article": "224 ust. 1", "limit": 50 }   // "art. " prefix added automatically

5. kio_get_pdf_url(signature_or_id: str | int) -> dict

返回 PDF 的 URL（由 UZP 使用 Qt 4.8.7 从 .docx 转换生成）。不会获取文件内容——我们只提供链接。

// Returns:
{
  "pdf_url": "https://orzeczenia.uzp.gov.pl/Home/PdfContent/15903?Kind=KIO",
  "signature": "KIO 2924/21",
  "internal_id": 15903,
  "human_readable_citation": "Wyrok KIO z 2021-10-28, sygn. KIO 2924/21"
}

---

6. kio_coverage() -> Coverage

声明此连接器涵盖的内容、数据来源，以及明确不涵盖的内容。 每个缺口都有一个稳定的 ID 和回退方案。在告诉用户某项裁决“不存在”之前，请先调用此函数——缺失可能是此连接器的覆盖缺口，而非 KIO 判例中的缺失。

3 个使用示例（自然语言）

示例 1：“过去一年关于异常低价的 KIO 裁决”

Agent 调用 kio_search：

{
  "phrase": "razaco niska cena",
  "date_from": "2025-05-20",
  "date_to": "2026-05-20",
  "inflection": true,
  "size": 50
}

结果：一组 OrzeczenieSummary，其中的 human_readable_citation 可直接插入法庭文件。

示例 2：“援引 PZP 第 226 条第 1 款第 5 项的 KIO 裁决”

Agent 调用 kio_by_pzp_article：

{ "article": "226 ust. 1 pkt 5", "limit": 30 }

示例 3：“KIO 2924/21 号裁决——当事方是谁？上诉是否获支持？”

Agent 调用 kio_get_orzeczenie：

"KIO 2924/21"

结果：完整的 Orzeczenie，包含 parties、sentence、reasoning。

---

限制（POC）

1. 将签名映射到 internal_id 需要搜索——如果按签名查询，我们会额外发送 1 个请求
2. 服务端 PZP 条款筛选基于字典——Art 会匹配 UZP 条款字典中的条目，因此格式很重要（"art. 226 ust. 1 pkt 5"，而非 "226"）；若未匹配，我们会回退到短语搜索，其范围更广，需要核验
3. 不获取 PDF——仅提供 UZP 页面链接（产品决策）
4. 裁决主文／理由解析器较浅——POC 中，我们会将 content_text 作为纯文本返回。拆分为各个部分 -> v1.0
5. 速率限制为 1 req/s——较大的列表可能会很慢。为裁决（不可变）设置 7 天缓存可缓解此问题。
6. UZP 每页固定提供 10 条结果——size > 10 时，由客户端拼接连续页面，即每增加一页额外发送 1 个请求
7. 采用网页抓取，而非 API——UZP 于 2026 年 7 月重建了搜索引擎，所有端点均已变更（参见 DISCOVERY.md）。UZP 端发生任何变更后，请运行 pytest -m smoke；tests/test_parser_regression.py 可离线保护解析器。

缓存

• 裁决（不可变）：7 天
• 搜索结果列表：6 小时
• PZP 字典（实现后）：30 天

缓存位置：~/.matematic/cache/kio/（可通过 KIO_MCP_CACHE_DIR 配置）。

审计日志

位置：~/.matematic/audit/kio-orzeczenia-mcp.jsonl

JSONL 格式（每次工具调用一条记录）。参见 CONSTITUTION.md 第 3 条。

不会记录的内容：裁决全文（content_text、reasoning）。我们只记录签名和元数据。

法律免责声明

数据来自 UZP 公开判例数据库（orzeczenia.uzp.gov.pl），该数据库依据 2001 年 9 月 6 日《公共信息获取法》和 2019 年 9 月 11 日《公共采购法》开放。

此连接器：

• 不会修改源数据；
• 不会对 UZP 未公开的诉讼当事方进行去匿名化；
• 不会绕过任何技术保护措施；
• 会使用 User-Agent 标头 matematic-kio-mcp/{version} (+https://matematic.co) 标识自身。

发布前阻塞事项。 计划在 GitHub 上发布仓库之前，通知 UZP（[email protected]）连接器即将上线，告知其 User-Agent、查询限制和访问性质。状态：TODO。

如 UZP 或其他方面提出异议，请联系：[email protected]。

许可证

Apache-2.0。参见 LICENSE。

项目章程

参见 CONSTITUTION.md——4 项治理原则（公共数据、速率限制、审计日志、引用）。

波兰法律的其他开源连接器

MateMatic 提供的开源连接器，可补充本仓库的覆盖范围：

• mcp-saos - SAOS（最高法院、最高行政法院、普通法院）
• mcp-eu-sparql - 通过 Cellar SPARQL 获取欧盟法律
• mcp-isap - 法律公报、《波兰监察报》、各部委公报（Sejm ELI API）

外部法律来源目录：worldwidelaw/legal-sources（批量采集脚本，MIT）。