关于 Meta Business Mcp
Meta Business MCP 为 WhatsApp Business 自动化团队和 Agent 开发者提供消息合规与编排服务。它检查 Meta 规则和业务策略,并提供错误分析、模板管理及异步消息投递。
主要功能
- 01发送前检查合规性
- 02执行业务策略和频率限制
- 03异步发送并自动重试消息
- 04分析 Meta API 错误
- 05管理模板与营销活动
适用场景
- 01检查消息是否符合规则后再发送
- 02查询会话状态、客户资格和送达情况
- 03安排面向筛选受众的模板营销活动
MCP 相关
服务通过 stdio 上的 MCP 向 AI Agent 提供 24 个工具,涵盖消息、合规、模板、会话及营销活动操作。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
我们还没有获取到这个服务的安装包或远程地址,请按项目 README 中的说明安装。
工具
本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。
详细介绍
Meta Business MCP
Go 1.21+ License: Apache 2.0 Tests: Passing Coverage: 85.6% Tools: 24 Production-Validated
WhatsApp 合规智能平台,确保每个 AI Agent 都能安全、合规且可用于生产环境地运营 WhatsApp Business,而无需理解 Meta 复杂的规则。
适用对象: AI Agent 开发者 · 数字营销机构 · WhatsApp 自动化团队 21 个工具永久免费 · Pro 版提供 3 个营销活动工具
目录
为何构建此项目
AI Agent 不理解 Meta 的 WhatsApp Business 规则,例如 24 小时客服窗口、频次上限、模板类别、退订要求和速率限制。哪怕只发错一条消息,也可能导致账号停用、消息被拒和违规。Meta Business MCP 位于 AI Agent 与 Meta API 之间,自动执行所有规则,让 Agent 无需学习这些规则。
功能介绍
| 职责 | 说明 |
|---|---|
| 合规检查 | 在发送前,根据 Meta 的客服窗口规则、退订名单和频次上限检查每条出站消息。 |
| 策略执行 | 根据 YAML 初始化的数据库应用自定义业务策略(时间范围、排除的用户细分、VIP 标签覆盖规则)。 |
| 异步消息发送 | 将消息加入 NATS JetStream 队列,并通过工作池发送,支持自动重试和指数退避。 |
| 速率限制 | 通过 Redis Lua 脚本执行针对每位客户的令牌桶速率限制。 |
| 错误智能处理 | 将 Meta API 数字错误代码转换为分类明确、可执行的开发者指引。 |
| 营销活动管理 | 安排、暂停和取消营销活动,并支持受众细分和模板验证。 |
| 模板生命周期管理 | 通过 Meta API 创建、同步和验证模板,并在本地持久化。 |
| MCP 服务 | 使用 Model Context Protocol,通过标准输入/输出向 AI Agent 提供 24 个结构化工具。 |
| Webhook 接收器 | 处理来自 Meta 的入站事件:客户消息、送达状态更新和模板审批回调。 |
快速开始
1. 克隆并启动
git clone https://github.com/metabusiness-mcp/meta-business-mcp.git
cd meta-business-mcp
docker compose up -d --build
等待所有容器变为健康状态:
docker compose ps
# All should show "healthy"
2. 打开控制面板
在浏览器中打开:http://localhost:8080
首次运行时,服务会自动生成一个随机密码并打印到终端:
╔══════════════════════════════════════════════════════════╗
║ DASHBOARD CREDENTIALS (auto-generated) ║
╠══════════════════════════════════════════════════════════╣
║ Username: admin ║
║ Password: a1b2c3d4e5f6g7h8 ║
╚══════════════════════════════════════════════════════════╝
复制密码并登录。
3. 连接 AI Agent
MCP 服务通过标准输入/输出运行。配置你的 AI 客户端(Claude Desktop、Cursor 等):
{
"mcpServers": {
"meta-business-mcp": {
"command": "/path/to/meta-business-mcp",
"args": []
}
}
}
4. 验证
curl http://localhost:8080/health
# OK
启动的服务: PostgreSQL 16(:5432)、Redis 7(:6379)、NATS JetStream(:4222)、Mock Meta API(:8081)、Meta Business MCP(:8080 + MCP 标准输入/输出)。默认使用模拟凭据——本地开发无需 Meta API 密钥。
MCP 工具
全部 24 个工具均通过标准输入/输出使用 Model Context Protocol 提供给 AI Agent。所有工具均已达到生产就绪状态,并通过真实 WABA 生产环境(Meta Graph API v20.0)验证。
操作工具
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
check_compliance() | 评估计划发送的出站消息是否符合 Meta 规则和本地政策 | [All] | ✅ |
send_message() | 发送自由格式服务文本消息(需要处于有效的 24 小时服务窗口内) | [All] | ✅ |
send_template() | 发送已获批准的模板消息(不受 24 小时服务窗口限制) | [All] | ✅ |
explain_error() | 将 Meta API 错误代码转换为分类清晰、可采取行动的说明 | [All] | ✅ |
reply_customer() | 在有效的对话上下文中回复(需要处于开启的 24 小时窗口内) | [All] | ✅ |
retry_failed_messages() | 验证消息是否可重试,并手动触发一条或多条失败消息的重试 | [All] | ✅ |
sync_template_status() | 从 Meta API 同步模板审批状态并更新本地数据库 | [All] | ✅ |
只读智能查询
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
check_conversation() | 查询对话窗口状态、剩余时间、类型和资格 | [All] | ✅ |
check_frequency_cap() | 检查客户是否达到 Meta 营销消息频次上限 | [All] | ✅ |
get_customer_context() | 获取完整客户资料:选择加入/退出状态、标签、互动评分、资格 | [All] | ✅ |
get_delivery_status() | 查询消息送达状态(已发送/已送达/已读/失败)及错误详情 | [All] | ✅ |
get_rate_limit() | 查询当前 MPS 容量、已消耗令牌数和剩余令牌数 | [All] | ✅ |
list_conversations() | 按筛选条件列出对话:开启、已关闭、即将过期 | [All] | ✅ |
list_templates() | 从 Meta API 按状态/类别/区域设置筛选并列出模板 | [All] | ✅ |
调度与营销活动
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
schedule_message() | 通过合规性预检查,将单条消息安排在未来发送 | [All] | ✅ |
schedule_campaign() | 使用已获批准的模板和受众筛选条件安排广播营销活动 | [Pro] | ✅ |
cancel_campaign() | 取消处于非终止状态(已安排/运行中/已暂停)的营销活动 | [Pro] | ✅ |
pause_campaign() | 暂停正在进行的营销活动,并保留进度计数器以便恢复 | [Pro] | ✅ |
账户与成本智能查询
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
get_account_quality() | 从 Meta 获取 WABA 质量评分和消息发送限额层级 | [All] | ✅ |
estimate_cost() | 估算计划消息批次的对话成本 | [All] | ✅ |
estimate_pricing() | 查询指定国家/类型组合当前的对话定价层级 | [All] | ✅ |
运维
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
create_template() | 向 Meta 提交新模板以供审批,并在本地保存为 PENDING | [All] | ✅ |
sync_webhooks() | 手动触发模板状态和待处理 Webhook 事件的重新同步 | [All] | ✅ |
archive_chat() | 将处于终止状态(窗口已过期)的对话归档 | [All] | ✅ |
完整参数规范和响应示例:docs/api_reference.md
架构
双模式二进制文件
该平台编译为单个 Go 二进制文件,可同时运行两个服务:
| 模式 | 传输方式 | 用途 |
|---|---|---|
| MCP 服务 | stdio(stdin/stdout) | 向 AI 客户端(Gemini、Claude、Cursor)公开 24 个结构化工具 |
| HTTP 服务 | TCP :8080 | Webhook 接收器、健康检查、Prometheus 指标 |
高层组件图
┌───────────────────────────────┐
│ AI Agent │
└──────────────┬────────────────┘
│ Stdio (MCP Protocol)
▼
┌────────────────────────────────────────────────────────┐
│ Meta Business MCP │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ MCP Server ├───────►│ Compliance Engine │ │
│ └───────────────────┘ └─────────┬─────────┘ │
│ ▼ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ Webhook Receiver │ │ Policy Engine │ │
│ └─────────▲─────────┘ └─────────┬─────────┘ │
│ │ ▼ │
│ │ ┌───────────────────┐ │
│ │ │ Orchestrator │ │
│ │ └─────────┬─────────┘ │
└─────────────┼────────────────────────────┼─────────────┘
│ Webhook │ POST /messages
│ ▼
┌─────────────┴────────────────────────────┴─────────────┐
│ Meta Cloud API (or Mock :8081) │
└────────────────────────────────────────────────────────┘
核心服务
| 服务 | 包 | 作用 |
|---|---|---|
| MCP 服务 | pkg/mcp/ | 注册并处理来自 AI Agent 的 24 个 MCP 工具调用。拆分为 6 个处理器文件(约 2,000 行)。 |
| 合规引擎 | pkg/compliance/ | 强制执行 24 小时服务窗口、选择退出/选择加入状态和频次上限。 |
| 策略引擎 | pkg/policy/ | 根据数据库评估动态业务规则(时间限制、标签排除)。 |
| 对话状态引擎 | pkg/state/ | 使用 Redis 缓存和 PostgreSQL 回退机制管理服务窗口 TTL。 |
| 用户智能 | pkg/userintel/ | 跟踪选择加入状态、标签(例如 vip)和互动时间线。 |
| 模板管理器 | pkg/template/ | 从 Meta 同步已批准的模板、验证变量并在本地缓存。 |
| 投递编排器 | pkg/delivery/ | 将消息加入 NATS JetStream 队列;管理后台工作池。 |
| 调度器 | pkg/delivery/ | 用于定时消息和营销活动的进程内轮询式调度器。 |
| 速率限制器 | pkg/ratelimit/ | 通过 Redis Lua 脚本实现按客户划分的令牌桶速率限制。 |
| 错误智能 | pkg/errorintel/ | 将 Meta 错误代码映射为是否重试的分类和说明。 |
| 营销活动模块 | pkg/campaign/ | 营销活动架构、受众筛选条件和按层级限制的操作。 |
| Webhook 接收器 | pkg/webhook/ | 解析并分发传入的 Meta 事件(消息、状态、模板)。 |
| 可观测性 | pkg/observability/ | 自定义 Prometheus 指标。 |
持久化层
| 层 | 技术 | 用途 |
|---|---|---|
| 主数据库 | PostgreSQL 16(pgxpool) | 所有持久化数据:对话、消息、客户、模板、策略、营销活动、审计日志。 |
| 缓存 | Redis 7 | 服务窗口 TTL 状态;通过 Lua 脚本维护令牌桶计数器;提供优雅的 PG 回退机制。 |
| 消息代理 | NATS JetStream | 异步投递队列,采用 WorkQueue 保留策略和拉取式消费者。 |
数据库架构(ER 图)
erDiagram
customers ||--o{ conversations : has
conversations ||--o{ messages : contains
templates ||--o{ messages : sent_as
messages }|--o{ message_frequencies : logs
customers {
varchar id PK "Phone Number"
varchar channel
boolean opt_in_marketing
boolean opt_in_utility
timestamp last_interaction_at
double engagement_score
text_array tags
}
conversations {
uuid id PK
varchar customer_id FK
varchar channel
timestamp last_inbound_at
timestamp last_outbound_at
timestamp window_expires_at
varchar conversation_type
varchar active_template_id
varchar status "active/archived"
}
messages {
varchar id PK "Meta Message ID or UUID"
uuid conversation_id FK
varchar customer_id FK
varchar direction "inbound/outbound"
varchar message_type "text/template"
jsonb content
varchar status "queued/sent/delivered/read/failed/scheduled"
integer error_code
text error_message
integer retry_count
timestamp next_retry_at
timestamp deliver_at "nullable, for scheduled messages"
}
templates {
varchar name PK
varchar locale PK
varchar category "marketing/utility"
varchar status
text body_text
jsonb variables
}
policies {
varchar id PK
varchar name
varchar type
varchar channel
varchar message_type
boolean is_enabled
jsonb rules
}
error_knowledge_base {
integer code PK
varchar category
boolean can_retry
text human_explanation
text suggested_action
}
audit_logs {
uuid id PK
varchar action
jsonb details
timestamp created_at
}
NATS JetStream 队列拓扑
| 流 | 主题 | 消费者 | 最大投递次数 | 确认等待时间 | 退避 |
|---|---|---|---|---|---|
META_MCP_DELIVERY | whatsapp.messages.outbound, whatsapp.messages.retry | delivery-workers(持久化拉取) | 3 | 30s | 1s → 5s(NakWithDelay) |
META_MCP_CAMPAIGN | whatsapp.campaigns.trigger | campaign-workers | — | — | — |
Redis 缓存策略
- 缓存键模式:
conv:<customer_id>:<channel>(例如conv:628119989630:whatsapp) - TTL:动态设置为 24 小时服务窗口的精确剩余时长。
- 优雅回退:如果 Redis 离线,状态引擎会无错误地回退到 PostgreSQL——已通过故障模拟测试验证。
- 电话号码格式:内部缓存和数据库存储的号码不带前导
+。MCP 工具边界会规范化带+前缀的输入。
与渠道无关的架构。WhatsApp 是当前启用的渠道。Messenger 和 Instagram 是计划启用的目标,并非路线图承诺。
完整架构文档:docs/architecture.md
配置
配置文件(config.yaml)
本地开发时,将 config.yaml 放在项目根目录:
server:
http_port: 8080
mcp_name: "meta-business-mcp"
mcp_version: "1.0.0"
database:
host: "localhost"
port: 5432
user: "postgres"
password: "password"
dbname: "meta_mcp"
sslmode: "disable"
redis:
addr: "localhost:6379"
nats:
url: "nats://localhost:4222"
meta:
api_url: "http://localhost:8081" # Use mock server for offline dev
phone_number_id: "mock-phone-id"
waba_id: "mock-waba-id"
access_token: "mock-access-token"
webhook_verify_token: "mock-verify-token"
policies_path: "policies.yaml"
tier: "oss" # oss | pro | enterprise
环境变量
所有配置值都可以通过环境变量覆盖。必填项以 ✅ 标记。
| 变量 | 默认值 | 必填 | 描述 |
|---|---|---|---|
SERVER_HTTP_PORT | 8080 | — | HTTP 服务端口 |
SERVER_MCP_NAME | "meta-business-mcp" | — | MCP 服务标识符 |
SERVER_MCP_VERSION | "1.0.0" | — | MCP 服务版本字符串 |
DB_HOST | "localhost" | — | PostgreSQL 主机 |
DB_PORT | 5432 | — | PostgreSQL 端口 |
DB_USER | "postgres" | — | PostgreSQL 用户名 |
DB_PASSWORD | "password" | — | PostgreSQL 密码 |
DB_NAME | "meta_mcp" | — | PostgreSQL 数据库名称 |
DB_SSLMODE | "disable" | — | disable、require 或 verify-ca |
REDIS_ADDR | "localhost:6379" | — | Redis 连接地址 |
REDIS_PASSWORD | "" | — | Redis 身份验证密码 |
REDIS_DB | 0 | — | Redis 数据库索引 |
NATS_URL | "nats://localhost:4222" | — | NATS 连接 URL |
META_API_URL | "https://graph.facebook.com" | — | Meta Graph API 基础 URL |
META_ACCESS_TOKEN | — | ✅ | Meta API OAuth 令牌(系统用户) |
META_PHONE_NUMBER_ID | — | ✅ | WhatsApp Business 电话号码 ID |
META_WABA_ID | — | ✅ | WhatsApp Business 账户 ID |
META_WEBHOOK_VERIFY_TOKEN | — | ✅ | Meta webhook 验证口令 |
POLICIES_PATH | "policies.yaml" | — | 业务策略种子 YAML 文件的路径 |
TIER | "oss" | — | 功能层级:oss、pro 或 enterprise |
SCHEDULER_POLL_INTERVAL | "30s" | — | 调度器对计划消息/营销活动的轮询间隔 |
业务策略(policies.yaml)
应用启动时会从 policies.yaml 导入业务策略,并将其存储在 policies 表中。种子脚本具有幂等性(ON CONFLICT DO UPDATE),因此重启应用即可应用更改。
- id: "no_marketing_after_8pm"
name: "No marketing after 8pm"
type: "time_restriction"
channel: "whatsapp"
message_type: "marketing"
is_enabled: true
rules:
deny_after: "20:00"
timezone: "Asia/Jakarta"
完整的环境变量参考:docs/env_variables.md
测试
运行所有测试
go test -count=1 -p 1 -cover ./...
运行合规性基准测试
go test -bench=BenchmarkCheckCompliance -benchtime=5s ./pkg/compliance/
包覆盖率(Sprint 2)
| 包 | 覆盖率 |
|---|---|
pkg/compliance | 93.9% |
pkg/errorintel | 100.0% |
pkg/config | 96.2% |
pkg/observability | 100.0% |
pkg/ratelimit | 87.5% |
pkg/webhook | 83.6% |
pkg/state | 83.3% |
pkg/userintel | 82.1% |
pkg/policy | 79.5% |
pkg/template | 78.9% |
pkg/campaign | 77.1% |
pkg/delivery | 73.8% |
pkg/mcp | 61.6% |
测试套件
| 套件 | 文件 | 测试数 | 状态 |
|---|---|---|---|
| v1 处理器 | pkg/mcp/server_test.go | 5(check_compliance、explain_error、send_message、send_template、电话号码规范化) | ✅ |
| A 组 — 智能功能 | pkg/mcp/server_test.go | 8(check_conversation、check_frequency_cap、get_customer_context、get_delivery_status ×2、get_rate_limit、list_templates、list_conversations) | ✅ |
| B 组 — 消息 | pkg/mcp/server_test.go | 5(reply_customer ×2、retry_failed_messages ×2、sync_template_status) | ✅ |
| C 组 — 营销活动 | pkg/mcp/server_test.go | 5(schedule_message ×2、营销活动层级限制 ×3) | ✅ |
| D 组 — 账户 | pkg/mcp/server_test.go | 4(estimate_cost、estimate_pricing、get_account_quality) | ✅ |
| E 组 — 运维 | pkg/mcp/server_test.go | 3(archive_chat ×2、sync_webhooks) | ✅ |
| 调度器 | pkg/delivery/scheduler_test.go | 5(到期消息、未来消息、合规性失败、重复派发、营销活动触发) | ✅ |
| 集成测试 | tests/integration_test.go | 7 | ✅ |
| 端到端测试 | tests/e2e_test.go | 3 | ✅ |
| 故障模拟 | tests/failure_test.go | 4(Redis 中断、NATS 中断、Meta 500、Meta 131049) | ✅ |
基准测试结果
| 工具 | 延迟 | 与目标相比 |
|---|---|---|
check_compliance() | 1.69 ms | 比 50ms 目标快约 30 倍 |
部署
构建二进制文件
go build -o mcp-server ./cmd/server/main.go
生产环境(.env)
SERVER_HTTP_PORT=8080
SERVER_MCP_NAME=meta-business-mcp
SERVER_MCP_VERSION=1.0.0
TIER=oss
DB_HOST=postgres.prod.internal
DB_PORT=5432
DB_USER=mcp_user
DB_PASSWORD=production_secure_postgres_pass
DB_NAME=meta_mcp
DB_SSLMODE=require
REDIS_ADDR=redis.prod.internal:6379
REDIS_PASSWORD=production_redis_auth_pass
REDIS_DB=0
NATS_URL=nats://nats.prod.internal:4222
META_API_URL=https://graph.facebook.com
META_ACCESS_TOKEN=EAAG...production_long_lived_system_user_token...
META_PHONE_NUMBER_ID=106555123456789
META_WABA_ID=204555123456789
META_WEBHOOK_VERIFY_TOKEN=production_webhook_verification_passphrase
POLICIES_PATH=/app/policies.yaml
SCHEDULER_POLL_INTERVAL=30s
生产环境 Docker Compose
services:
postgres:
image: postgres:16-alpine
restart: always
environment:
POSTGRES_USER: mcp_user
POSTGRES_PASSWORD: production_secure_postgres_pass
POSTGRES_DB: meta_mcp
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U mcp_user -d meta_mcp"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7-alpine
restart: always
command: redis-server --requirepass production_redis_auth_pass
volumes:
- redisdata:/data
healthcheck:
test: ["CMD", "redis-cli", "-a", "production_redis_auth_pass", "ping"]
interval: 10s
timeout: 5s
retries: 5
nats:
image: nats:alpine
restart: always
command: "--jetstream -m 8222"
ports:
- "4222:4222"
volumes:
- natsdata:/data
healthcheck:
test: ["CMD", "nc", "-z", "localhost", "4222"]
interval: 10s
timeout: 5s
retries: 5
app:
build:
context: .
dockerfile: Dockerfile
restart: always
ports:
- "8080:8080"
env_file:
- .env
volumes:
- ./policies.yaml:/app/policies.yaml
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
nats:
condition: service_healthy
volumes:
pgdata:
redisdata:
natsdata:
docker compose -f docker-compose.prod.yaml up -d --build
数据库迁移与播种
无需外部迁移运行器。应用启动时会自动:
- 创建所有数据库表(
customers、conversations、messages、templates、policies、campaigns、message_frequencies、error_knowledge_base、audit_logs、conversation_pricing)。 - 将 Meta 标准错误代码写入
error_knowledge_base。 - 使用幂等的
ON CONFLICT DO UPDATE从policies.yaml写入业务策略。 - 写入 ID、US、IN、BR、GB 的会话定价数据,以及 DEFAULT 回退项。
所有架构变更均使用 IF NOT EXISTS / ADD COLUMN IF NOT EXISTS。现有部署只需重启应用即可升级。
Webhook 注册
在 Meta App Developer Portal 中注册公开 URL:
- 验证:
GET /webhook— 返回hub.challenge。 - 事件:
POST /webhook— 接收入站消息、状态更新和模板事件。 - 签名验证:验证所有 POST 事件的
X-Hub-Signature-256标头。
基础设施依赖项
| 依赖项 | 最低版本 | 备注 |
|---|---|---|
| PostgreSQL | 16 | 兼容 AWS RDS |
| Redis | 7 | 兼容 AWS ElastiCache |
| NATS Server | Latest stable | 必须启用 JetStream(--jetstream) |
| Go | 1.21+ | 仅用于构建 |
| Docker | 20.10+ | 必须使用 Compose V2 |
商业模式
| 套餐 | 价格 | WABA 数量 | 消息数量 | 功能 |
|---|---|---|---|---|
| OSS | 免费 | 1 | 200/天 | 合规引擎、基础消息功能、只读智能分析 |
| Pro | $149/mo | 最多 5 个 | 无限 | 完整 MCP 工具套件、活动管理、计划安排、仪表板 |
| Enterprise | $499/mo | 无限 | 无限 | 专用基础设施、SSO、自定义策略、SLA |
活动操作(schedule_campaign、cancel_campaign、pause_campaign)仅 Pro 套餐可用。
采用 Apache 2.0 许可证。
路线图
| 阶段 | 里程碑 | 状态 |
|---|---|---|
| Phase 1 | v1.0 — 核心平台(4 个工具) | ✅ 已完成 |
| Phase 2 | Sprint 2 — MCP 工具完善(4→24 个工具) | ✅ 已完成 |
| Phase 3 | 工具重命名 + PRD 更新 | ✅ 已完成 |
| Phase 4 | 运营仪表板(Next.js + go:embed) | ✅ 已完成 |
| Phase 5 | 托管云 MVP(Railway、Stripe 计费) | 接下来(第 3-6 周) |
| Phase 6 | 设计合作伙伴验证(3-5 家机构参与 Beta 测试) | 第 5-10 周 |
| Phase 7 | 商业发布($149 Pro / $499 Enterprise) | 第 9-12 周 |
| Phase 8 | 扩展(15-20 位付费客户) | 第 4-6 个月 |
Messenger 和 Instagram 不在当前范围内,除非获得资金支持。暂无针对这些渠道的路线图承诺。
完整路线图详情:PRD_MetaBusinessMCP.md §27
可观测性
HTTP 端点
| 端点 | 方法 | 响应 |
|---|---|---|
/health | GET | 200 OK — 正文:"OK" |
/metrics | GET | 200 OK — Prometheus 抓取负载 |
/webhook | GET | 200 OK — 回显 webhook challenge |
/webhook | POST | 200 OK — 正文:"EVENT_RECEIVED" |
健康检查
curl http://localhost:8080/health
Prometheus 指标
curl http://localhost:8080/metrics
自定义指标在 pkg/observability/ 中注册。默认 Prometheus 注册表会自动包含标准 Go 运行时和进程指标。
日志记录
结构化日志写入 stdout/stderr。通过 Docker 收集:
docker compose logs -f app
NATS 监控
NATS 监控 HTTP 接口可通过 :8222 访问。流和消费者统计信息:http://localhost:8222/jsz。
文档索引
| 文档 | 描述 |
|---|---|
| docs/architecture.md | 组件布局、数据库架构(ER)、NATS 流拓扑、Redis 缓存策略 |
| docs/api_reference.md | HTTP 端点规范 + 全部 24 个 MCP 工具规范及请求/响应示例 |
| docs/deployment_guide.md | 生产环境部署分步指南、Docker Compose 模板、迁移 |
| docs/developer_guide.md | 如何添加策略、注册新的 MCP 工具、扩展 NATS 队列工作进程 |
| docs/env_variables.md | 完整的环境变量参考表 |
| docs/limitations.md | 已知的平台限制和未来路线图 |
| docs/mcp-tools-test-report.md | 全部 24 个 MCP 工具的集成测试报告 |
| walkthrough-1.md | MVP 实现总结 |
| walkthrough-2.md | 阶段 6:加固与文档编写——测试、基准测试、文档冲刺 |
| walkthrough-3.md | WABA 生产环境验证、回归修复、边界规范化 |
| walkthrough-4.md | 冲刺 2:完成 MCP 工具(4→24 个)——架构决策、测试覆盖率 |
| PRD_MetaBusinessMCP.md | 产品需求文档 v3.2 |
贡献
本项目使用 Go 1.21+、PostgreSQL 16、Redis 7 和 NATS JetStream。
- Fork 此仓库。
- 创建功能分支:
git checkout -b feature/my-change - 提交前运行测试:
go test -count=1 -p 1 ./... - 提交 pull request,并清晰描述所做的更改。
有关扩展策略、添加 MCP 工具以及使用队列工作进程架构的信息,请参阅 docs/developer_guide.md。
许可证
Apache License 2.0
版权所有 2026 Adam Zibran
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。