物业 MCP Server

让 AI 助手（Trae / Claude Desktop / Cursor / VS Code）通过自然语言操作物业系统。

垂直行业 MCP 实践 —— 覆盖报修工单、业主信息、缴费管理、公告发布、巡检记录 5 大场景。MCP 全原语覆盖：26 个 Tools（12 业务 + 4 话术 fallback + 9 Agentic 工作流 + 1 可观测）+ 4 个 Resources + 4 个 Prompts。含 RBAC 四角色权限模型 + 审计日志 + 报修 Agentic Workflow 状态机编排（智能分类 + 负载均衡派工 + human-in-the-loop 确认 + 全程留痕）+ OpenTelemetry 三支柱可观测（Traces + Metrics + Logs + 仪表盘）。预置翡翠花园小区 mock 数据，开箱即用。

适合谁用

• 物业公司 / 物业团队：想让一线管家、维修工、客服用 AI 助手处理报修、催缴、公告等日常业务，替代反复登录工单系统的繁琐操作

• MCP 学习者 / 开发者：想看一个完整、可跑、覆盖全原语（Tools + Resources + Prompts）的 MCP Server 示例，直接 clone 作为自己项目的脚手架

• AI Agent 实践者：想了解如何把单次工具调用升级为多步智能流程（状态机 + HITL + 留痕），让 Agent 真正"干活"而非只"问答"

Related MCP server: Buildium MCP Server

演示

业主报修对话

业主在 Trae 里说"我家厨房漏水，要报修" → AI 自动追问房间号 → 调 create_repair 建单。无需登录工单系统，口语直接驱动工具。

报修工作流 HITL 派工

run_repair_workflow 一键编排：创建 → 智能分类 → 派工建议（HITL 暂停等管家确认）→ 派工 → 处理 → 验收 → 关闭。分类结果、推荐师傅全部可见。

可观测仪表盘

调用总量 / 成功率 / P95 延迟 / 工具 Top N / 角色分布 / 工单漏斗 / 工作流事件 / Top 慢调用，5 秒自动刷新，零额外依赖启动。

一句话效果：业主说句话 → AI 自动建单 → 工作流自动跑分类 / 派工 / HITL 确认 → 每一步在 workflow_events 留痕 → 仪表盘实时反映调用指标。

快速开始

1. 安装依赖

cd property-mcp-server
pip install -r requirements.txt

需要 Python 3.10+

2. 验证 server 能启动

python server.py

首次运行会自动在 data/property.db 创建数据库并填充翡翠花园小区示例数据。server 启动后等待 MCP client 连接。

3. 连接 AI 客户端

支持多种客户端，任选其一。推荐 Trae（字节免费 AI IDE，国内版永久免费，SOLO 模式自动调 MCP）。

方式一：Trae（推荐，国内免费 + 项目已内置配置）

项目根目录已包含 .trae/mcp.json，用 Trae 打开 property-mcp-server 文件夹即自动加载，无需额外配置。配置使用了 ${workspaceFolder} 变量，clone 项目后用 Trae 打开也能直接用，无需改路径。

首次使用需开启项目级 MCP 开关：

1. 用 Trae 打开 property-mcp-server 文件夹

2. 左下角头像 → 设置 → MCP，打开「启用项目级 MCP」开关，在弹窗中确认

3. Trae 会自动加载 .trae/mcp.json，在 Chat/SOLO 面板能看到 property-management 工具

配置内容（已预置，无需手动修改）：

{
  "mcpServers": {
    "property-management": {
      "command": "python",
      "args": ["${workspaceFolder}/server.py"],
      "env": {
        "PROPERTY_USER_ID": "u1"
      }
    }
  }
}

切换角色：把 PROPERTY_USER_ID 改成 u1(管理员)/u2(管家)/u3(维修工)/u4(业主张伟)，重启 Trae 即可以不同身份调用工具。

提示：如果 Trae 提示找不到 python，把 command 改成 Python 的绝对路径（例如 C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe 或你本机的 python.exe）。

方式二：Cursor（备选，项目已内置配置）

项目根目录也包含 .cursor/mcp.json，用 Cursor 打开 property-mcp-server 文件夹即自动加载。

如果自动加载未生效，手动配置：Settings → Cursor Settings → MCP → Add MCP Server，内容与上方相同。重启 Cursor，在 Chat 面板右下角工具图标处能看到 property-management。

方式三：Claude Desktop

打开 Claude Desktop 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

加入以下内容（路径改成你自己的）：

{
  "mcpServers": {
    "property-management": {
      "command": "python",
      "args": ["C:/你的路径/property-mcp-server/server.py"],
      "env": {
        "PROPERTY_USER_ID": "u1"
      }
    }
  }
}

重启 Claude Desktop，左侧会出现 property-management 工具图标。

4. 开始对话 demo

在 Claude Desktop 里直接说：

• 「查一下 1 栋 502 的报修记录」

• 「2 栋有哪些业主欠费？总共多少？」

• 「帮我建一条报修：3 栋 401 卫生间地漏返味，优先级普通」

• 「把 1 号工单状态改成处理中，备注：已派工」

• 「发个公告：明天 9 点检修电梯，目标 2 栋」

• 「查一下 2 栋地下车库的巡检记录」

Resources（自动加载上下文，直接问即可）：

• 「小区现在整体情况怎么样？」→ AI 自动读取 property://community/overview

• 「2 栋物业费多少钱一平？停车费呢？」→ AI 自动读取 property://fee-standard/2栋

• 「小区有哪些设备需要巡检？有异常的吗？」→ AI 自动读取 property://devices/list

• 「装修有什么规定？能养宠物吗？」→ AI 自动读取 property://convention

Prompts（输入 / 调用话术模板）：

• 输入 /collection_reminder，填业主名、欠费金额、账期 → 生成催缴短信话术

• 输入 /repair_guide，填症状 → 生成报修引导话术

• 输入 /complaint_handler，填投诉内容 → 生成投诉处理流程话术

• 输入 /notice_drafter，填主题、楼栋 → 生成规范小区公告

Trae 用户注意：Trae 当前版本的 / 菜单不展示 MCP Prompts（只显示 Trae 自带 Commands/Skills）。改用对应的 Tool fallback——直接用自然语言说：

• 「帮我给业主张伟写催缴短信，欠 2685 元，7 月账期」→ 触发 generate_collection_reminder

• 「业主报修厨房漏水，帮我生成引导话术」→ 触发 generate_repair_guide

• 「业主投诉电梯老坏，帮我生成处理话术」→ 触发 generate_complaint_response

• 「帮我起草 8 月 15 日 2 栋电梯维保公告」→ 触发 generate_notice

4 个 generate_* Tools 与 4 个 Prompts 共享同一套话术模板逻辑，效果完全一致，保证所有客户端可用。

工具列表

Resources（只读数据原语）

Resources 是 MCP 的第二大原语，用于暴露只读参考数据。与 Tools 不同：Tools 是 AI 主动调用的动作，Resources 是 AI 自动加载的上下文。

动态资源模板是 MCP 高级用法：用 URI 模板 property://fee-standard/{building} 暴露参数化资源，客户端填入楼栋即可查询对应标准，无需为每栋楼单独注册。

使用场景：在 Trae/Cursor 里直接问「小区现在情况怎么样」「2栋物业费多少钱」「有哪些设备需要巡检」「装修有什么规定」，AI 会自动加载对应 Resource 作为上下文再回答，不需要显式调用工具。

Prompts（提示词模板原语）

Prompts 是 MCP 的第三大原语，用于预置结构化提示词模板。在 Trae/Cursor 中，用户输入 / 即可看到可用模板，填入参数后生成标准化话术。价值：让一线管家/客服执行任务时话术规范统一，不依赖个人经验。

使用场景：管家在 Trae/Cursor 里输入 /催缴，填入业主张伟、欠费 2685 元、账期 2026年7月，AI 即时生成一条得体、规范的催缴短信话术。比手写省时，比复制粘贴模板更灵活。

Trae 兼容方案：Trae 某些版本的 / 菜单不展示 MCP Prompts。为此项目额外提供了 4 个 generate_* Tools 作为 fallback（generate_collection_reminder / generate_repair_guide / generate_complaint_response / generate_notice），与 Prompts 共享同一套话术模板逻辑。在 Trae 里直接用自然语言描述需求即可触发，效果与 Prompts 完全一致。这种「Prompts 提供原生语义入口 + Tools fallback 保证可用性」的双入口设计，保证了跨客户端兼容性。

Agentic Workflow（报修状态机编排）

Phase 3 核心：把报修从"单次工具调用"升级为多步智能流程。与多数只提供工具集合的 MCP Server 不同，本项目实现了完整的 Agent 工作流编排——状态机驱动、自动分类派工、关键节点人工确认、全程留痕。

状态流转

待处理 ──智能分类──→ 已分类 ──智能派工──→ 待确认派工 ──管家确认──→ 已派工
  (created)         (classified)      (pending_assign) HITL    (assigned)
                                                                   │
  已关闭 ←──满意度回访──← 已完成 ←──管家验收──← 待验收 ←──维修工完工──← 处理中
  (closed)          (completed)   (pending_acceptance)  (processing)

• 2 个智能模块：规则分类器（关键词匹配 + 置信度）、负载均衡派工器（技能匹配 + 当前负载）

• 1 个 Human-in-the-loop 确认点：派工建议生成后停在"待确认派工"，管家确认后才正式派工

• 全程留痕：每次状态转移记入 workflow_events 表，可完整还原工单流转历史

智能分类器（规则引擎，非 LLM）

用关键词匹配 + 置信度计算自动判断报修类别（水电/土建/门窗/电梯/消防）。不用 LLM 的理由：报修描述短、类别仅 6 种，规则引擎准确率高（测试 7/7）、零延迟、可解释、可审计，满足物业合规。置信度低于阈值时标记"需人工确认"。

智能派工（技能匹配 + 负载均衡）

维修工技能矩阵：李师傅（水电/配电/排水/土建）、王师傅（消防/门窗/土建）、维保单位（电梯）、保安队（门禁/安防）。算法：筛选技能匹配的可用维修工 → 统计各自当前处理中工单数 → 选负载最低的。

一键编排

run_repair_workflow 是核心编排工具——不是单个工具，而是多步流程编排器：自动串联分类器和派工器，在 human-in-the-loop 点暂停等管家确认。适合新工单快速启动处理流程。

验证工作流

python test_workflow.py

会验证：智能分类器准确率、智能派工负载均衡、7 状态完整流转、HITL 暂停、非法转移拦截、全程留痕、一键编排。

在 Trae/Claude 里体验：

• 「帮我跑一下 1 号工单的报修流程」→ 触发 run_repair_workflow，自动分类+派工建议

• 「确认派工给李师傅」→ 触发 confirm_repair_assignment

• 「查一下 1 号工单的处理记录」→ 触发 get_repair_workflow，看完整流转历史

验证全原语

python test_primitives.py

会验证 16 个 Tools + 4 个 Resources + 4 个 Prompts 全部注册正确、数据可读、话术可生成、权限脱敏生效。

权限模型（RBAC + 审计日志）

四角色权限矩阵

数据级隔离

业主角色（owner）除了工具级权限限制，还有数据级隔离：系统会强制把查询参数覆盖为业主自己的楼栋/房号，即使传入别人的房间号也只会返回自己的数据。例如业主张伟（1栋1-502）调用 query_repairs(building="2栋")，实际返回的是 1 栋的工单。

审计日志

每次工具调用（无论成功 / 被拒 / 出错）都会写入 audit_logs 表，记录：调用时间、用户ID、用户角色、工具名、参数摘要、结果状态（success/denied/error）、错误信息、耗时(ms)。仅管理员可通过 query_audit_logs 查询，满足物业合规留痕需求。

切换角色 demo

通过环境变量 PROPERTY_USER_ID 注入当前身份（适合 MCP stdio 无状态场景）。在 .trae/mcp.json / .cursor/mcp.json 的 env 字段修改：

改成对应 ID 后重启客户端，即可用不同身份对话，体验权限隔离效果。

验证权限模型

python test_rbac.py

会模拟 4 个角色调用各种工具，展示权限拒绝、数据隔离、审计日志记录的完整效果。

可观测性（OpenTelemetry + 仪表盘）

Phase 4 核心：给 MCP Server 装上"三支柱可观测"——Traces（链路）+ Metrics（指标）+ Logs（审计日志）。让 Server 不只是"能用"，还"可观测、可监控、可对接 APM 平台"——生产级可观测，开箱即用。

三支柱覆盖

Span attributes（OTel 标准 + 业务字段）

每次 MCP 工具调用生成的 Span 含以下 attributes，可对接任何 OTel 后端（Jaeger/Tempo/Grafana/Datadog）：

• mcp.tool.name —— 工具名

• mcp.user.id / mcp.user.role —— 调用者身份

• mcp.tool.result.status —— success / denied / error

• mcp.tool.duration_ms —— 执行耗时（仪表盘侧聚合 P50/P95/P99）

• mcp.tool.args.summary —— 参数摘要（截断 200 字符防膨胀）

• mcp.tool.error.msg —— 错误信息（仅 error/denied 时）

Resource 标识：service.name=property-mcp-server，service.version，deployment.environment。

双出口设计

对接 Jaeger 示例：

# 1. 起 Jaeger（OTLP 接收端口 4318，UI 端口 16686）
docker run -d -p 4318:4318 -p 16686:16686 jaegertracing/all-in-one

# 2. 设环境变量启动 server
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
python server.py

# 3. 在 Trae/Cursor 里调用几个工具，打开 http://localhost:16686 看 trace

可观测仪表盘

独立 HTML 仪表盘（原生 HTML/CSS/JS，零外部依赖，内网可用），从 SQLite 直读数据，5 秒自动刷新：

python dashboard_server.py            # 默认 http://localhost:8765
python dashboard_server.py --port 9000  # 自定义端口

仪表盘展示：

• KPI 卡片：总调用数、成功率、P95 延迟、权限拒绝数

• 工具调用 Top 10：堆叠柱状图（绿/橙/红 = 成功/拒绝/错误）

• 角色调用分布：饼图 + 图例

• 近 24h 调用趋势：SVG 折线图（按小时分桶）

• 报修工单状态漏斗：8 状态分布

• 工作流流转事件：按 action 聚合

• Top 慢调用：耗时最长的工具调用（性能优化定位）

API 端点：

• GET / —— 仪表盘 HTML

• GET /api/metrics —— 全量指标 JSON（observability.get_all_metrics()）

• GET /api/metrics/raw?limit=N —— 最近 N 条审计日志

• GET /api/health —— 健康检查

AI 可读指标（query_observability Tool）

新增 MCP Tool query_observability，让 AI 也能读懂系统健康度并主动报告：

用户：「帮我看看系统运行得怎么样」 AI：（调用 query_observability）→ 返回调用总量、成功率、P95 延迟、工具 Top N、工单漏斗等指标 → AI 总结："系统运行健康，成功率 92%，P95 延迟 15ms，最慢的工具是 create_repair..."

降级安全

OTel SDK 未安装时自动降级为 no-op（_OTEL_AVAILABLE=False），server 正常运行不报错。这让项目在"零依赖"和"全可观测"之间可灵活切换——只装 mcp[cli] 能跑，加装 opentelemetry-* 即获完整可观测能力。

验证可观测性

python test_telemetry.py

验证项：OTel 初始化、Span 生成（success/denied/error 三态）、9 个聚合函数、query_observability Tool 返回 10 个指标块、dashboard_server 4 个端点响应正常。

接入真实数据（数据源切换抽象）

本项目默认用本地 SQLite + 翡翠花园示例数据开箱即跑。要对接真实物业系统时，无需改 server.py / auth.py / workflow.py，只改数据层。

切换方式

# Linux / macOS
export DATA_SOURCE=real
export PROPERTY_API_BASE=https://your-property-system/api
export PROPERTY_API_TOKEN=your-service-token

# Windows
set DATA_SOURCE=real
set PROPERTY_API_BASE=https://your-property-system/api
set PROPERTY_API_TOKEN=your-service-token

不设置 DATA_SOURCE 则默认 mock，走本地 SQLite，零配置。

设计边界：业务数据 vs 系统留痕

db.py 在 real 模式下会把业务数据访问函数替换为 real_adapter.py 的同名函数，但 record_workflow_event / list_workflow_events / init_db / _connect 保持本地，确保留痕和建表逻辑不受影响。

接入真实数据的 11 条隐藏考量

对接真实系统不只是"换数据源"，以下是落地时容易踩的坑（详见 real_adapter.py 顶部 docstring）：

1. 服务凭证：MCP 侧 RBAC 是用户身份，调真实系统还要带服务间凭证（API Key / OAuth），不能把业主身份透传给下游

2. 字段映射：真实系统字段名/结构与 mock 表不一致，需一层 mapper（如 building="1栋" ↔ buildingCode="B01"）

3. 缓存：社区概览/物业费标准/设备清单这类高频低变更数据要加 TTL 缓存（5-10 分钟），避免每次 AI 对话都打下游

4. 降级：关键写操作（报修创建/状态变更）报错，只读统计可返回 last_known + 标记 stale

5. 脱敏：业主手机号/姓名跨系统流转时按最小必要原则脱敏（复用 auth.py 的 mask_owner_info）

6. 写回审批：报修创建/公告发布在真实系统往往有审批流，要先调审批 API 拿 instance_id 再关联

7. 事务一致性：update_repair_flow_state + record_workflow_event 是两步写，真实系统若非同事务需补偿/对账

8. 幂等：MCP 客户端可能重试，create_repair_order 等写接口要带幂等键（业主+房间+描述 hash）

9. 限流/超时：真实 API 设 timeout（3s）+ 重试（1-2 次指数退避），超阈值熔断

10. 审计扩展：audit_logs 仍本地写，但 args_summary 要扩展包含真实系统返回的业务 ID（真实工单号），便于跨系统追溯

11. 业务数据 vs 系统留痕分离：见上表，留痕表始终本地自管

对接工作量

real_adapter.py 已给出 22 个业务数据访问方法的签名骨架，每个方法标注了对接要点。真实物业系统的 API 文档/沙箱账号/服务凭证/审批流对接，通常需要 1-3 个月跨部门协调，远大于代码本身。

项目结构

property-mcp-server/
├── server.py                    # MCP Server 主入口 + 26 tools + 4 resources + 4 prompts
├── auth.py                      # RBAC 权限模型 + 审计日志 + OTel Span 埋点（装饰器实现）
├── workflow.py                  # 报修 Agentic Workflow 状态机引擎（智能分类 + 派工 + 转移规则）
├── telemetry.py                 # OpenTelemetry 初始化 + 双出口（Console + OTLP）+ Span 装饰器
├── observability.py             # 可观测数据聚合层（9 个聚合函数，仪表盘 + Tool 的数据源）
├── dashboard_server.py          # 可观测仪表盘 HTTP server（标准库 http.server，零依赖）
├── dashboard.html               # 仪表盘页面（原生 HTML/CSS/JS，5s 自动刷新）
├── db.py                        # SQLite 数据层 + mock 数据 + 数据源切换（DATA_SOURCE=real 时委托给 real_adapter）
├── real_adapter.py              # 真实物业系统适配器骨架（22 个方法签名 + 11 条隐藏考量，对接真实系统时实现）
├── test_rbac.py                 # 权限模型演示脚本（4 角色场景测试）
├── test_primitives.py           # 全原语验证脚本（Tools + Resources + Prompts）
├── test_workflow.py             # Agentic Workflow 端到端测试（7 状态流转 + HITL + 留痕）
├── test_telemetry.py            # Phase 4 验证（OTel Span + 聚合函数 + 仪表盘端点）
├── handshake_test.py            # stdio 握手测试（验证 34 个原语发现 + stdout 纯净性）
├── demo.py                      # 早期 demo 脚本（独立调用样例）
├── A2_TEST_GUIDE.md             # 四角色场景对话测试清单（13 个场景话术）
├── data/
│   └── property.db              # 数据库（首次运行自动生成，已 gitignore）
├── .trae/
│   └── mcp.json                 # Trae 项目级 MCP 配置（推荐，${workspaceFolder} 跨机器通用）
├── .cursor/
│   └── mcp.json                 # Cursor 项目级 MCP 配置（备选）
├── .gitignore                   # Git 忽略规则（排除 .db / __pycache__ / .venv）
├── requirements.txt             # 依赖：mcp[cli] + opentelemetry-*
├── LICENSE                      # MIT License
├── claude_desktop_config.json   # Claude Desktop 配置示例
└── README.md

预置数据

翡翠花园小区，3 栋楼，6 位业主，5 条报修工单，6 条缴费记录，3 条公告，3 条巡检记录，12 台设备（1 台异常），6 条物业费标准，4 个系统用户（管理员/管家/维修工/业主），4 名维修工（含技能矩阵）。

路线图

1. 对接真实系统：实现 real_adapter.py 的 22 个方法，把 db.py 的 SQLite 操作替换成调用真实物业系统 API（DATA_SOURCE=real 已留好切换抽象，见上方"接入真实数据"章节）

2. MCP 全原语：用 @mcp.resource() 暴露只读数据 + @mcp.prompt() 预置话术模板 ✓ 已完成（4 Resources + 4 Prompts，含动态资源模板）

3. 报修 Agentic Workflow：把报修升级为多步智能流程（智能分类→派工→验收→回访），状态机编排 ✓ 已完成（7 状态机 + 规则分类 + 负载派工 + HITL + 留痕）

4. 权限控制：不同角色能调用的工具不同 ✓ 已完成（RBAC 四角色 + 数据隔离）

5. 审计日志：记录每次工具调用的操作人、时间、参数 ✓ 已完成（audit_logs 表 + denied/success/error 留痕）

6. OpenTelemetry 可观测：工具调用埋 trace，输出延迟/成功率/调用链路 ✓ 已完成（三支柱 + 双出口 + 仪表盘 + AI 可读指标）

技术栈

• MCP SDK：官方 mcp 包的 FastMCP（@mcp.tool() 装饰器）

• 数据库：SQLite（Python 标准库，零配置）

• 权限模型：RBAC 四角色 + 数据级隔离 + 审计日志（@require_role 装饰器）

• 工作流引擎：自研轻量状态机（状态 + 转移规则 + HITL，不引入 LangGraph 重依赖）

• 可观测：OpenTelemetry SDK（TracerProvider + Console/OTLP 双出口）+ 标准库 http.server 仪表盘

• 传输：stdio（Trae / Cursor / Claude Desktop 原生支持）

参考

• MCP 官方文档

• MCP Python SDK

• FastMCP 教程