内容
# Meta Business MCP
`Go 1.21+` `License: Apache 2.0` `Tests: Passing` `Coverage: 85.6%` `Tools: 24` `Production-Validated`
> 一个确保每个 AI 代理都能安全、合规、准备好生产地运行 WhatsApp Business 的合规智能平台，无需了解 Meta 的规则复杂性。
**适用于：** AI 代理开发者 · 数字机构 · WhatsApp 自动化团队
**21 个免费工具 · 3 个专业版工具**
---
## 目录
1. [为什么存在](#为什么存在)
2. [功能](#功能)
3. [快速开始](#快速开始)
4. [MCP 工具](#mCP-工具)
5. [架构](#架构)
6. [配置](#配置)
7. [测试](#测试)
8. [部署](#部署)
9. [商业模式](#商业模式)
10. [路线图](#路线图)
11. [可观察性](#可观察性)
12. [文档索引](#文档索引)
13. [贡献](#贡献)
14. [许可证](#许可证)
---
## 为什么存在
AI 代理不了解 Meta 的 WhatsApp Business 规则 — 24 小时服务窗口、频率限制、模板类别、退出强制措施、速率限制。发送错误的消息意味着账户暂停、消息拒绝和合规违规。Meta Business MCP 位于 AI 代理和 Meta 的 API 之间，自动强制执行所有规则，以便代理无需了解这些规则。
---
## 功能
| 责任 | 描述 |
|---|---|
| **合规门控** | 在发送前评估每条 outbound 消息是否符合 Meta 的服务窗口规则、退出列表和频率限制。 |
| **策略强制执行** | 从 YAML 加载数据库中应用自定义业务策略（时间边界、细分排除、VIP 标签覆盖）。 |
| **异步消息传递** | 将消息排队到 NATS JetStream 并通过具有自动重试和指数退避的工作线程池分派。 |
| **速率限制** | 通过 Redis Lua 脚本强制执行每个客户的令牌桶速率限制。 |
| **错误智能** | 将数字 Meta API 错误代码转换为分类的、可操作的开发者指令。 |
| **活动管理** | 调度、暂停、取消活动，并具有受众细分和模板验证功能。 |
| **模板生命周期** | 通过 Meta API 创建、同步和验证模板，具有本地持久性。 |
| **MCP 服务器** | 通过 stdio 向 AI 代理公开 24 个结构化工具，使用模型上下文协议。 |
| **Webhook 接收器** | 处理来自 Meta 的入站事件：客户消息、交付状态更新和模板批准回调。 |
---
## 快速开始
### 1. 克隆和启动
```bash
git clone https://github.com/metabusiness-mcp/meta-business-mcp.git
cd meta-business-mcp
docker compose up -d --build
```
等待所有容器变为健康状态：
```bash
docker compose ps
# 所有容器都应显示 "healthy"
```
### 2. 访问仪表盘
打开浏览器：**http://localhost:8080**
首次运行时，服务器会自动生成一个随机密码并将其打印到终端：
```
╔══════════════════════════════════════════════════════════╗
║ 仪表盘凭证（自动生成） ║
╠══════════════════════════════════════════════════════════╣
║ 用户名： admin ║
║ 密码： a1b2c3d4e5f6g7h8 ║
╚══════════════════════════════════════════════════════════╝
```
复制密码并登录。
### 3. 连接您的 AI 代理
MCP 服务器在 stdio 上运行。配置您的 AI 客户端（Claude Desktop、Cursor 等）：
```json
{
"mcpServers": {
"meta-business-mcp": {
"command": "/path/to/meta-business-mcp",
"args": []
}
}
}
```
### 4. 验证
```bash
curl http://localhost:8080/health
# OK
```
**启动内容：** PostgreSQL 16 (`:5432`)，Redis 7 (`:6379`)，NATS JetStream (`:4222`)，模拟 Meta API (`:8081`)，Meta Business MCP (`:8080` + MCP stdio)。默认使用模拟凭证 — 本地开发不需要 Meta API 密钥。
---
## MCP 工具
所有 24 个工具都通过 stdio 使用模型上下文协议暴露给 AI 代理。所有工具都是准备好生产的，并针对真实的 WABA 生产环境（Meta Graph API v20.0）进行了验证。
### 操作操作
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
| `check_compliance()` | 评估计划中的 outbound 消息是否符合 Meta 规则和本地策略 | [所有] | ✅ |
| `send_message()` | 发送自由格式的服务文本消息（需要活跃的 24 小时服务窗口） | [所有] | ✅ |
| `send_template()` | 发送批准的模板消息（绕过 24 小时服务窗口） | [所有] | ✅ |
| `explain_error()` | 将 Meta API 错误代码转换为分类的、可操作的解释 | [所有] | ✅ |
| `reply_customer()` | 在活跃的对话上下文中回复（需要开放的 24 小时窗口） | [所有] | ✅ |
| `retry_failed_messages()` | 触发一个或多个失败消息的手动重试，并进行重试验证 | [所有] | ✅ |
| `sync_template_status()` | 从 Meta API 同步模板批准状态并更新本地数据库 | [所有] | ✅ |
### 只读智能
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
| `check_conversation()` | 查询对话窗口状态、剩余时间、类型和资格 | [所有] | ✅ |
| `check_frequency_cap()` | 检查客户是否处于 Meta 的营销消息频率上限之下 | [所有] | ✅ |
| `get_customer_context()` | 检索完整的客户资料：选择加入/退出、标签、参与度评分、资格 | [所有] | ✅ |
| `get_delivery_status()` | 查询消息传递状态（已发送/已交付/已读/失败）并具有错误智能 | [所有] | ✅ |
| `get_rate_limit()` | 查询当前 MPS 容量、已消耗的令牌和剩余的令牌 | [所有] | ✅ |
| `list_conversations()` | 列出对话，并带有筛选器：开放、关闭、即将过期 | [所有] | ✅ |
| `list_templates()` | 列出模板，并带有状态/类别/本地筛选器从 Meta API | [所有] | ✅ |
### 调度和活动
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
| `schedule_message()` | 调度单个消息以备将来投递，并进行合规预检查 | [所有] | ✅ |
| `schedule_campaign()` | 调度广播活动，并带有批准的模板和受众筛选器 | [专业版] | ✅ |
| `cancel_campaign()` | 取消非终端状态的活动（已调度和运行/暂停） | [专业版] | ✅ |
| `pause_campaign()` | 暂停活跃的活动，保留进度计数器以备恢复 | [专业版] | ✅ |
### 账户和成本智能
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
| `get_account_quality()` | 从 Meta 检索 WABA 质量分数和消息限制层级 | [所有] | ✅ |
| `estimate_cost()` | 估算计划消息批次的对话成本 | [所有] | ✅ |
| `estimate_pricing()` | 查询当前对话定价层级，适用于国家/类型组合 | [所有] | ✅ |
### 操作
| 工具 | 描述 | 层级 | 状态 |
|---|---|---|---|
| `create_template()` | 向 Meta 提交新模板以批准，本地持久化为 PENDING | [所有] | ✅ |
| `sync_webhooks()` | 触发模板状态和待处理 webhook 事件的手动重新同步 | [所有] | ✅ |
| `archive_chat()` | 在终端状态（过期窗口）存档对话 | [所有] | ✅ |
完整的参数规范和响应示例：[docs/api_reference.md](docs/api_reference.md)
---
## 架构
### 双模式二进制
该平台编译为单个 Go 二进制文件，同时运行两个服务器：
| 模式 | 传输 | 目的 |
|---|---|---|
| **MCP 服务器** | stdio（stdin/stdout） | 向 AI 客户端公开 24 个结构化工具（Gemini、Claude、Cursor） |
| **HTTP 服务器** | TCP :8080 | Webhook 接收器、健康检查、Prometheus 指标 |
### 高级组件图
```
┌───────────────────────────────┐
│ AI 代理 │
└──────────────┬────────────────┘
│ stdio（MCP 协议）
▼
┌────────────────────────────────────────────────────────┐
│ Meta Business MCP │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ MCP 服务器 ├───────►│ 合规引擎 │ │
│ └───────────────────┘ └─────────┬─────────┘ │
│ ▼ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ Webhook 接收器 │ │ 策略引擎 │ │
│ └─────────▲─────────┘ └─────────┬─────────┘ │
│ │ ▼ │
│ │ ┌───────────────────┐ │
│ │ │ 调度器 │ │
│ │ └─────────┬─────────┘ │
└─────────────┼────────────────────────────┼─────────────┘
│ Webhook │ POST /messages
│ ▼
┌─────────────┴────────────────────────────┴─────────────┐
│ Meta Cloud API（或模拟 :8081） │
└────────────────────────────────────────────────────────┘
```
### 核心服务
| 服务 | 包 | 角色 |
|---|---|---|
| **MCP 服务器** | `pkg/mcp/` | 注册并处理来自 AI 代理的 24 个 MCP 工具调用。分为 6 个处理文件（~2000 行）。 |
| **合规引擎** | `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 脚本；优雅的 PostgreSQL 回落。 |
| **消息代理** | NATS JetStream | 异步投递队列，具有 WorkQueue 保留和拉取消费者。 |
### 数据库模式（ER 图）
```mermaid
erDiagram
customers ||--o{ conversations : has
conversations ||--o{ messages : contains
templates ||--o{ messages : sent_as
messages }|--o{ message_frequencies : logs
customers {
varchar id PK "电话号码"
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 消息 ID 或 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` (durable pull) | 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](docs/architecture.md)
---
## 配置
### 配置文件（`config.yaml`）
在本地开发时，将 `config.yaml` 放在项目根目录：
```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" # 使用模拟服务器进行离线开发
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"` | — | 调度器轮询间隔，适用于定时消息/活动 |
完整的环境变量参考：[docs/env_variables.md](docs/env_variables.md)
---
## 测试
### 运行所有测试
```bash
go test -count=1 -p 1 -cover ./...
```
### 运行合规基准测试
```bash
go test -bench=BenchmarkCheckCompliance -benchtime=5s ./pkg/compliance/
```
### 软件包覆盖率（冲刺 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, phone normalization） | ✅ |
| 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, campaign tier-gating ×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（due message, future message, compliance failure, duplicate dispatch, campaign trigger） | ✅ |
| 集成测试 | `tests/integration_test.go` | 7 | ✅ |
| 端到端测试 | `tests/e2e_test.go` | 3 | ✅ |
| 故障模拟 | `tests/failure_test.go` | 4（Redis outage, NATS outage, Meta 500, Meta 131049） | ✅ |
### 基准测试结果
| 工具 | 延迟 | 与目标相比 |
|---|---|---|
| `check_compliance()` | **1.69 ms** | ~30× faster than 50ms target |
---
## 部署
### 编译二进制文件
```bash
go build -o mcp-server ./cmd/server/main.go
```
### 生产环境（`.env`）
```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
```yaml
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:
```
```bash
docker compose -f docker-compose.prod.yaml up -d --build
```
### 数据库迁移和种子
无需外部迁移运行器。应用程序启动时会自动：
1. 创建所有数据库表（`customers`, `conversations`, `messages`, `templates`, `policies`, `campaigns`, `message_frequencies`, `error_knowledge_base`, `audit_logs`, `conversation_pricing`）。
2. 将标准 Meta 错误代码种子到 `error_knowledge_base`。
3. 使用幂等 `ON CONFLICT DO UPDATE` 从 `policies.yaml` 种子业务策略。
4. 为 ID、US、IN、BR、GB 和 DEFAULT fallback 种子对话定价数据。
所有模式更改都使用 `IF NOT EXISTS` / `ADD COLUMN IF NOT EXISTS`。现有部署通过重启应用程序进行升级。
### Webhook 注册
在 Meta 应用开发者门户中注册公共 URL：
- **验证**：`GET /webhook` — 响应 `hub.challenge`。
- **事件**：`POST /webhook` — 接收传入消息、状态更新和模板事件。
- **签名验证**：所有 POST 事件都验证 `X-Hub-Signature-256` 头。
### 基础设施依赖
| 依赖 | 最低版本 | 备注 |
|---|---|---|
| PostgreSQL | 16 | 与 AWS RDS 兼容 |
| Redis | 7 | 与 AWS ElastiCache 兼容 |
| NATS 服务器 | 最新稳定版 | 必须启用 JetStream (`--jetstream`) |
| Go | 1.21+ | 仅限构建 |
| Docker | 20.10+ | 需要 Compose V2 |
---
## 商业模式
| 层级 | 价格 | WABAs | 消息 | 功能 |
|---|---|---|---|---|
| **OSS** | 免费 | 1 | 200/天 | 合规引擎、基本消息传递、只读情报 |
| **Pro** | $149/月 | 最多 5 | 无限 | 全套 MCP 工具、活动管理、调度、仪表盘 |
| **企业** | $499/月 | 无限 | 无限 | 专用基础设施、SSO、自定义策略、SLA |
活动操作（`schedule_campaign`, `cancel_campaign`, `pause_campaign`）在 Pro 层级后面。
根据 Apache 2.0 许可。
---
## 路线图
| 阶段 | 里程碑 | 状态 |
|---|---|---|
| 阶段 1 | v1.0 — 核心平台（4 个工具） | ✅ 已完成 |
| 阶段 2 | 短跑 2 — MCP 工具完成（4→24 个工具） | ✅ 已完成 |
| 阶段 3 | 工具重命名 + PRD 更新 | ✅ 已完成 |
| 阶段 4 | 操作仪表盘（Next.js + go:embed） | ✅ 已完成 |
| 阶段 5 | 管理云 MVP（Railway，Stripe 计费） | 下一步（第 3-6 周） |
| 阶段 6 | 设计合作伙伴验证（3-5 个机构测试） | 第 5-10 周 |
| 阶段 7 | 商业启动（$149 Pro / $499 企业） | 第 9-12 周 |
| 阶段 8 | 扩展（15-20 个付费客户） | 第 4-6 个月 |
Messenger 和 Instagram 在获得资金支持之前不在考虑范围内。对这些渠道没有路线图承诺。
完整路线图详情：[PRD_MetaBusinessMCP.md §27](PRD_MetaBusinessMCP.md)
---
## 可观察性
### HTTP 端点
| 端点 | 方法 | 响应 |
|---|---|---|
| `/health` | `GET` | `200 OK` — 正文：`"OK"` |
| `/metrics` | `GET` | `200 OK` — Prometheus 抓取有效载荷 |
| `/webhook` | `GET` | `200 OK` — Webhook 挑战回声 |
| `/webhook` | `POST` | `200 OK` — 正文：`"EVENT_RECEIVED"` |
### 健康检查
```bash
curl http://localhost:8080/health
```
### Prometheus 指标
```bash
curl http://localhost:8080/metrics
```
自定义指标在 `pkg/observability/` 中注册。默认 Prometheus 注册表中自动包含标准 Go 运行时和进程指标。
### 日志记录
结构化日志写入 stdout/stderr。 通过 Docker 收集：
```bash
docker compose logs -f app
```
### NATS 监控
NATS 监控 HTTP 接口在 `:8222` 处可用。 流和消费者统计：`http://localhost:8222/jsz`。
---
## 文档索引
| 文档 | 描述 |
|---|---|
| [docs/architecture.md](docs/architecture.md) | 组件布局、DB 模式 (ER)、NATS 流拓扑、Redis 缓存策略 |
| [docs/api_reference.md](docs/api_reference.md) | HTTP 端点规范 + 所有 24 个 MCP 工具规范，附请求/响应示例 |
| [docs/deployment_guide.md](docs/deployment_guide.md) | 分步生产部署、Docker Compose 模板、迁移 |
| [docs/developer_guide.md](docs/developer_guide.md) | 如何添加策略、注册新的 MCP 工具、扩展 NATS 队列工作器 |
| [docs/env_variables.md](docs/env_variables.md) | 完整环境变量参考表 |
| [docs/limitations.md](docs/limitations.md) | 已知平台限制和未来路线图 |
| [docs/mcp-tools-test-report.md](docs/mcp-tools-test-report.md) | 所有 24 个 MCP 工具的集成测试报告 |
| [walkthrough-1.md](walkthrough-1.md) | MVP 实现总结 |
| [walkthrough-2.md](walkthrough-2.md) | 阶段 6：强化和文档 — 测试、基准测试、文档冲刺 |
| [walkthrough-3.md](walkthrough-3.md) | WABA 生产验证、回归修复、边界归一化 |
| [walkthrough-4.md](walkthrough-4.md) | 短跑 2：MCP 工具完成（4→24 个工具）— 架构决策、测试覆盖 |
| [PRD_MetaBusinessMCP.md](PRD_MetaBusinessMCP.md) | 产品需求文档 v3.2 |
---
## 贡献
该项目使用 Go 1.21+、PostgreSQL 16、Redis 7 和 NATS JetStream。
1. 复刻仓库。
2. 创建一个功能分支：`git checkout -b feature/my-change`
3. 提交前运行测试：`go test -count=1 -p 1 ./...`
4. 提交一个包含更改的清晰描述的拉取请求。
参见 [docs/developer_guide.md](docs/developer_guide.md) 以扩展策略、添加 MCP 工具和处理队列工作器架构。
---
## 许可证
Apache 许可证 2.0
版权 2026 Adam Zibran
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器