cognigy-ai-mcp-management-server

Cognigy.AI 管理 MCP 服务

用于通过 Management API 管理 Cognigy.AI 虚拟 Agent 的 Model Context Protocol 服务

这是一个独立的开源 MCP 服务，与 Cognigy 或 NiCE 无关联，也未获其认可或赞助。使用该服务需要拥有有效的 Cognigy.AI 账户和 API 密钥，并遵守 Cognigy 的商业许可条款。“Cognigy”和“Cognigy.AI”是其各自所有者的商标。

这是什么？

cognigy-ai-mcp-management-server 是一个本地 MCP 服务，可让 AI 编码助手（Claude、Cursor 等）以编程方式构建、配置、测试和运行 Cognigy.AI 对话式 AI Agent。

现在，你无需再点击 Cognigy UI，即可：

• 通过自然语言创建和管理流程、节点及意图
• 自动运行 NLU 训练和回归测试
• 跨环境部署快照和程序包
• 配置 LLM、Knowledge AI 和集成

适用对象： 在 Cognigy.AI 上进行开发的开发者、解决方案架构师和解决方案集成合作伙伴。

要求

• Node.js 20.0.0 或更高版本
• Cognigy.AI 账户，并拥有 API 访问权限（Trial、SaaS 或本地部署）
• API Key，在 Cognigy UI 中生成（My Profile → API Keys）

安装

# 1. Install the Cognigy REST API client (required peer dependency)
npm install @cognigy/rest-api-client

# 2. Install this MCP server
npm install -g cognigy-ai-mcp-management-server

重要提示： @cognigy/rest-api-client 软件包采用“Cognigy Proprietary License”许可。安装该软件包即表示你同意 Cognigy 的许可条款。

配置

运行前设置环境变量：

# Required: Your Cognigy API endpoint
export COGNIGY_BASE_URL=https://api-trial.cognigy.ai

# Required: Your API key (never commit this!)
export COGNIGY_API_KEY=your-api-key-here

# Optional: Default project for operations
export COGNIGY_DEFAULT_PROJECT_ID=your-project-id

常见基础 URL：

环境	基础 URL
Trial	https://api-trial.cognigy.ai
SaaS EU	https://api-app.cognigy.ai
SaaS US	https://api-app-us.cognigy.ai
Dedicated	https://api-<company>.cognigy.cloud

MCP 客户端配置

Claude Desktop

将配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

将配置添加到项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

将配置添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

可用工具

所有工具

此服务提供 132 个 MCP 工具，按领域组织：

类别	工具数	描述
项目与流程	5	列出项目、流程、流程设置和日志
节点	9	CRUD 操作、搜索、移动、AI 输出生成
意图与 NLU	10	意图管理、训练、评分、审计
端点	2	列出并检查端点配置
会话	2	注入/重置对话上下文
对话	3	获取对话和转录记录
Playbook 与测试	6	运行 Playbook、回归测试
快照	9	创建、恢复、打包、比较、提升
包	7	创建、合并、上传、下载
连接	5	管理 API 连接（机密信息已隐藏）
大模型	7	配置生成式 AI 提供商
NLU 连接器	5	外部 NLU（Dialogflow、LUIS 等）
Knowledge AI	21	存储、来源、分块、连接器（RAG）
函数	9	自定义代码函数、实例
扩展	6	上传、配置、管理扩展
联系人档案	11	档案 CRUD、合并、导出（GDPR）
分析	4	对话、通话、知识指标
审计	2	审计事件日志
转接	7	实时 Agent 提供商和服务
搜索	1	搜索整个组织的资源
任务	2	异步任务状态跟踪

主要功能

• 默认安全： 所有变更工具默认使用 dryRun: true
• 支持异步操作： 长时间运行的操作会轮询，直到完成
• 安全性： API 密钥仅保存在内存中，机密信息会自动隐藏
• 分页： 所有列表操作均支持 limit 和 skip

开发与测试

实时 API 测试

# Create .env from template
cp .env.example .env
# Edit .env with your credentials

# Run development server
npm run dev

构建

npm run build    # Compile TypeScript
npm test         # Run test suite (49 tests)
npm run lint     # Check code style

重新生成类型（可选）

如果需要根据较新版的 Cognigy API 更新生成的类型：

npm run update:spec   # Download latest OpenAPI spec
npm run gen:types     # Regenerate TypeScript types

重要：依赖项

此软件包需要将 @cognigy/rest-api-client 作为对等依赖项。这意味着：

1. 你必须单独安装它（参见上文的安装说明）
2. 安装 Cognigy 的软件包即表示你接受其许可条款
3. 我们不会打包或再分发任何 Cognigy 代码

你有责任：

• 查看并接受 Cognigy 的专有许可条款
• 确保拥有使用 Cognigy API 的适当权限
• 妥善保管 API 凭据

Cognigy REST API 客户端是由 Cognigy GmbH 维护的官方 SDK，并以「Cognigy Proprietary License」授权发布在 npm 上。

许可证

此 MCP 服务采用 MIT 许可证发布。详情请参阅 LICENSE。

注意：MIT 许可证仅适用于此 MCP 服务代码。依赖项（尤其是 @cognigy/rest-api-client）受其各自许可证约束。

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 遵循现有代码模式（Zod 模式、dryRun 标志等）
4. 为新工具添加测试
5. 提交前运行 npm test && npm run build
6. 提交 Pull Request

开发指南

• 所有工具都必须进行 Zod 输入验证
• 变更工具必须支持 dryRun 标志（默认值：true）
• 工具描述应便于大模型理解（1-2 句话）
• 切勿记录或暴露 API 密钥/机密信息
• 使用实时 API 前，先对模拟服务进行测试

支持

• 问题反馈： GitHub Issues
• Cognigy 文档： docs.cognigy.com
• MCP 规范： modelcontextprotocol.io

---

使用 Model Context Protocol SDK 构建