Property MCP Server
by digitsouler
README.md
# 物业 MCP Server
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](./LICENSE)
[](https://opentelemetry.io/)
[](https://github.com/modelcontextprotocol/python-sdk)
让 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 真正"干活"而非只"问答"
## 演示
### 业主报修对话
业主在 Trae 里说"我家厨房漏水，要报修" → AI 自动追问房间号 → 调 `create_repair` 建单。无需登录工单系统，口语直接驱动工具。
### 报修工作流 HITL 派工
`run_repair_workflow` 一键编排：创建 → 智能分类 → 派工建议（HITL 暂停等管家确认）→ 派工 → 处理 → 验收 → 关闭。分类结果、推荐师傅全部可见。
### 可观测仪表盘
调用总量 / 成功率 / P95 延迟 / 工具 Top N / 角色分布 / 工单漏斗 / 工作流事件 / Top 慢调用，5 秒自动刷新，零额外依赖启动。
***
**一句话效果**：业主说句话 → AI 自动建单 → 工作流自动跑分类 / 派工 / HITL 确认 → 每一步在 `workflow_events` 留痕 → 仪表盘实时反映调用指标。
## 快速开始
### 1. 安装依赖
```bash
cd property-mcp-server
pip install -r requirements.txt
```
> 需要 Python 3.10+
### 2. 验证 server 能启动
```bash
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` 工具
配置内容（已预置，无需手动修改）：
```json
{
"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`
加入以下内容（路径改成你自己的）：
```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 共享同一套话术模板逻辑，效果完全一致，保证所有客户端可用。
## 工具列表
| 工具 | 功能 | 关键参数 |
| ------------------------------ | --------------------------------- | ----------------------------------------------- |
| `create_repair` | 创建报修工单 | building, room, category, description, priority |
| `query_repairs` | 查询工单列表 | building ?, status ?, limit ? |
| `update_repair` | 更新工单状态 | order\_id, status, note? |
| `get_owner` | 查询业主信息 | building, room |
| `list_owners_by_building` | 业主列表 | building ?, limit ? |
| `search_owner` | 模糊搜索业主 | keyword |
| `query_payments` | 查询缴费记录 | building ?, room ?, status ?, limit ? |
| `query_arrears` | 查询欠费汇总 | building ? |
| `publish_notice` | 发布公告 | title, content, category ?, target\_building? |
| `query_notices` | 查询公告 | building ?, limit ? |
| `create_inspection` | 创建巡检记录 | inspector, location, item, result, notes ? |
| `query_audit_logs` | 查询审计日志（仅管理员） | user\_id ?, status ?, limit ? |
| `generate_collection_reminder` | 生成催缴话术 | owner\_name, amount, period |
| `generate_repair_guide` | 生成报修引导话术 | sympromt ? |
| `generate_complaint_response` | 生成投诉处理话术 | complaint, complainant ? |
| `generate_notice` | 生成公告草稿 | topic, target\_building ? |
| `run_repair_workflow` | **一键编排报修工作流**（自动分类+派工建议，停 HITL 点） | order\_id |
| `classify_repair` | 智能分类工单（规则引擎） | order\_id |
| `suggest_repair_assignment` | 智能派工建议（技能+负载均衡） | order\_id |
| `confirm_repair_assignment` | 管家确认派工（HITL 确认点） | order\_id, worker\_name ? |
| `start_repair_work` | 维修工接单 | order\_id |
| `complete_repair_work` | 维修工完工提交 | order\_id, summary |
| `accept_repair_work` | 验收（通过/驳回返工） | order\_id, accepted, comment ? |
| `visit_repair` | 满意度回访关闭工单 | order\_id, satisfaction, comment ? |
| `get_repair_workflow` | 查询工单流转历史 | order\_id |
## Resources（只读数据原语）
Resources 是 MCP 的第二大原语，用于暴露只读参考数据。与 Tools 不同：Tools 是 AI 主动调用的动作，Resources 是 AI **自动加载的上下文**。
| URI | 类型 | 说明 |
| ------------------------------------ | ---- | ---------------------------------------------------- |
| `property://community/overview` | 静态 | 小区概览：楼栋数、业主数、工单统计、欠费汇总、设备状态（业主角色欠费金额脱敏） |
| `property://devices/list` | 静态 | 设备清单：12 台设备的名称、位置、类别、巡检周期、责任人、状态 |
| `property://convention` | 静态 | 业主公约：装修/宠物/垃圾/停车/公共区域/缴费 6 章规约 |
| `property://fee-standard/{building}` | 动态模板 | 物业费标准：按楼栋查询物业费、停车费单价（如 `property://fee-standard/2栋`） |
> **动态资源模板**是 MCP 高级用法：用 URI 模板 `property://fee-standard/{building}` 暴露参数化资源，客户端填入楼栋即可查询对应标准，无需为每栋楼单独注册。
**使用场景**：在 Trae/Cursor 里直接问「小区现在情况怎么样」「2栋物业费多少钱」「有哪些设备需要巡检」「装修有什么规定」，AI 会自动加载对应 Resource 作为上下文再回答，不需要显式调用工具。
## Prompts（提示词模板原语）
Prompts 是 MCP 的第三大原语，用于预置结构化提示词模板。在 Trae/Cursor 中，用户输入 `/` 即可看到可用模板，填入参数后生成标准化话术。价值：让一线管家/客服执行任务时话术规范统一，不依赖个人经验。
| 模板 | 说明 | 参数 |
| ---------------------- | ----------------- | --------------------------- |
| `/collection_reminder` | 催缴话术：生成得体的欠费催缴通知 | owner\_name, amount, period |
| `/repair_guide` | 报修引导：引导业主详细描述报修问题 | symptom ? |
| `/complaint_handler` | 投诉处理：按标准流程处理业主投诉 | complaint, complainant ? |
| `/notice_drafter` | 公告起草：根据主题生成规范小区公告 | topic, target\_building ? |
**使用场景**：管家在 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 点暂停等管家确认。适合新工单快速启动处理流程。
### 验证工作流
```bash
python test_workflow.py
```
会验证：智能分类器准确率、智能派工负载均衡、7 状态完整流转、HITL 暂停、非法转移拦截、全程留痕、一键编排。
**在 Trae/Claude 里体验**：
- 「帮我跑一下 1 号工单的报修流程」→ 触发 `run_repair_workflow`，自动分类+派工建议
- 「确认派工给李师傅」→ 触发 `confirm_repair_assignment`
- 「查一下 1 号工单的处理记录」→ 触发 `get_repair_workflow`，看完整流转历史
### 验证全原语
```bash
python test_primitives.py
```
会验证 16 个 Tools + 4 个 Resources + 4 个 Prompts 全部注册正确、数据可读、话术可生成、权限脱敏生效。
## 权限模型（RBAC + 审计日志）
### 四角色权限矩阵
| 工具 | admin 管理员 | steward 管家 | repairman 维修工 | owner 业主 |
| -------------------------- | :-------: | :--------: | :-----------: | :------: |
| create\_repair | ✓ | ✓ | — | ✓（限本户） |
| query\_repairs | ✓ | ✓ | ✓ | ✓（限本栋） |
| update\_repair | ✓ | ✓ | ✓ | — |
| get\_owner | ✓ | ✓ | — | ✓（限本户） |
| list\_owners\_by\_building | ✓ | ✓ | — | — |
| search\_owner | ✓ | ✓ | — | — |
| query\_payments | ✓ | ✓ | — | ✓（限本户） |
| query\_arrears | ✓ | ✓ | — | — |
| publish\_notice | ✓ | ✓ | — | — |
| query\_notices | ✓ | ✓ | ✓ | ✓（限本栋） |
| create\_inspection | ✓ | ✓ | ✓ | — |
| query\_audit\_logs | ✓ | — | — | — |
### 数据级隔离
业主角色（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 | 角色 | 说明 |
| ---- | -------------------- | ------------ |
| `u1` | admin 管理员 | 全部权限 + 查审计日志 |
| `u2` | steward 管家 | 业务管理类，不能查审计 |
| `u3` | repairman 维修工 | 工单处理 + 巡检 |
| `u4` | owner 业主（张伟 1栋1-502） | 数据隔离演示 |
改成对应 ID 后重启客户端，即可用不同身份对话，体验权限隔离效果。
### 验证权限模型
```bash
python test_rbac.py
```
会模拟 4 个角色调用各种工具，展示权限拒绝、数据隔离、审计日志记录的完整效果。
## 可观测性（OpenTelemetry + 仪表盘）
Phase 4 核心：给 MCP Server 装上"三支柱可观测"——**Traces（链路）+ Metrics（指标）+ Logs（审计日志）**。让 Server 不只是"能用"，还"可观测、可监控、可对接 APM 平台"——生产级可观测，开箱即用。
### 三支柱覆盖
| 支柱 | 实现 | 数据源 |
| ----------- | --------------------------------------- | ----------------------------------------------- |
| **Traces** | OTel SDK + Span 装饰器（`require_role` 内集成） | 每次 MCP 工具调用一个 Span |
| **Metrics** | `observability.py` SQL 聚合 + 仪表盘 | audit\_logs / workflow\_events / repair\_orders |
| **Logs** | Phase 1 已建的 `audit_logs` 表 | user/role/tool/status/duration 全字段 |
### 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`。
### 双出口设计
| 出口 | 开关 | 用途 |
| ------------------------ | ----------------------------------- | -------------------------- |
| **Console SpanExporter** | 默认开启，`OTEL_CONSOLE_EXPORTER=off` 关闭 | 开发调试，stderr 直接看 trace JSON |
| **OTLP HTTP Exporter** | 设 `OTEL_EXPORTER_OTLP_ENDPOINT` 开启 | 生产对接 Jaeger/Tempo/Grafana |
对接 Jaeger 示例：
```bash
# 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 秒自动刷新：
```bash
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-*` 即获完整可观测能力。
### 验证可观测性
```bash
python test_telemetry.py
```
验证项：OTel 初始化、Span 生成（success/denied/error 三态）、9 个聚合函数、`query_observability` Tool 返回 10 个指标块、dashboard\_server 4 个端点响应正常。
## 接入真实数据（数据源切换抽象）
本项目默认用本地 SQLite + 翡翠花园示例数据开箱即跑。要对接真实物业系统时，**无需改 server.py / auth.py / workflow.py**，只改数据层。
### 切换方式
```bash
# 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 系统留痕
| 数据类型 | real 模式走向 | 原因 |
|---------|-------------|------|
| 业务数据（业主/工单/缴费/公告/巡检/设备/物业费/用户） | 真实物业系统 API | 这些是真实业务，AI 要读到实时数据 |
| 系统留痕（audit\_logs / workflow\_events） | 始终本地 SQLite | 留痕是 MCP Server 自己的行为记录，不应依赖真实业务系统可用性 |
`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 官方文档](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [FastMCP 教程](https://gofastmcp.com)
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessNo issues