内容
# SGP MCP 服务器
SGP MCP 服务器，用于与 **SGP（服务提供商管理系统）** 进行集成，专为在 Cloudflare Workers 上运行而开发。
## 🚀 功能特点
此 MCP 服务器提供了 **50+ 种工具** ，供 AI 助手与 SGP 进行交互：
### 客户和合同
- 按 CPF/CNPJ、电话号码或名称查询客户
- 列出和详细显示合同
- 检查状态和待办事项
### 财务
- 列出账单（已开具、已支付、已过期）
- 生成账单第二联
- 查询和生成付款通知书
### 支持
- 开启和管理工单
- 添加互动
- 指派给客服人员
- 完成服务
### 服务订单
- 创建安装、维护等服务订单
- 安排和重新安排服务
- 转移给其他技术人员
- 查询技术人员日程
### FTTH（光纤网络）
- 管理 ONU（配置、重启、状态）
- 查询 OLT
- 管理机柜（CTO/CEO）
- 查询分光器
### 库存
- 列出产品和类别
- 记录出入库（入库/出库）
- 查询供应商
- 管理库存
### RADIUS
- 管理 RADIUS 用户
- 阻止/解除阻止连接
- 监控活动会话
- 结束会话
- 查询计费记录
## 📦 安装
### 1. 克隆或复制项目
```bash
# 如果使用模板
npm create cloudflare@latest -- sgp-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless
# 或者直接复制文件到您的项目中
```
### 2. 安装依赖项
```bash
cd sgp-mcp-server
npm install
```
### 3. 配置凭证
编辑 `wrangler.toml` 文件或使用 secrets：
```bash
# 您的 SGP URL
wrangler secret put SGP_API_URL
# 输入：https://您的供应商.sgp.net.br/api
# 使用 Token 进行身份验证（推荐）
wrangler secret put SGP_TOKEN
wrangler secret put SGP_APP
# 或者使用 Basic 身份验证
wrangler secret put SGP_USERNAME
wrangler secret put SGP_PASSWORD
```
### 4. 部署
```bash
# 登录 Cloudflare
npx wrangler login
# 部署
npx wrangler deploy
```
部署后，您的 MCP 服务器将在以下地址可用：
```
https://sgp-mcp-server.<您的账户>.workers.dev
```
## 🔧 配置
### 环境变量
| 变量名 | 描述 | 是否必填 |
|----------|-----------|-------------|
| `SGP_API_URL` | SGP API 基本 URL | 是 |
| `SGP_AUTH_TYPE` | 身份验证类型：`basic` 或 `token` | 否（默认为 token） |
| `SGP_TOKEN` | API Token（如果 auth_type=token） | 条件必填 |
| `SGP_APP` | 应用名称（如果 auth_type=token） | 条件必填 |
| `SGP_USERNAME` | 用户名（如果 auth_type=basic） | 条件必填 |
| `SGP_PASSWORD` | 密码（如果 auth_type=basic） | 条件必填 |
### `wrangler.toml` 示例
```toml
name = "sgp-mcp-server"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]
[vars]
SGP_API_URL = "https://demo.sgp.net.br/api"
SGP_AUTH_TYPE = "token"
```
## 🔌 连接 MCP 客户端
### Claude Desktop
在您的 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"sgp": {
"command": "npx",
"args": [
"mcp-remote",
"https://sgp-mcp-server.<您的账户>.workers.dev/sse"
]
}
}
}
```
### Cloudflare AI Playground
1. 访问：https://playground.ai.cloudflare.com/
2. 点击“添加 MCP 服务器”
3. 粘贴 URL：`https://sgp-mcp-server.<您的账户>.workers.dev/sse`
### 其他 MCP 客户端
使用 `/mcp` 端点进行 Streamable HTTP 或 `/sse` 端点进行 Server-Sent Events。
## 📚 端点
| 端点 | 描述 |
|----------|-----------|
| `/` 或 `/health` | 健康检查 |
| `/tools` | 列出所有可用工具 |
| `/mcp` | MCP 端点（Streamable HTTP） |
| `/sse` | MCP 端点（Server-Sent Events） |
## 🛠️ 本地开发
```bash
# 在本地运行
npm run dev
# 服务器将在 http://localhost:8787 运行
```
使用 MCP Inspector 进行测试：
```bash
npx @anthropic/mcp-inspector http://localhost:8787/sse
```
## 📋 工具列表
### 客户
- `sgp_consultar_cliente` - 按 CPF/CNPJ、电话号码或名称查询客户
- `sgp_detalhes_cliente` - 客户详细信息
### 合同
- `sgp_listar_contratos` - 列出合同，支持筛选
- `sgp_detalhes_contrato` - 合同详细信息
- `sgp_consultar_contrato_resumido` - 通过 URA 查询合同摘要
### 账单
- `sgp_listar_faturas` - 列出账单，支持筛选
- `sgp_detalhes_fatura` - 账单详细信息
- `sgp_segunda_via_fatura` - 生成账单第二联
- `sgp_faturas_contrato` - 查询合同的账单（URA）
- `sgp_listar_boletos` - 列出付款通知书
- `sgp_detalhes_boleto` - 付款通知书详细信息
- `sgp_gerar_boleto` - 生成新的付款通知书
### 工单
- `sgp_listar_chamados` - 列出工单，支持筛选
- `sgp_detalhes_chamado` - 工单详细信息
- `sgp_abrir_chamado` - 新建工单
- `sgp_interagir_chamado` - 添加互动
- `sgp_atribuir_chamado` - 指派给客服人员
- `sgp_finalizar_chamado` - 完成服务
- `sgp_listar_categorias_chamado` - 列出工单类别
- `sgp_listar_interacoes_chamado` - 工单互动历史
### 服务订单
- `sgp_listar_ordens_servico` - 列出服务订单，支持筛选
- `sgp_detalhes_ordem_servico` - 服务订单详细信息
- `sgp_criar_ordem_servico` - 新建服务订单
- `sgp_atualizar_status_ordem` - 更新服务订单状态（开始、暂停、完成等）
- `sgp_reagendar_ordem` - 重新安排服务订单
- `sgp_transferir_ordem` - 转移给其他技术人员
- `sgp_comentario_ordem` - 添加评论
- `sgp_listar_comentarios_ordem` - 列出评论
- `sgp_listar_tipos_os` - 列出服务订单类型
- `sgp_listar_tecnicos` - 列出技术人员
- `sgp_agenda_tecnico` - 查询技术人员日程
### FTTH
- `sgp_listar_onus` - 列出 ONU 设备
- `sgp_detalhes_onu` - ONU 设备详细信息
- `sgp_provisionar_onu` - 配置 ONU 设备
- `sgp_desprovisionar_onu` - 取消配置 ONU 设备
- `sgp_reiniciar_onu` - 重启 ONU 设备
- `sgp_status_onu` - ONU 设备实时状态
- `sgp_listar_olts` - 列出 OLT 设备
- `sgp_detalhes_olt` - OLT 设备详细信息
- `sgp_listar_caixas` - 列出机柜（CTO/CEO）
- `sgp_detalhes_caixa` - 机柜详细信息
- `sgp_listar_splitters` - 列出分光器
- `sgp_detalhes_splitter` - 分光器详细信息
### 库存
- `sgp_listar_produtos` - 列出产品
- `sgp_detalhes_produto` - 产品详细信息
- `sgp_listar_movimentacoes` - 列出出入库记录
- `sgp_cadastrar_movimentacao` - 记录出入库
- `sgp_listar_fornecedores` - 列出供应商
- `sgp_listar_categorias_estoque` - 列出库存类别
- `sgp_listar_inventarios` - 列出库存
- `sgp_detalhes_inventario` - 库存详细信息
### RADIUS
- `sgp_listar_usuarios_radius` - 列出 RADIUS 用户
- `sgp_detalhes_usuario_radius` - RADIUS 用户详细信息
- `sgp_bloquear_usuario_radius` - 阻止 RADIUS 用户
- `sgp_desbloquear_usuario_radius` - 解锁 RADIUS 用户
- `sgp_resetar_senha_radius` - 重置 RADIUS 用户密码
- `sgp_listar_sessoes_radius` - 列出 RADIUS 会话
- `sgp_detalhes_sessao_radius` - RADIUS 会话详细信息
- `sgp_encerrar_sessao_radius` - 结束 RADIUS 会话
- `sgp_listar_grupos_radius` - 列出 RADIUS 分组
- `sgp_listar_nas` - 列出 NAS 服务器
- `sgp_detalhes_nas` - NAS 服务器详细信息
- `sgp_listar_accounting_radius` - 历史计费记录
## 📄 许可证
MIT
## 🤝 支持
如有关于 SGP API 的疑问，请查阅 [官方文档](https://documenter.getpostman.com/view/6682240/UzXKVyUs)。
