Uisp MCP Server

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个工具）

NMS工具（4个工具）

实用工具（4个工具）

工具使用示例

客户搜索

{ "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连接失败

1. 验证服务器是否手动启动：

   cd mcp-uisp-server && npm run dev

1. 检查环境变量是否已设置
2. 确保路径 .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

发展

添加新工具

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

建筑

npm run build

许可证

麻省理工学院

支持

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