deweloperuch.pl (unofficial)

deweloperuch-mcp

网站 · 波兰语文档，附带可视化安装指南

向 AI 助手咨询波兰新建公寓：挂牌价格及其历史、真实成交价格和官方统计数据。

这是一个非官方的 MCP 服务和命令行工具，提供对 deweloperuch.pl 公开数据的访问：开发商挂牌价格（含价格历史）、来自房地产价格登记册（RCN）的成交价格，以及 GUS 和 NBP 的统计数据。它提供 13 种只读工具，可通过 Claude Desktop 或 Claude Code 等 MCP 客户端使用，也可通过 deweloperuch CLI 使用。

免责声明。 这是一个独立项目。它与 deweloperuch.pl、GUS、NBP 或登记册发布方没有关联，也未获得其认可或赞助。deweloperuch.pl 的作者已同意本项目使用其服务；客户端会使用 deweloperuch-mcp/<version> 标识自身，并附上此代码库的链接。

• 本工具只读：绝不会在服务上创建或更改任何内容。
• 本工具是一个礼貌的客户端：每秒最多发送 1 个请求，且一次只发送一个请求；所有进程在你的机器上共用此限制；响应会缓存；遇到 401、403、429 或验证码/WAF 挑战后，工具会停止发送请求，直到你手动清除锁定。
• 请尊重此服务。 服务由其他人运营；请提出范围明确的问题，不要在此工具之上构建循环请求或批量下载。
• 不保证数据准确。价格是挂牌价或登记价格，并非估值或建议。
• 你需自行负责如何使用本工具及其数据，包括遵守服务条款。

可以询问什么

• 买房：“在克拉科夫的 Podgórze 区寻找面积为 40–55 m²、总价不超过 800 000 PLN 的公寓，按每平方米价格从低到高排序。”（服务不支持按房间数筛选；请改按面积筛选。）
• 判断房源价格：“这套房源划算吗？展示它的价格历史、过去 30 天和 90 天的最低价，以及降价是否看起来可疑。”
• 查询开发商：“这家开发商建造什么项目？在哪些城市有多少套在售房源？”
• 市场与成交价格：“过去几个季度，格但斯克的挂牌价格与登记的成交价格相比如何？”
• 估价：“根据附近的成交记录，这个地址一套 55 m² 的公寓大约值多少钱？”
• 比较城市：“按每平方米成交价格给城市排名，并列出各城市的工资和失业率。”

安装

选择最适合你的第一个选项；这些选项从无需终端到面向专家依次排列。支持的系统：macOS、Linux，以及带有本地 NTFS 缓存目录的 Windows 10（1903+）/ 11。

从 0.1.3 开始支持 Windows，包括 PyPI 软件包和 .mcpb 扩展。0.1.2 及更早版本仅支持 macOS 和 Linux。

想要图文演示？项目网站上的安装指南（波兰语）会逐步介绍安装，并提供一段提示词，让 AI Agent 替你安装。

1. Claude Desktop，无需终端

1. 从最新版本下载 deweloperuch-mcp-<version>.mcpb。
2. 双击该文件，或将它拖入 Claude Desktop → Settings → Extensions → Install，然后重启 Claude Desktop。

你将获得：Claude Desktop 中的 13 个工具和 4 个提示词。该扩展使用 uv 运行时（清单中的 server.type 为 uv），因此首次启动时会获取 Python 和依赖项，耗时约一分钟；无需自行安装任何内容。它没有命令行工具；如果服务曾被停止（STOP），请参阅无需检出即可解除 STOP。

2. 任意 MCP 客户端，使用 uv

你将获得：Claude Desktop、Claude Code 或任何可启动 stdio 服务的客户端中的相同工具。无需克隆。

安装一次 uv（macOS 和 Linux）：

curl -LsSf https://astral.sh/uv/install.sh | sh

在 Windows 上使用 PowerShell（uv 安装说明）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后打开新的终端，让它识别 PATH 中的 uv。

Claude Code：

claude mcp add deweloperuch -- uvx deweloperuch-mcp

Claude Desktop（claude_desktop_config.json；其他客户端使用相同的 command 和 args）：

{
  "mcpServers": {
    "deweloperuch": {
      "command": "uvx",
      "args": ["deweloperuch-mcp"]
    }
  }
}

若要直接从 GitHub 运行而不是使用 PyPI，请使用 uvx --from git+https://github.com/MBratkowski/[email protected] deweloperuch-mcp（@v0.1.3 固定到该版本；删除它即可跟随 main）。pip install deweloperuch-mcp 也可使用。

如果 Windows MCP 客户端找不到 uvx，请将 (Get-Command uvx).Source 返回的完整可执行文件路径用作 command。在 JSON 中转义反斜杠，例如 "C:\\Users\\YOUR_NAME\\.local\\bin\\uvx.exe"。检出源码后则使用 "command": "uv" 和 "args": ["run", "--directory", "C:\\path\\to\\deweloperuch-mcp", "deweloperuch-mcp"]。

3. 用于 CLI 的 Agent 技能

你将获得：一个懂得如何使用 deweloperuch CLI 的 AI 编码 Agent（知道要调用哪个命令、如何读取输出，以及遇到 STOP 时该怎么做），无需 MCP 服务。该技能名为 deweloperuch-cli；新的 Agent 会话会自动加载它。

npx skills add MBratkowski/deweloperuch-mcp

这会使用 skills CLI（需要 Node.js），并适用于其支持的任何 Agent；由你选择 Agent。若没有 Node.js：

uvx --from deweloperuch-mcp deweloperuch skill install

它会写入 ~/.claude/skills/deweloperuch-cli（供用户使用的 Claude Code）。选项：--project（此项目的 ./.claude/skills）、--agent codex|cursor|gemini-cli|github-copilot、--dir PATH（写入 PATH/deweloperuch-cli）、--force（替换不同的副本；不使用该选项时，已更改的副本绝不会被覆盖，且安装程序绝不会通过符号链接写入）。deweloperuch skill show 会打印技能内容，deweloperuch skill path 会打印其文件夹路径。详情：docs/cli/commands/skill.md。

Claude Code 插件市场：

/plugin marketplace add MBratkowski/deweloperuch-mcp
/plugin install deweloperuch@deweloperuch-mcp

4. 单独使用 CLI

你将获得：可用于终端和脚本的 deweloperuch 命令；请参阅 docs/cli/README.md。

uvx --from deweloperuch-mcp deweloperuch --help    # one-off, nothing installed
uv tool install deweloperuch-mcp                   # installs deweloperuch and deweloperuch-mcp
deweloperuch locations search krak

5. 从源代码安装（贡献者）

要求：Python 3.11 或更高版本，以及 uv。

git clone https://github.com/MBratkowski/deweloperuch-mcp.git
cd deweloperuch-mcp
uv sync
uv run deweloperuch --help                  # sends no requests

客户端命令使用 uv run --directory /path/to/deweloperuch-mcp deweloperuch-mcp（Claude Code：claude mcp add deweloperuch -- uv run --directory /path/to/deweloperuch-mcp deweloperuch-mcp）。更多信息：CONTRIBUTING.md 和 docs/mcp/README.md。

故障排除

• uvx: command not found 或 spawn uvx ENOENT：安装 uv（选项 2）。Claude Desktop 可能无法读取你的 shell PATH，因此请将 which uvx（macOS/Linux）或 (Get-Command uvx).Source（PowerShell）输出的完整路径填入 command。
• Claude Desktop 中未显示服务：安装扩展或编辑配置后，退出并重启 Claude Desktop。
• Windows 上使用 0.1.2 或更早版本：更新到 0.1.3 或更高版本。若通过 uv 工具安装，请运行 uv tool upgrade deweloperuch-mcp；若通过 pip 安装，请运行 python -m pip install --upgrade deweloperuch-mcp；若使用 uvx，请运行 uvx --refresh deweloperuch-mcp --help。将旧版 .mcpb 扩展替换为最新版本。
• STOP / 退出代码 3：收到 401、403、429 或遇到验证码/WAF 挑战后，客户端会在所有进程中停止发送请求，以免给服务增加负担。429 会在暂停一段时间（至少 60 s）后自行失效。其他原因则会持续存在，直到你解除限制并检查原因（deweloperuch stop status 会显示状态；AI Agent 不得解除限制）。MCP 服务会一直处于停止状态，直到你重启它。详情和命令见：docs/configuration.md。
• **缓存在哪里？**响应仅缓存在内存中。限流锁和 STOP 记录位于 ~/.cache/deweloperuch-mcp（$XDG_CACHE_HOME/deweloperuch-mcp）。不要删除此目录，否则也会解除 STOP。

工具

概览、参数规则、错误和结果大小：docs/mcp/README.md。

工具	描述
search_locations	根据名称片段查找城市、区和街道，并返回 city_slug。
search_offers	按价格、面积、每平方米价格、区、状态和降价情况筛选并排序，查看某个城市或整个波兰的开发商公寓房源分页结果。
get_offer	获取单个房源及其完整价格历史和价格标记（30/90 天内最低价、疑似降价）。
search_investments	按城市查找项目（包括均价、排序和按开发商筛选），或按名称在波兰范围内查找。
get_investment	获取项目及其开发商、平均价格和房源列表。
search_developers	根据名称片段查找开发商，并返回 developer_slug。
get_developer	开发商资料：简介、包含在售房源的项目以及所在城市。
get_market_statistics	某个城市的房源市场统计：数量、价格、每平方米价格和面积分布，以及规模最大的开发商。
get_transaction_statistics	按月或季度查看某个城市的交易价格（RCN）。
rank_locations	按 RCN 交易和每平方米价格对地点或 powiat 排名。
get_building	获取 RCN 中的建筑及其单元和交易记录。
estimate_property_value	根据附近的 RCN 交易，估算某个地点的公寓价值。
get_government_statistics	获取波兰、汇总地区和 66 个城市的 GUS 和 NBP 官方时间序列数据（住宅、NBP 价格、失业率、工资、人口统计）。

每个工具都会拒绝不符合其架构的参数，并通过错误列出允许的名称。工具描述、错误消息和 CLI 输出均为波兰语，因为该服务及其用户都来自波兰。

提示词

Claude Desktop 中会以命令形式显示四个预设提示词。它们不会自行发送请求，而是引导模型使用上述工具。参数和详情：docs/mcp/prompts.md。

提示词	描述
znajdz_mieszkanie（“Znajdź mieszkanie”）	在一个城市中查找符合预算、面积和区域要求的开发商公寓：以每平方米价格从低到高排列的房源表。
ocen_oferte（“Oceń ofertę”）	评估单个房源的价格：查看价格历史、与城市市场的比较，以及与附近交易估值的比较。
przeswietl_dewelopera（“Prześwietl dewelopera”）	开发商资料：其开发地点和规模、项目、在售房源、价格及其变化。
porownaj_miasta（“Porównaj miasta”）	在一个表格中比较多个城市（最多 5 个）的公寓市场：挂牌价格、RCN 交易价格，以及可选的工资和失业率。

CLI 命令

概览、输出格式和退出代码：docs/cli/README.md。

命令	描述
deweloperuch locations search QUERY	查找城市、区和街道；返回城市 slug。
deweloperuch offers search CITY	使用筛选条件和排序，在某个城市或整个波兰搜索房源。
deweloperuch offers get OFFER_ID --investment SLUG	显示房源及其价格历史和价格标记。
deweloperuch investments search [CITY]	按城市或名称搜索楼盘。
deweloperuch investments get SLUG	显示楼盘及其开发商和房源。
deweloperuch developers search NAME	按名称查找开发商；返回开发商 slug。
deweloperuch developers get SLUG	显示开发商资料。
deweloperuch buildings get SLUG	显示 RCN 中的建筑及其单元和交易。
deweloperuch valuation estimate --lat --lng --area	估算某个地点的公寓价值。
deweloperuch stats market CITY	显示某个城市的房源市场统计数据。
deweloperuch stats transactions CITY	按月或季度显示某个城市的 RCN 交易价格。
deweloperuch stats cities	显示按 RCN 交易数量排名的地区或 powiat。
deweloperuch stats government LOCATION DATASET	以时间段表格的形式显示某个地点的 GUS 和 NBP 统计数据。
deweloperuch stop status [--json]	显示所有进程共享的 STOP 锁（离线；激活时退出代码为 3）。
deweloperuch stop clear	检查原因后清除 STOP 锁。
deweloperuch skill install|show|path	安装、打印或定位 deweloperuch-cli Agent 技能（离线）。

工作原理

deweloperuch.pl  →  api  →  models  →  usecases  →  consumers (CLI, MCP server)

层	作用
api/	与服务通信：提供共享限流器、缓存和 STOP 锁的 HTTP 传输层；用于读取 JSON API 和页面数据的读取器；以及将响应映射到模型的 DTO。
models/	纯冻结数据类（房源、楼盘、价格历史、统计数据）。不执行 I/O。
usecases/	每种操作对应一个模块（例如 SearchOffers），通过 api/ 实现的端口编写。
consumers/	CLI 和 MCP 服务，二者均保持轻量：解析参数、调用用例并呈现结果。

各层在 bootstrap.py 中连接；tooling/ 存放非业务辅助工具（技能安装程序），仅供 CLI 使用。Import-linter 会强制执行导入方向。设计决策及其原因：docs/decisions.md。服务的数据、端点和限制：docs/discovery/README.md。配置、限流器和 STOP 锁：docs/configuration.md。

开发

uv sync
make fast     # ruff, ruff format --check, mypy, import-linter (a few seconds)
make check    # fast + the offline tests + dead-code check + complexity and duplication reports

每个 make 目标都可离线运行；测试不会打开网络套接字，而是使用存储在 docs/discovery/samples/ 和 tests/fixtures/ 中的真实响应进行测试。

文件夹	内容
tests/unit/	与 src/ 对应的单元测试。
tests/contract/	将存储的服务响应与 DTO 和适配器进行对比。
tests/integration/	在模拟服务上使用真实适配器的用例。
tests/characterization/	CLI 和 MCP 服务的黄金输出（tests/golden/）。
tests/architecture/、tests/safeguards/	分层和命名规则、全仓库一致性（身份、已发布资源、元数据）；无网络保证。
tests/support/	测试基础设施（伪造对象、构建器、检查工具），不包含测试。
tests/e2e/	可选启用的实时测试套件，见下文。

有意更改输出后，请使用 DEWELOPERUCH_UPDATE_GOLDEN=1 uv run pytest tests/characterization 刷新黄金输出，并检查差异（tests/golden/README.md）。

实时端到端测试默认关闭。它们会针对真实服务检查已安装的服务、CLI 和辅助脚本，因此会发送真实请求。请谨慎运行，仅在更改确有需要时运行：

DEWELOPERUCH_LIVE=1 uv run pytest -m live tests/e2e -rs --maxfail=3

必须同时设置变量并指定 -m live。测试场景和请求预算：tests/e2e/README.md。贡献指南和发布流程：CONTRIBUTING.md。

文档

文档	内容
网站 和其文档	项目首页和波兰语用户文档，附有可视化安装指南
docs/mcp/README.md	MCP 服务：工具、提示词、客户端配置、参数规则、错误、结果大小
docs/cli/README.md	deweloperuch CLI：命令、输出格式、退出代码
docs/configuration.md	环境变量、文件、请求限制器、缓存和 STOP 锁
docs/discovery/README.md	数据层概览：服务架构、访问渠道、主要发现
docs/discovery/endpoints.md	服务 /api/* 端点目录
docs/discovery/pages-rsc.md	将页面作为数据源：筛选、排序、分页
docs/discovery/entities.md	实体、标识符、关系、值字典
docs/discovery/samples/	精简的响应示例（契约测试的依据）
docs/capability-matrix.md	功能、对应请求，以及提供这些功能的工具或命令
docs/open-questions.md	关于服务的已知缺口和未经验证的假设
docs/decisions.md	架构决策
CHANGELOG.md	各版本之间的变更

数据来源和许可

• deweloperuch.pl：所有房源、投资、开发商和统计数据的来源。使用这些数据时须遵守其条款。
• RCN（房地产价格登记册）交易数据，通过该服务获取。该服务的作者在其公开仓库中以 CC0 许可发布原始 RCN 数据。
• GUS（中央统计局）和 NBP（波兰国家银行）统计数据，通过该服务获取。重新发布数据时，请注明来源。

代码采用 MIT 许可证。该许可证仅涵盖代码；用于测试的示例和固定数据包含来自上述来源的数据，详情见 NOTICE。项目图标也不受 MIT 许可证涵盖：保留所有权利，经 deweloperuch.pl 作者许可使用（见 NOTICE）。

贡献

欢迎提交问题和拉取请求；请先阅读 CONTRIBUTING.md，尤其是 polite-client 规则。安全问题报告： SECURITY.md。