📚 MCP Advbox Server 文件

版本： 2.2.0（硬化）\ 上次更新： 2026年5月，里约热内卢\ 作者： 乔纳斯·索萨

______________________________________________________________________

📑 索引

概览
建筑
安装
配置
认证
端点HTTP
可用工具
使用范例
安全
与N8N集成
监测
故障排除

______________________________________________________________________

1. 概述

什么是MCP Advbox？

哦 MCP Advbox服务器 是实现协议的服务器 模型上下文协议（MCP） 与法律管理系统Advbox API集成。它允许人工智能代理（如Claude）直接与客户数据、流程、任务和办公室财务交易进行交互。

主要功能

✅ 19工具 用于完整的 CRUD 操作
✅ 安全认证 通过承载令牌
✅ 速率限制 防止滥用
✅ SSE（服务器发送事件） 用于实时通信
✅ 输入验证 在所有参数中
✅ 安全头 （HSTS、CSP、X-Frame-Options）

使用案例

用例	描述
查询客户	按姓名、电话、电子邮件搜索客户信息
过程管理	创建、更新和咨询法律过程
财务控制	列出交易、收入和支出
约会日历	创建和列出任务和约会
团队报告	查看团队得分和奖励

______________________________________________________________________

2. 建筑

图片

┌─────────────────┐     HTTPS/SSE      ┌──────────────────┐     HTTPS      ┌─────────────────┐
│   Claude / n8n  │ ◄────────────────► │  MCP Advbox API  │ ◄────────────► │   Advbox API    │
│                 │    Bearer Token    │   (Port 3847)    │   API Token    │   (v1)          │
└─────────────────┘                    └──────────────────┘                └─────────────────┘

堆栈技术

组件	技术
运行时	Node.js 20 Alpine
语言	TypeScript
Protocolo	MCP（模型上下文协议）
传输	HTTP + SSE
容器	Docker
代理	Traefik
TLS	让我们加密

文件结构

/opt/stacks/advbox-mcp-server/
├── src/
│   └── http-server.ts      # Código principal
├── dist/
│   └── http-server.js      # Código compilado
├── docs/
│   └── README.md           # Esta documentação
├── docker-compose.yml
├── Dockerfile.http
├── package.json
├── tsconfig.json
└── .env

______________________________________________________________________

3. 安装

先决条件

Docker 24.0+
Docker Compose v2
说话 Docker proxy 已配置
Traefik com让我们加密

一步一步

# 1. Criar estrutura
mkdir -p /opt/stacks/advbox-mcp-server/src
cd /opt/stacks/advbox-mcp-server

# 2. Criar .env
cat > .env

例子

curl -H "Authorization: Bearer " https:///tools

错误

状态	答案	原因
401	`{"error":"Unauthorized"}`	无效令牌
429	`{"error":"Too Many Requests"}`	费率限制

______________________________________________________________________

6.端点HTTP

方法	Endpoint	Auth	描述
得到	`/health`	❌	健康检查
得到	`/sse`	✅	SSE 连接（MCP）
职位	`/message`	✅	MCP消息
得到	`/tools`	✅	Listar工具
职位	`/execute`	✅	执行工具

GET/健康

curl https:///health

{"status":"healthy","version":"2.2.0","tools":19,"sse":0}

POST/执行

curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_customers","arguments":{"limit":5}}' \
  https:///execute

______________________________________________________________________

7. 可用工具

简历（19工具）

类别	工具	数量
客户	列表、获取、搜索、创建	4
诉讼	列表、获取、搜索、创建、更新	5
交易	列表，获取	2
任务	列表，创建	2
设置	get_Settings、get_users、get_rigins、get_stages、get_type_lawsuits	5
奖励	用户_奖励	1

7.1客户（顾客）

列表_客户

列出并使用过滤器搜索客户。

参数	类型	强制性	描述
`name` string 。❌	客户名（部分搜索）
`phone`	string	❌	Telefone
`email`	string	❌	电子邮件
`city` string 。❌	城市
`limit`	数字	❌	最大结果（默认值：100，最大值：500）
`offset` 号码	❌	跳过结果（分页）

例如：

{"tool":"list_customers","arguments":{"name":"Silva","limit":10}}

get_客户

通过 ID 获取客户的详细信息。

参数	类型	强制性	描述
`customer_id` 号码	✅	客户ID。

例如：

{"tool":"get_customer","arguments":{"customer_id":12345}}

搜索_客户

按名字查找客户

参数	类型	强制性	描述
`query`	字符串	✅\*	搜索保温瓶
`name` string 。✅\*	替代 query。

创建_客户

创建一个新客户。

参数	类型	强制性	描述
`users_id` 号码	✅	创建用户 ID
`customers_origins_id` 号码	✅	客户来源 ID。
`name` string 。✅	客户名
`email`	string	❌	电子邮件
`document`	string	❌	CPF/CNPJ
`identification`	string	❌	RG
`phone`	string	❌	Telefone
`birthdate`	string	❌	数据来源（YYYY-MM-DD）

例如：

{
  "tool": "create_customer",
  "arguments": {
    "users_id": 1,
    "customers_origins_id": 2,
    "name": "João da Silva",
    "email": "joao@email.com",
    "phone": "85999999999"
  }
}

______________________________________________________________________

7.2诉讼（过程）

list_lawsuits

列出带过滤器的进程。

参数	类型	强制性	描述
`name` string 。❌	文件夹/客户端名称
`process_number` string 。❌	过程编号。
`customer_id` 号码	❌	客户ID。
`responsible_id` 号码	❌	负责人的ID
`group_id` 号码	❌	组/区域 ID
`limit`	数字	❌	最大结果
`offset` 号码	❌	跳过结果

get_lawsuit

获取一个过程的详细信息。

参数	类型	强制性	描述
`lawsuit_id`	编号	✅	ID执行进程

搜索服

按名称/文件夹搜索进程。

参数	类型	强制性	描述
`query`	字符串	✅\*	搜索保温瓶
`name`	string	✅\*	备选方案a

create_lawsuit

创建新进程。

参数	类型	强制性	描述
`users_id` 号码	✅	创建用户 ID
`customers_id`	数组\[数字\]	✅	客户端ID
`stages_id` 号码	✅	阶段ID。
`type_lawsuits_id` 号码	✅	进程类型 ID 。
`process_number` string 。❌	过程编号。
`protocol_number` string 。❌	协议编号
`folder` string 。❌	文件夹名称。
`date`	string	❌	数据（YYYY-MM-DD）
`notes` string 。❌	评论

例如：

{
  "tool": "create_lawsuit",
  "arguments": {
    "users_id": 1,
    "customers_id": [123, 456],
    "stages_id": 5,
    "type_lawsuits_id": 10,
    "folder": "Silva vs Estado",
    "process_number": "0001234-56.2026.8.06.0001"
  }
}

update_lawsuit

更新已有进程。

参数	类型	强制性	描述
`lawsuit_id`	编号	✅	ID执行进程
`stages_id` 号码	❌	新阶段。
`type_lawsuits_id`	编号	❌	新提示
`process_number` string 。❌	过程编号。
`folder` string 。❌	文件夹名称。
`notes` string 。❌	评论

______________________________________________________________________

7.3 交易（Transactions）

list_交易

金融交易列表。

参数	类型	强制性	描述
`date_payment_start` string 。❌	开始付款日期（YYY-MM-DD）
`date_payment_end` string 。❌	结束付款日期
`date_due_start` string 。❌	到期日期开始。
`date_due_end` string 。❌	到期日期结束。
`lawsuit_id` 号码	❌	按过程过滤
`limit`	数字	❌	最大结果
`offset` 号码	❌	跳过结果

例如：

{
  "tool": "list_transactions",
  "arguments": {
    "date_payment_start": "2026-01-01",
    "date_payment_end": "2026-01-31"
  }
}

get_transaction

获取交易的详细信息。

参数	类型	强制性	描述
`transaction_id` 号码	✅	交易ID。

______________________________________________________________________

7.4任务（Tarefas）

list_tasks

列出任务和承诺。

参数	类型	强制性	描述
`date_start` string 。❌	开始日期（YYY-MM-DD）
`date_end`	string	❌	数据fim
`user_id` 号码	❌	按用户过滤
`lawsuit_id` 号码	❌	按过程过滤
`task_id` 号码	❌	按任务类型过滤
`limit`	数字	❌	最大结果
`offset` 号码	❌	跳过结果

创建任务

创建一个新任务/待办事宜。

参数	类型	强制性	描述
`from` 号码	✅	创建用户 ID
`guests`	数组\[数字\]	✅	身份证号码
`tasks_id` 号码	✅	任务类型 ID 。
`lawsuits_id`	编号	✅	ID执行进程
`start_date` string 。✅	开始日期（YYY-MM-DD）
`start_time` string 。❌	开始时间（HH:MM）
`end_date`	string	❌	数据fim
`end_time` string 。❌	结束时间
`date_deadline`	string	❌	普拉佐
`comments` string 。❌	评论
`local`	string	❌	本地
`urgent`	布尔	❌	紧急的
`important`	布尔值	❌	重要事项

例如：

{
  "tool": "create_task",
  "arguments": {
    "from": 1,
    "guests": [2, 3],
    "tasks_id": 5,
    "lawsuits_id": 100,
    "start_date": "2026-01-10",
    "start_time": "14:00",
    "comments": "Reunião com cliente",
    "urgent": true
  }
}

______________________________________________________________________

7.5 设置（Settings）

获取设置

获取所有系统配置（用户，阶段，类型，起源）。

用户名

用户/贡献者列表

get_origins

列出客户来源。用于获取 customers_origins_id.

获取_页面

列出过程阶段。用于获取 stages_id.

get_type_lawsuits

列出过程类型。用于获取 type_lawsuits_id.

______________________________________________________________________

7.6奖励（奖励）

获取用户奖励

获得团队的分数和奖励。

参数	类型	强制性	描述
`date`	string	❌	数据限制（YYYY-MM-DD）

例如：

{"tool":"get_users_rewards","arguments":{"date":"2026-01-05"}}

______________________________________________________________________

8. 使用范例

8.1 全MCP流（SSE）

// 1. Conectar ao SSE
const eventSource = new EventSource('https:///sse', {
  headers: { 'Authorization': 'Bearer ' }
});

let messageEndpoint = '';

// 2. Receber endpoint para mensagens
eventSource.addEventListener('endpoint', (e) => {
  messageEndpoint = e.data;
  console.log('Endpoint:', messageEndpoint);
});

// 3. Receber respostas
eventSource.addEventListener('message', (e) => {
  const response = JSON.parse(e.data);
  console.log('Response:', response);
});

// 4. Enviar requisição MCP
fetch(messageEndpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer '
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'list_customers',
      arguments: { limit: 5 }
    }
  })
});

8.2 直接执行（REST）

# Listar clientes
curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_customers","arguments":{"name":"Silva","limit":10}}' \
  https:///execute

# Buscar processo
curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_lawsuit","arguments":{"lawsuit_id":12345}}' \
  https:///execute

# Criar tarefa
curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_task",
    "arguments": {
      "from": 1,
      "guests": [1],
      "tasks_id": 5,
      "lawsuits_id": 100,
      "start_date": "2026-01-10",
      "comments": "Audiência"
    }
  }' \
  https:///execute

8.3 页面

# Página 1 (primeiros 100)
curl -X POST -H "Authorization: Bearer " \
  -d '{"tool":"list_customers","arguments":{"limit":100,"offset":0}}' \
  https:///execute

# Página 2 (próximos 100)
curl -X POST -H "Authorization: Bearer " \
  -d '{"tool":"list_customers","arguments":{"limit":100,"offset":100}}' \
  https:///execute

______________________________________________________________________

9. 安全

9.1实施的控制

控制	描述	CWE 减轻
定时安全认证	抵御定时攻击的代币比较	CWE-208
速率限制	每IP 100 req/min	CWE-770
输入验证	所有参数的卫生	CWE-20
车身尺寸限制	最大1MB	CWE-400
SSE限额	最多100个连接，每IP5个	CWE-770
原型污染过滤器。 `__proto__`, `constructor`	CWE-1321
路径遍历	正则表达式验证端点	CWE-22
安全标头	HSTS、CSP、X-Frame-Options	Múltiplos

9.2 安全标题

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'none'
Strict-Transport-Security: max-age=31536000; includeSubDomains

9.3科尔

允许的域名（可通过配置） ALLOWED_ORIGINS):

https://
https://

9.4集装箱安全

✅ 以非 root 用户身份运行（advbox:1001)
✅ 最小阿尔卑斯山图像
✅ 半根壳
✅ 资源有限（512MB RAM，1 CPU）

9.5 良好实践

旋转或MCP_TOKEN 每90天
监视器 认证尝试失败
保持已更新的容器
使用HTTPS 总是（通过Traefik）

______________________________________________________________________

10. 与n8n集成

10.1 MCP 客户端设置

在 n8n 上配置节点 MCP客户端 通用域名格式：

价值
统一资源定位符	`https:///sse`
认证	标头身份验证
标题名称	`Authorization`
标头值	`Bearer`

10.2 自动化中最常用的工具

自动化	工具
寻找客户	`search_customers`, `get_customer`
创建过程	`get_settings`, `create_lawsuit`
财务报告	`list_transactions`
议程	`list_tasks`, `create_task`
游戏化	`get_users_rewards`

______________________________________________________________________

11. 监测

11.1健康检查

curl https:///health
# {"status":"healthy","version":"2.2.0","tools":19,"sse":0}

11.2日志做容器

# Ver logs em tempo real
docker logs -f advbox-mcp-api

# Últimas 100 linhas
docker logs --tail 100 advbox-mcp-api

11.3 监测指标

指标	描述	警报
`sse`	活动的 SSE 连接	> 80
健康状态	服务器状态		healthy
Response time	响应时间	> 5s
错误率 5xx	> 1%

11.4 Uptime Kuma 集成

Type: HTTP(s)
URL: https:///health
Method: GET
Expected Status: 200
Interval: 60 seconds
Retries: 3

______________________________________________________________________

12.故障排除

12.1 常见错误

401未经授权

原因： 令牌不存在或无效

解决方案：

# Verificar token
cat /opt/stacks/advbox-mcp-server/.env | grep MCP_TOKEN

# Testar com curl
curl -H "Authorization: Bearer " https:///tools

429请求太多

原因： 超过速率限制（100 req/min）

解决方案： 等待 60 秒或优化请求

503连接太多

原因： 已达到 SSE 连接限制（100）

解决方案：

docker restart advbox-mcp-api

连接被拒绝

原因： 容器未运行

解决方案：

docker ps | grep advbox
docker logs advbox-mcp-api
docker compose up -d advbox-api

API错误401（Advbox）

原因： 无效的 Advbox 令牌

解决方案：

cat /opt/stacks/advbox-mcp-server/.env | grep ADVBOX_API_TOKEN
curl -H "Authorization: Bearer " https://app.advbox.com.br/api/v1/settings

12.2诊断命令

# Status do container
docker inspect advbox-mcp-api | jq '.[0].State'

# Uso de recursos
docker stats advbox-mcp-api --no-stream

# Verificar rede
docker exec advbox-mcp-api wget -qO- http://localhost:3000/health

# Rebuild completo
cd /opt/stacks/advbox-mcp-server
docker compose down
docker compose build --no-cache
docker compose up -d

______________________________________________________________________

13.变更日志

v2.2.0（2026年1月5日）-硬化

安全：

✅ 定时安全令牌比较
✅ 原型污染防护
✅ 限速保护记忆耗竭
✅ SSE 连接限制（全局和 IP）
✅ SSE 连接超时（1 小时）
✅ 带白名单的限制性CORS
✅ 电子邮件验证
✅ 安全标头（HSTS）

v2.1.0（2026年1月5日）

✅ Bearer Token 认证
✅ 限速básico
✅ 输入验证

v2.0.0（2026年1月4日）

✅ Servidor HTTP独立版
✅ 19 功能工具
✅ SSE 支持

v1.0.0（2026年1月3日）

初始版本（STDIO）

______________________________________________________________________

14. 快速参考

生产证书

项目	阀门
端点SSE	`https:///sse`
端点执行	`https:///execute`
MCP令牌	``
本地端口	`3847`

快速测试命令

# Testar autenticação
curl -s -H "Authorization: Bearer " \
  https:///health

# Listar tools
curl -s -H "Authorization: Bearer " \
  https:///tools | jq '.tools[].name'

______________________________________________________________________

*2026年1月5日创建的文档 - Jonas Sousa*

______________________________________________________________________

15. 与 Claude Desktop 集成

15.1先决条件

Node.js 已安装（版本18+）
克劳德桌面版 instalado

检查 Node.js 是否已安装：

node --version
npx --version

如果没有，请下载：https://nodejs.org/

15.2 配置文件的位置

系统	路径
视窗	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

15.3 配置

编辑文件 claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "advbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https:///sse",
        "--transport",
        "sse-only",
        "--header",
        "Authorization:Bearer "
      ]
    }
  }
}

注：如果文件中已经有内容，请仅添加部分 mcpServers 保持其他配置。

现有配置示例：

{
  "preferences": {
    "chromeExtensionEnabled": true
  },
  "mcpServers": {
    "advbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https:///sse",
        "--transport",
        "sse-only",
        "--header",
        "Authorization:Bearer "
      ]
    }
  }
}

15.4 参数解释

参数	描述
`npx` Node.js 软件包执行器
`-y`	自动接受软件包安装
`mcp-remote` STDIO 与远程 SSE 之间的桥梁
`https:///sse` MCP Advbox 服务器的 URL
`--transport sse-only` 通过SSE强制连接（必填）
`--header`	验证头
`Authorization:Bearer ...` 验证令牌（“：”）后没有空格。

15.5 激活

你好文件 claude_desktop_config.json
完全关闭 Claude Desktop（包括系统托盘）
打开 Claude 桌面
检查图标是否出现 工具/MCP na接口

15.6 验证

重新启动后，使用以下命令之一进行测试：

“列出可用的Advbox工具”
“在Advbox中查找Silva客户”
“办公室的用户是谁？”

15.7克劳德桌面故障排除

检查日志

没有克劳德桌面，acesse： View → 切换开发者工具→ 控制台

常见错误

错误	原因	解决方案
`command is required`	JSON 格式错误	使用 com 格式 `command` e `args`
`transport strategy: http-first`	缺少 `--transport sse-only` 添加参数。
`Request timed out` 服务器没有响应请检查服务器是否在线
`Server disconnected` 检查网络并重新启动 Claude Desktop

手动测试连接

无终端，执行：

npx -y mcp-remote https:///sse --transport sse-only --header "Authorization:Bearer "

如果连接正确，您将看到交换JSON消息。

15.8 多个 MCP 服务器

若要在 Advbox 中添加其他 MCP 服务器：

{
  "mcpServers": {
    "advbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https:///sse",
        "--transport",
        "sse-only",
        "--header",
        "Authorization:Bearer "
      ]
    },
    "outro-servidor": {
      "command": "npx",
      "args": ["-y", "outro-mcp-server"]
    }
  }
}

______________________________________________________________________

*2026年1月5日添加的部分*

Advbox MCP Server

快速接入

详细介绍

📚 MCP Advbox Server 文件

📑 索引

1. 概述

什么是MCP Advbox？

主要功能

使用案例

2. 建筑

图片

堆栈技术

文件结构

3. 安装

先决条件

一步一步

例子

错误

6.端点HTTP

GET/健康

POST/执行

7. 可用工具

简历（19工具）

7.1客户（顾客）

列表_客户

get_客户

搜索_客户

创建_客户

7.2诉讼（过程）

list_lawsuits

get_lawsuit

搜索服

create_lawsuit

update_lawsuit

7.3 交易（Transactions）

list_交易

get_transaction

7.4任务（Tarefas）

list_tasks

创建任务

7.5 设置（Settings）

获取设置

用户名

get_origins

获取_页面

get_type_lawsuits

7.6奖励（奖励）

获取用户奖励

8. 使用范例

8.1 全MCP流（SSE）

8.2 直接执行（REST）

8.3 页面

9. 安全

9.1实施的控制

9.2 安全标题

9.3科尔

9.4集装箱安全

9.5 良好实践

10. 与n8n集成

10.1 MCP 客户端设置

10.2 自动化中最常用的工具

11. 监测

11.1健康检查

11.2日志做容器

11.3 监测指标

11.4 Uptime Kuma 集成

12.故障排除

12.1 常见错误

401未经授权

429请求太多

503连接太多

连接被拒绝

API错误401（Advbox）

12.2诊断命令

13.变更日志

v2.2.0（2026年1月5日）-硬化

v2.1.0（2026年1月5日）

v2.0.0（2026年1月4日）

v1.0.0（2026年1月3日）

14. 快速参考