Cisco CX Cloud MCP Server

思科CX云MCP服务器

一种模型上下文协议（MCP）服务器，提供对Cisco CX Cloud API的自然语言访问。通过Claude或其他MCP兼容客户端使用会话语言查询您的思科库存、合同、警报等。

特性

此MCP服务器提供10个工具来访问Cisco CX Cloud数据：

客户管理

• 获取客户计数 -获取所有可访问的CX Cloud客户帐户和ID

库存管理

• 获取硬件库存 -为客户获取硬件清单
• get_network_elements -获取网络元素和设备

合同管理

• get_contracts -获取客户的所有合同
• get_covered_assets -获得合同涵盖的资产
• 获得未收回资产 -识别覆盖范围差距

产品警报

• get_field_通知 -获取现场通知和公告
• get_hardware_eol -获取硬件寿命终止信息
• get_software_eol -获取软件寿命终止信息
• get_security_advisories -获取安全建议和警报

先决条件

1. Cisco.com帐户 -您需要一个Cisco.com帐户
2. CX云访问 -您必须在至少一个CX Cloud帐户中拥有角色https://cx.cisco.com
3. API证书 -注册应用程序以获取OAuth凭据

安装说明

第一步：注册您的申请

1. 首选 Cisco API控制台
2. 使用您的Cisco.com凭据登录
3. 点击“我的应用程序和密钥”→ “注册新应用程序”
4. 选择“服务”作为应用程序类型
5. 选择“客户端凭据”作为授权类型
6. 添加以下CX云API资源：

- 警报v2 - 合同v2 - 客户v2 - 库存v2

1. 接受条款并完成注册
2. 保存您的 客户端ID 和 客户端密钥

步骤2：将凭据与CX Cloud关联

1. 登录到 CX云
2. 导航至 个人资料和帐户 → 管理个人资料 → API 标签
3. 输入步骤1中的客户ID

备注：首次安装后，您可能会延迟10分钟才能使用API。

步骤3：安装和配置

# Install dependencies
npm install

# Create .env file from example
cp .env.example .env

# Edit .env and add your credentials
# CISCO_CLIENT_ID=your_client_id_here
# CISCO_CLIENT_SECRET=your_client_secret_here

步骤4：构建服务器

npm run build

运行服务器

开发模式（带自动重新加载）

npm run dev

生产模式

npm start

Claude桌面配置

要将此MCP服务器与Claude Desktop一起使用，请将以下内容添加到配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cisco-cx-cloud": {
      "command": "node",
      "args": [
        "/absolute/path/to/cisco-cx-cloud-mcp/dist/index.js"
      ],
      "env": {
        "CISCO_CLIENT_ID": "your_client_id_here",
        "CISCO_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

重要：替换 /absolute/path/to/cisco-cx-cloud-mcp/ 使用您的实际安装路径并添加您的真实凭据。

配置后，重新启动Claude Desktop。

使用示例

配置后，您可以向Claude提出以下问题：

入门指南

• “我可以访问哪些客户帐户？”
• “显示我的客户ID”

库存查询

• “我们为客户XYZ准备了哪些硬件库存？”
• “列出我的客户的所有网络元素”
• “显示我们库存中的所有Cisco设备”

合同管理

• “我们有什么合同？”
• “是否有任何没有合同保障的资产？”
• “支持合同涵盖哪些设备？”

警报和合规性

• “有什么我应该知道的安全建议吗？”
• “什么硬件即将达到生命周期的终点？”
• “显示客户ABC的所有字段通知”
• “哪些软件版本正在被弃用？”

复杂查询

• “查找所有未覆盖的资产，并检查是否有安全建议”
• “向我展示EOL和合同未涵盖的硬件”
• “将我们的库存与有效合同进行比较”

运作原理

1. OAuth身份验证：服务器使用客户端凭据自动处理OAuth 2.0身份验证
2. 许可证管理：访问令牌会被缓存，并在过期时自动刷新
3. API调用：自然语言请求被转换为适当的API调用
4. 数据格式化：响应采用易于阅读的JSON格式
5. 日志记录：全面的日志记录跟踪所有调试和监控操作

日志记录

服务器包括详细的日志记录功能：

日志级别

通过配置日志记录 LOG_LEVEL 环境变量：

• 错误 -仅错误（身份验证失败、API错误）
• 警告 -警告和错误
• 信息 -一般信息、工具调用、API请求（默认）
• 调试 -详细的调试，包括请求/响应细节、令牌管理

配置

编辑您的 .env 文件：

# Set log level (ERROR, WARN, INFO, DEBUG)
LOG_LEVEL=DEBUG

# Enable file logging
LOG_TO_FILE=true

# Set log directory (default: ./logs)
LOG_DIR=./logs

日志输出

控制台日志 （标准错误） ：

• 通过Claude Desktop运行时：检查 ~/Library/Logs/Claude/mcp*.log （macOS）
• 手动运行时：日志显示在终端中

文件日志 （可选）：

• 启用 LOG_TO_FILE=true
• 文件是在 LOG_DIR 目录
• 按日期命名： mcp-server-2024-12-01.log

记录的内容

信息级别：

• 服务器启动/关闭
• 工具调用
• 身份验证事件
• 工具完成时间

调试级别（包括INFO plus）：

• 环境配置
• OAuth令牌详细信息（已净化）
• API完整的请求/响应周期
• 请求时间和性能指标

调试输出示例：

[2024-12-01T00:00:00.000Z] [INFO] Cisco CX Cloud MCP Server starting...
[2024-12-01T00:00:00.001Z] [DEBUG] Environment loaded
{
  "logLevel": "DEBUG",
  "hasClientId": true,
  "hasClientSecret": true
}
[2024-12-01T00:00:01.000Z] [INFO] Tool invoked: get_customer_accounts
[2024-12-01T00:00:01.100Z] [DEBUG] API Request: GET https://apix.cisco.com/...
[2024-12-01T00:00:01.500Z] [DEBUG] API call completed in 400ms
[2024-12-01T00:00:01.501Z] [INFO] Tool SUCCESS: get_customer_accounts
{
  "duration": "500ms"
}

API费率限制

Cisco CX Cloud API具有速率限制。服务器处理：

• 自动令牌刷新（令牌在1小时后过期）
• API故障的错误处理
• 正确的身份验证标头管理
• 用于调试的请求/响应日志记录

项目结构

cisco-cx-cloud-mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── auth.ts           # OAuth authentication client
│   └── logger.ts         # Logging utility
├── dist/                 # Compiled JavaScript (generated)
├── logs/                 # Log files (if LOG_TO_FILE=true)
├── .env.example          # Environment template
├── .env                  # Your credentials (git-ignored)
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

故障排除

身份验证错误

• 验证您的客户端ID和密码是否正确
• 确保您已将客户端ID与CX Cloud配置文件相关联
• 首次设置后等待10分钟
• 检查日志：设置 LOG_LEVEL=DEBUG 查看详细的OAuth流程

未返回数据

• 确认您有权访问CX Cloud帐户https://cx.cisco.com
• 验证您的用户是否分配了正确的角色
• 检查您是否使用了正确的客户ID
• 检查日志：查找API响应代码和错误消息

API错误

• 检查API控制台中是否启用了所有必需的API资源
• 确保您的凭据尚未过期
• 验证网络连接
• 检查日志：使用查看完整的错误堆栈跟踪 LOG_LEVEL=DEBUG

调试提示

启用调试日志记录：

# In .env file
LOG_LEVEL=DEBUG
LOG_TO_FILE=true

实时查看日志：

# macOS - Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Or if LOG_TO_FILE=true
tail -f ./logs/mcp-server-*.log

常见日志消息：

• "Access token obtained successfully" -身份验证工作
• "Tool invoked: get_customer_accounts" -克劳德调用的工具
• "API call completed in Xms" -请求性能
• "Failed to obtain access token" -检查凭据

资源

• Cisco CX Cloud API文档
• Cisco API控制台
• CX云门户
• 模型上下文协议

许可证

国际学生委员会