belle-mcp-server

一个参考性的 Model Context Protocol (MCP) 服务器，将 Belle Realty 真实的物业管理数据——物业、租户、租约、维护工单、租金账册——以工具的形式暴露出来，Claude Desktop、Cursor 或任何兼容 MCP 的客户端都可以直接调用。

共六个工具：五个严格只读，一个是 HITL 门控的提议写入。这个比例是刻意为之，也正是本仓库的全部意义所在。

是 AI Fluency Program — Level 2 的一部分。

为什么做这个

大多数“AI + 你的数据”演示都会让模型拥有不受限制的数据库访问权限。那是一个隐患。

Model Context Protocol 的设计初衷是暴露一个小而精的接口面，并配备按工具划分的认证、速率限制和审计——与你会应用于公共 REST API 的准则一致。本仓库展示了这在真实领域（一个路易斯安那州的购物中心）中是什么样子：包含真实的 Postgres schema、一套可用的种子数据，以及一条 HITL 门控的写入路径。

如果你理解了本仓库，你就能为你经营的任何业务构建一个同样的系统。

你能得到什么

每次调用都有速率限制（默认 60 次/分钟），并审计记录到 mcp_audit_log。

快速开始

# 1. Clone + install
git clone https://github.com/OrangeOnyx/belle-mcp-server.git
cd belle-mcp-server
npm install

# 2. Configure
cp .env.example .env
# Paste your Supabase URL + service-role key

# 3. Set up the schema (Supabase project)
#    Copy supabase/migrations/0001_init.sql into the SQL editor and run.

# 4. Seed demo data
npm run db:seed

# 5. Build + inspect
npm run build
npm run inspect

MCP Inspector 会打开一个 UI，你可以在其中列出工具、调用工具并查看原始响应。

接入 Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)，或 Windows/Linux 上对应的位置：

{
  "mcpServers": {
    "belle-realty": {
      "command": "node",
      "args": ["/absolute/path/to/belle-mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

重启 Claude Desktop。你现在会看到一个 belle-realty 工具集。试试：

“On The Boulevard 目前有哪些单元已出租，它们每月产生多少租金？”

Claude 会调用 get_rent_roll，并根据返回的数据作答。

HITL 写入模式

唯一的写入工具（draft_maintenance_response）演示了一个通用模式，你应该为任何面向 AI 的服务采用它：

1. AI 提出一个变更——这里是指对租户维护工单的回复。

2. 服务器将其保存为 approved=false。

3. 在人工另行批准（通常是在物业经理的管理后台 UI 中）之前，任何内容都不会被投递、发送或应用。

4. MCP 工具面刻意不提供名为 approve 的工具。审批是仅限人工的操作。

这意味着，一个过于急切或遭到提示注入的智能体无法悄无声息地把文本推送给租户。它可以提议，而且可以大声地提议，但它无法真正发出去。

更详细的分步说明，请参阅 docs/hitl-pattern.md。

个人使用指南

你是一个个人房东，拥有 3 套出租房或一栋小型商业楼宇。

1. 在你的 Supabase 项目上运行迁移。

2. 用你自己的数据填充（编辑 supabase/seed.ts，或手动插入行）。

3. 将 Claude Desktop 指向该服务器。

4. 提出类似“哪个租户的租约将在未来 90 天内到期？”或“草拟一份关于热水器工单的回复。”这样的问题。

你现在已经构建了一个能读懂你数据的 AI 原生租户运营层。只花了你一个晚上。

公司使用指南

你经营着 Belle Realty（或一家类似的管理公司）。多名员工需要让 Claude 访问物业组合数据，而无需查看原始 SQL，也不用担心意外写入的风险。

1. 将此服务器部署为常驻进程（Railway、Fly 或 Docker 主机）。

2. 设置 MCP_TRANSPORT=http 和 MCP_HTTP_TOKEN=<shared-secret>。

3. 每位团队成员使用 URL + token 配置 Claude Desktop 或 Cursor。

4. 只读工具让每个人都能借力。唯一的写入工具保护着租户关系。

5. mcp_audit_log 为你提供每项 AI 操作的事后记录。

架构

graph LR
    A[Claude Desktop / Cursor] -->|MCP stdio or HTTP| B[belle-mcp-server]
    B --> C[RateLimiter]
    B --> D[Zod validation]
    B --> E[Supabase Postgres]
    B --> F[mcp_audit_log]
    E --> G[(properties, tenants, leases, tickets)]

详见 docs/architecture.md。

扩展

通过 4 个步骤添加一个新工具：

1. 在 src/schemas/domain.ts 中为输入添加一条 Zod schema（如果数据形态是新的）。

2. 创建 src/tools/<name>.ts，包含一个 input schema、一个 handler 和一个 JSON-Schema 定义。

3. 在 src/tools/index.ts 中注册它。

4. 在 tests/ 中添加测试。

每个写入工具都应遵循 draft_maintenance_response 中的提议写入模式。

部署

Railway（推荐用于 HTTP 传输）

railway up

railway.json 会构建服务器并运行 node dist/index.js。在 Railway 仪表盘中设置环境变量。

本地（仅 stdio）

只需构建，然后将你的 MCP 客户端指向 dist/index.js。无需托管。

开发

npm run dev       # tsx watch mode
npm run test      # vitest
npm run build     # tsc → dist/
npm run inspect   # MCP Inspector UI

相关仓库

• lease-abstractor — 从租约 PDF/DOCX 中提取结构化摘要

• support-triage-agent — 将相同的 HITL 模式应用于支持消息

• diligence-agent — 基于 RAG 对文档文件夹进行尽职调查

• ai-fluency-program — 所属课程体系

许可证

MIT — 请参阅 LICENSE。

不构成法律、税务或物业管理建议。在没有持证专业人士参与的情况下，请勿将其用于合规关键决策。