内容
# Cognigy.AI 管理 MCP 服务器
> 用于通过管理 API 管理 Cognigy.AI 虚拟代理的模型上下文协议服务器
>
> 这是一个独立的、开源的 MCP 服务器，与 Cognigy 或 NiCE 无关，也不受其赞助或认可。它需要您自己的有效的 Cognigy.AI 账户和 API 密钥，按照 Cognigy 的商业许可条款使用。“Cognigy”和“Cognigy.AI”是其各自所有者的商标。
## 什么是 Cognigy.AI 管理 MCP 服务器？
**cognigy-ai-mcp-management-server** 是一个本地 MCP 服务器，使 AI 编码助手（Claude、Cursor 等）能够以编程方式构建、配置、测试和操作 [Cognigy.AI](https://www.cognigy.com/) 对话式 AI 代理。
不再需要点击 Cognigy UI，您现在可以：
- 通过自然语言创建和管理流程、节点和意图
- 自动运行 NLU 训练和回归测试
- 跨环境部署快照和软件包
- 配置 LLM、知识 AI 和集成
**为以下人员构建：** 开发者、解决方案架构师和 SI 合作伙伴，他们在 Cognigy.AI 上构建。
## 要求
- **Node.js** 20.0.0 或更高版本
- **Cognigy.AI 账户**，具有 API 访问权限（试用版、SaaS 或本地部署）
- **API 密钥**，从 Cognigy UI（我的个人资料 → API 密钥）生成
## 安装
```bash
# 1. 安装 Cognigy REST API 客户端（必需的对等依赖项）
npm install @cognigy/rest-api-client
# 2. 安装此 MCP 服务器
npm install -g cognigy-ai-mcp-management-server
```
**重要：** `@cognigy/rest-api-client` 包在“Cognigy 专有许可”下许可。通过安装它，您同意 Cognigy 的许可条款。
## 配置
在运行之前设置环境变量：
```bash
# 必需：您的 Cognigy API 端点
export COGNIGY_BASE_URL=https://api-trial.cognigy.ai
# 必需：您的 API 密钥（请勿提交此密钥！）
export COGNIGY_API_KEY=your-api-key-here
# 可选：操作的默认项目
export COGNIGY_DEFAULT_PROJECT_ID=your-project-id
```
**常见基本 URL：**
| 环境 | 基本 URL |
|-------------|----------|
| 试用版 | `https://api-trial.cognigy.ai` |
| SaaS 欧盟 | `https://api-app.cognigy.ai` |
| SaaS 美国 | `https://api-app-us.cognigy.ai` |
| 专属 | `https://api-<company>.cognigy.cloud` |
## MCP 客户端配置
### Claude 桌面版
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```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"
}
}
}
}
```
### Claude 代码
添加到项目根目录的 `.mcp.json`：
```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`：
```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"
}
}
}
}
```
## 可用工具
[所有工具](https://github.com/TsvetanG2/cognigy-ai-mcp-management-server/blob/master/TOOLS.md)
此服务器提供 **132 个 MCP 工具**，按领域组织：
| 类别 | 工具 | 描述 |
|----------|-------|-------------|
| **项目和流程** | 5 | 列出项目、流程、流程设置、日志 |
| **节点** | 9 | CRUD 操作、搜索、移动、AI 输出生成 |
| **意图和 NLU** | 10 | 意图管理、训练、评分、审计 |
| **端点** | 2 | 列出和检查端点配置 |
| **会话** | 2 | 注入/重置对话上下文 |
| **对话** | 3 | 获取对话、转录记录 |
| **剧本和测试** | 6 | 运行剧本、回归测试 |
| **快照** | 9 | 创建、恢复、打包、差异、推广 |
| **软件包** | 7 | 创建、合并、上传、下载 |
| **连接** | 5 | 管理 API 连接（删除密钥） |
| **LLM** | 7 | 配置生成式 AI 提供商 |
| **NLU 连接器** | 5 | 外部 NLU（Dialogflow、LUIS 等） |
| **知识 AI** | 21 | 存储、来源、块、连接器（RAG） |
| **函数** | 9 | 自定义代码函数、实例 |
| **扩展** | 6 | 上传、配置、管理扩展 |
| **联系人资料** | 11 | 配置文件 CRUD、合并、导出（GDPR） |
| **分析** | 4 | 对话、调用、知识指标 |
| **审计** | 2 | 审计事件日志 |
| **移交** | 7 | 实时代理提供商和服务 |
| **搜索** | 1 | 全组织资源搜索 |
| **任务** | 2 | 异步任务状态跟踪 |
### 关键功能
- **默认安全：** 所有变更工具默认使用 `dryRun: true`
- **异步感知：** 长时间运行的操作会轮询直到完成
- **安全：** 内存中仅存储 API 密钥，密钥自动删除
- **分页：** 所有列表操作支持 `limit` 和 `skip`
## 开发和测试
### 模拟优先开发
针对 Prism 模拟服务器运行（无需 Cognigy 账户）：
```bash
# 终端 1：启动模拟服务器
npm run mock
# 终端 2：运行测试
npm test
```
### 直播 API 测试
```bash
# 从模板创建 .env
cp .env.example .env
# 使用您的凭证编辑 .env
# 运行开发服务器
npm run dev
```
### 构建
```bash
npm run build # 编译 TypeScript
npm test # 运行测试套件（49 个测试）
npm run lint # 检查代码风格
```
### 更新类型（可选）
如果您需要从较新的 Cognigy API 更新生成的类型：
```bash
npm run update:spec # 下载最新的 OpenAPI 规范
npm run gen:types # 重新生成 TypeScript 类型
```
## 重要：依赖项
此软件包需要 **`@cognigy/rest-api-client`** 作为 **对等依赖项**。这意味着：
1. **您必须单独安装它**（参见上面的安装）
2. **您接受 Cognigy 的许可条款**，通过安装他们的软件包
3. **我们不捆绑或重新分发** 任何 Cognigy 代码
**您负责：**
- 审查和接受 Cognigy 的专有许可条款
- 拥有使用 Cognigy API 的适当权限
- 保护您的 API 凭证安全
Cognigy REST API 客户端是由 Cognigy GmbH 维护的官方 SDK，并在 npm 上以“Cognigy 专有许可”发布。
## 许可
此 MCP 服务器在 **MIT 许可**下发布。有关详细信息，请参见 [LICENSE](LICENSE)。
注意：MIT 许可仅适用于此 MCP 服务器代码。依赖项（特别是 `@cognigy/rest-api-client`）受其自身许可的约束。
## 贡献
欢迎贡献！请：
1. 复刻仓库
2. 创建一个功能分支（`git checkout -b feature/amazing-feature`）
3. 遵循现有的代码模式（Zod 模式、dryRun 标志等）
4. 为新工具添加测试
5. 在提交前运行 `npm test && npm run build`
6. 提交拉取请求
### 开发指南
- 所有工具必须具有 Zod 输入验证
- 变更工具必须支持 `dryRun` 标志（默认值：true）
- 工具描述应适合 LLM（1-2 句话）
- 绝不记录或公开 API 密钥/密钥
- 在实时 API 之前针对模拟服务器进行测试
## 支持
- **问题：** [GitHub 问题](https://github.com/TsvetanG2/cognigy-ai-mcp-management-server/issues)
- **Cognigy 文档：** [docs.cognigy.com](https://docs.cognigy.com)
- **MCP 规范：** [modelcontextprotocol.io](https://modelcontextprotocol.io)
---
使用 [模型上下文协议](https://modelcontextprotocol.io) SDK 构建
