内容
NiFi](https://raw.githubusercontent.com/Giojacke/mcpipilot/master/docs/assets/logo(2).png)
# NiFiPilot — AI 助手适用于 Apache NiFi
适用于 Apache NiFi 2.2.0（模型上下文协议）服务器。让 AI 代理安全、可审计地检查、构建和控制 Ni，借助 17 种现成的工具。
[](tests/)
[](pyproject.toml)
[](LICENSE)
[](https://nifi.apache.org)
[](https://pypi.org/project/nifi-mcp/)
[](https://marketplace.visualstudio.com/items?itemName=CodHector.nifipilot)
---
## 功能概述
NiFiPilot 将 Apache NiFi 的 REST API 公开为 MCP 工具，允许任何兼容的 AI 代理：
- **检查** 运行中的流程、处理器状态、队列深度和系统健康状况
- **构建** 从自然语言创建流程组、处理器和连接
- **控制** 启动/停止单个处理器或整个流程组
- **审计** 每个操作 — 每个工具调用都写入 JSON 日志
Pilot 在 VS Code 中 — Claude 使用 NiFi 画布实时执行 MCP 工具*
---
## 功能特点
- **17 种工具**，分为三类：读取（5）、写入（6）、控制（6）
- **只读模式** — 写入和控制工具被阻止；生产环境监控安全
- **预运行模式** — 预览写入/控制操作而不执行它们
结构化审计日志** — 每个工具调用都记录参数和时间戳
- **延迟身份验证** — 在时获取 JWT 令牌，并在 401 时自动刷新
传输** — 标准输入输出（本地客户端）和 SSE（Docker/远程）
- **37 个单元测试** — 无需实时 NiFi
---
## 快速入门 Docker Compose
捆绑的 compose 文件启动 NiFi 2.2.0 和 MCP 服务器。
```bash
# 1. 复制并编辑环境变量文件
cp .env.example .env
# 编辑 NIFI_PASSWORD（最少 12 个字符）并设置 MCP_MODE=full 以允许写入/控制
# 2. 启动两个服务
docker compose up --build
# 3. NiFi UI：https://localhost:8443（首次启动约 2 分钟）
# MCP SSE：http://localhost:/sse
```
将任何兼容 MCP 的客户端连接到 SSE 端点：
```json
{
"mcpServers": {
"nifi-mcp": { "url": "http://localhost:8000/sse" }
}
}
```
---
## 手动安装
**要求：** Python 3.11+
```bash
# 从源码
git clone https://github.com/Giojacke/mcp-nifipilot
cd mcp-nifipilot
pip install .
```
在标准输入输出模式下运行（由 Claude Code、VS Code、Cursor 使用）：
```bash
NIFI_URL=https://localhost:8443 \
NIFI_USERNAME=admin \
NIFI_PASSWORD=your-password \
NIFI_VERIFY_SSL=false \
MCP_MODE=readonly \
nifi-mcp
```
---
## 配置
所有设置均来自环境变量（或工作目录中的 `.env` 文件）。
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `NIFI_URL` | `https://localhost:8443` | NiFi 基本 URL |
| `NIFI_USERNAME` | `admin` | NiFi 用户名 |
| `NIFI_PASSWORD` | _（必填）_ | NiFi 密码（单用户身份验证最少 12 个字符）|
| `NIFI_VERIFY_SSL` | `false` | 验证 TLS 证书（生产环境中为 `true`）|
| `MCP_MODE` | `readonly` | `readonly` — 仅读取工具；`full` — 所有工具 |
| `MCP_AUDIT_LOG` | `true` | 写入 JSON 审计日志 |
| `MCP_AUDIT_LOG_PATH` | `./logs/audit.log` | 审计日志文件路径 |
| `MCP_RATE_LIMIT` | `60` | 每分钟最大工具调用次数 |
| `MCP_DRY_RUN` | `false` | 描述写入/控制操作而不执行 |
| `MCP_TRANSPORT` | `stdio` | 本地 `stdio`；Docker 使用 `sse` |
| `_HOST` | `0.0.0.0` `MCP_TRANSPORT=sse` 时绑定主机 |
MCP_PORT` | `8000` | 当 `MCP_TRANSPORT=sse` 时端口 |
---
## 工具参考
### 读取工具 _（始终可用）
| 工具 | 描述 |
| --- | --- |
| `get_process_groups(group_id)` | 列出直接子流程组 |
| `get_processors(group_id)` | 列出组中的处理器及其运行状态 |
| `get_connections(group_id)` | 列出连接及其队列深度 |
| `get_flow_status(group_id)` | 运行/停止/无效计数和吞吐量 |
| `get_system_diagnostics()` | NiFi 版本、堆、CPU、运行时间 |
### 写入工具 _（需要 `MCP_MODE=full`）
| 工具 | 描述 |
| --- | --- |
| `create_process_group(name, parent_group_id, x, y)` | 创建新的流程组 |
| `create_processor(name, processor_type, group_id, x, y)` | 添加处理器（完整的 Java 类名）|
| `update_processor(processor_id, name?, properties?, scheduling_period?)` | 更新处理器配置 |
| `create_connection(source_id, destination_id, group_id, relationships?, ...)` | 连接两个组件 |
delete_processor(processor_id)` | 删除已停止的处理器 |
| `delete_process_group(group_id)` |停止的流程组 |
### 控制工具 _（需要 `MCP_MODE=full`）
| 工具 | 描述 |
| --- | --- |
| `start_processor(processor_id)` | 启动处理器 |
| `stop_processor(processor_id)` | 停止处理器 |
| `start_process_group(group_id)` | 启动组中的所有处理器 |
| `stop_process_group(group_id)` | 停止组中的所有处理器 |
| `get_queue_status(connection_id)` | 队列深度和吞吐量 |
| `purge_queue(connection_id)` | 清空队列中的所有流文件 |
---
## 客户端设置
### Claude Code（标准输入输出）
项目根目录下的 `.mcp.json` 已预先配置。填写您的密码：
```jsonc
{
"mcpServers": {
"nifi-mcp": {
"command": "nifi-mcp",
" {
"N": "https://localhost:8443",
"NIFI_USERNAME": "admin",
"NIFI_PASSWORD": "YOUR_PASSWORD",
"NIFI_VERIFY_SSLfalse",
"MCP_MODE": "readonly"
}
}
}
}
```
### Claude Code（SSE — Docker 栈运行）
```jsonc
{
"mcpServers": {
"nifi-mcp": { "url": "http://localhost:8000/sse" }
}
}
```
### VS Code
从 VS Code 市场安装：[NiFiPilot — AI适用于 Apache NiFi](https://marketplace.visualstudio.com/items?itemName=CodHector.nifipilot)
复制 `.vscode/mcp.json`（已包含）并填写您的密码。
### Cursor / Windsurf
将标准输入输出配置放在 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目）。
---
## 安全模型
| 关注点 | 缓解措施 |
| --- | --- |
| 凭证暴露 | 所有机密均通过环境变量 — 绝不硬编码 |
| 意外写入 | `MCP_MODE=readonly` 阻止所有写入和控制工具 |
| 失控更改 | `MCP_DRY_RUN=true` 描述操作而不执行 |
| 可审计性 | 每个工具调用写入审计日志的 JSON 条目 |
|令牌过期 | `ensure_authenticated()` 在 401 时自动重新登录 |
| 生产环境中的 SSL | 设置 `NIFI_VERIFY_SSL=true` 和有效的证书 |
---
## 开发
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试（无需实时 NiFi）
pytest
# 检查
ruff check src tests format src tests
在 API 类级别模拟 nipyapi — 37 个需实时 NiFi。集成测试可以添加到 `tests/`（默认测试运行中排除）。
---
##技能
NiFiPilot一个代理技能 — 一个结构化的指令集，教 代理如何安全有效地使用 MCP 工具。
位于 [`skills/nifipilot-agent.md/nifipilot)，涵盖：
- 标准工作流程（创建、控制、调试）
- 安全操作的黄金法则
- 常见处理器类型参考
- 生产模式指南
- 入门示例提示
### 快速入门技能
**Claude Code：** 添加到您的 `CLAUDE.md`。
**VS Code：** 在开始 NiFi 会话前，将 `skills/nifipilot-agent.md` 固定到聊天上下文中。
---
## 架构
参见 [ARCHITECTURE.md](ARCHITECTURE.md) 获取设计决策和 C4 图表。
---
## 路线图
- [ ] 速率限制强制执行（配置存在，中间件待定）
] `NiFiClient` facade（工具当前直接调用 nipyapi）
- [ ] 针对实时 的集成测试
- 用于 NiFi 流的 CI/CD 的 Azure DevOps MCP 桥
- [get_processor_details` — NiFi 2.x 兼容性的完整处理器配置切属性名称
许可证
MIT
