使用说明

MCP UISP服务器

一种模型上下文协议（MCP）服务器，提供对UISP CRM和NMS API的统一访问。此服务器将72+个单独的API操作合并到 13个面向工作流的工具，将上下文开销减少了82%。

特性

13个综合工具 -从72+个工具下降
基于行动的设计 -每个工具都支持多种操作（搜索、获取、更新等）
智能型强制 -自动处理MCP字符串参数
输出格式 -JSON、markdown和简洁的输出选项
错误处理 -与代码和消息一致的错误响应
CRM+NMS集成 -完全访问这两个系统

快速开始

先决条件

Node.js 18.x或更高版本
npm
访问UISP服务器（CRM+NMS API）

安装

cd mcp-uisp-server
npm install

配置

设置这些环境变量：

UISP_CRM_URL=https://your-uisp-server/crm/api/v1.0
UISP_CRM_API_KEY=your-crm-api-key
UISP_NMS_URL=https://your-uisp-server/nms/api/v2.1
UISP_NMS_API_KEY=your-nms-api-key
NODE_TLS_REJECT_UNAUTHORIZED=0  # Only for self-signed certs

跑步

# Development (TypeScript directly)
npm run dev

# Production
npm run build && npm start

与Claude Code集成

选项1：本地 `.mcp.json` （推荐）

创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "uisp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-uisp-server/dist/server.js"],
      "env": {
        "UISP_CRM_URL": "https://your-uisp-server/crm/api/v1.0",
        "UISP_CRM_API_KEY": "your-crm-api-key",
        "UISP_NMS_URL": "https://your-uisp-server/nms/api/v2.1",
        "UISP_NMS_API_KEY": "your-nms-api-key",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

选项2：使用tsx（开发）

对于没有构建的TypeScript，创建一个包装器脚本：

uisp-mcp-start.sh:

#!/bin/bash
cd /path/to/mcp-uisp-server
exec node node_modules/tsx/dist/cli.mjs src/server.ts

然后在 .mcp.json:

{
  "mcpServers": {
    "uisp": {
      "type": "stdio",
      "command": "/path/to/uisp-mcp-start.sh",
      "args": [],
      "env": {
        "UISP_CRM_URL": "...",
        "UISP_CRM_API_KEY": "...",
        "UISP_NMS_URL": "...",
        "UISP_NMS_API_KEY": "...",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

选项3:Claude桌面配置

添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "uisp": {
      "command": "node",
      "args": ["/path/to/mcp-uisp-server/dist/server.js"],
      "env": {
        "UISP_CRM_URL": "...",
        "UISP_CRM_API_KEY": "...",
        "UISP_NMS_URL": "...",
        "UISP_NMS_API_KEY": "..."
      }
    }
  }
}

13个综合工具

CRM工具（6个工具）

工具	操作	描述
`uisp_client`	搜索、获取、更新	客户端管理
`uisp_payment`	create、list、get_methods	付款处理
`uisp_invoice`	列表、发送、生成.pdf	发票操作
`uisp_service`	get_plans、get、suspend、unsuspend，change_plan、get_starts	服务管理
`uisp_communication`	send_email、send_sms、create_ticket、get_tickets、get_email_queue	消息传递

NMS工具（4个工具）

工具	操作	描述
`uisp_site`	list、get、get_devices、get_path	站点操作
`uisp_device`	list、get、restart、get_starts	设备管理
`uisp_diagnostics`	speed_test、trace_route、cable_test、get_outages、get_link_quality	网络诊断
`uisp_wireless`	get_stations、get_signal、scan_frequencies、get_capacity、get_interference	无线管理

实用工具（4个工具）

工具	操作	描述
`uisp_health_check`	test_connection、service_health、get_alerts、get_outage_summary	系统健康状况
`uisp_batch_operation`	批处理付款、批处理暂停、批处理消费、批处理邮件、批处理设备重新启动	批处理操作
`uisp_analytics`	收入、网络性能、客户使用、发票使用	报告和分析
`uisp_automation`	check_auto_suspend、execute_auto_ssuspend、check_provisiting、optimize_frequencies	自动化

工具使用示例

客户搜索

{ "action": "search", "query": "Garcia" }
{ "action": "search", "phone": "+5491155551234" }
{ "action": "get", "clientId": 123, "include": ["services", "balance"] }

付款创建

{ "action": "create", "clientId": 123, "amount": 5000, "method": "transfer" }
{ "action": "list", "clientId": 123, "limit": 10 }

服务管理

{ "action": "get_plans", "activeOnly": true }
{ "action": "suspend", "serviceId": 123, "reason": "Non-payment" }
{ "action": "change_plan", "serviceId": 123, "newPlanId": 5 }

网络诊断

{ "action": "get_outages", "includeResolved": false, "limit": 10 }
{ "action": "speed_test", "deviceId": "abc-123", "duration": 15 }

分析

{ "action": "revenue", "period": "month" }
{ "action": "invoice_aging" }

自动化（小心使用！）

{ "action": "check_auto_suspend", "daysOverdue": 30, "minimumAmount": 1000 }
{ "action": "execute_auto_suspend", "daysOverdue": 30, "dryRun": true }

api参考

公共参数

所有工具支持：

format: "json" | "markdown" | "concise" （默认值： "json")

错误响应格式

{
  "success": false,
  "action": "action_name",
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE"
  }
}

状态代码

服务状态（UISP）：

1=活动
2=结束
3=暂停
4=准备就绪
5=报价

发票状态：

1=未付
2=部分支付
3=逾期
4=已支付
5=无效

项目结构

mcp-uisp-server/
├── src/
│   ├── server.ts              # MCP server entry point
│   ├── tools/
│   │   ├── base-tool.ts       # Base tool class
│   │   └── consolidated/      # 13 unified tools
│   │       ├── client.ts
│   │       ├── payment.ts
│   │       ├── invoice.ts
│   │       ├── service.ts
│   │       ├── communication.ts
│   │       ├── site.ts
│   │       ├── device.ts
│   │       ├── diagnostics.ts
│   │       ├── wireless.ts
│   │       ├── health.ts
│   │       ├── batch.ts
│   │       ├── analytics.ts
│   │       └── automation.ts
│   ├── types/                 # TypeScript types
│   └── utils/
│       ├── api-client.ts      # UISP API client
│       └── zodCoerce.ts       # Type coercion helpers
├── test-outputs/              # Sample JSON outputs
├── package.json
└── tsconfig.json

故障排除

SSL证书错误

对于自签名证书：

NODE_TLS_REJECT_UNAUTHORIZED=0

MCP连接失败

验证服务器是否手动启动：
```
cd mcp-uisp-server && npm run dev
```
检查环境变量是否已设置
确保路径 .mcp.json 是绝对的

“无法读取undefined的属性”

检查UISP API密钥是否正确
验证UISP服务器是否可访问
某些API响应可能具有空字段（我们处理大多数情况）

工具未出现

修改后重新启动Claude Code .mcp.json
检查配置中的JSON语法错误
验证服务器进程是否可以执行

测试

# List all tools
npm run test:list

# Test specific tool
npm run test:tool uisp_client

# Interactive test client
npm run test:interactive

# Run test scenarios
npm test

发展

添加新工具

在中创建文件 src/tools/consolidated/
扩展 BaseTool 类
定义Zod输入模式
实现操作处理程序
出口自 src/tools/index.ts

建筑

npm run build

许可证

麻省理工学院

支持

对于问题和功能请求，请打开GitHub问题。