NiFiMCP

NiFiMCP

为 AI 提供理解 NiFi 流的上下文、通过引用证据调查故障以及起草后续方案所需的信息。

探索 NiFiMCP · 工作原理 · 带来一个关键的 NiFi 工作流

NiFiMCP 是一个用于基于证据调查 Apache NiFi 的开源 Model Context Protocol 服务。 它只读取信息，不会更改你的 NiFi。

公开预览版 0.1.0rc1。 已在 Linux x86_64 上使用 Python 3.12，对标准 Apache NiFi 2.12.0（单节点、证书身份验证）和 Claude Code 进行测试。对实时 NiFi 的访问是只读的；流程草稿是本地文件，由获授权人员另行导入。超出此范围的内容均在功能矩阵中标为未测试或不受支持。当前版本尚不完善，欢迎报告问题。

NiFiMCP 是一个面向 Apache NiFi 的独立项目，由 Lloyd Clark 创立并维护。它与 Apache Software Foundation 或 Cloudera 无关，也未获其赞助或认可。Apache NiFi 和 NiFi 是 Apache Software Foundation 的商标。网站：nifimcp.com。

1. 一分钟体验 NiFiMCP

此演示无需 NiFi、大模型或账号。它会重放从运行合成流程的真实 NiFi 2.12.0 实例中采集的证据。安装好 uv 后：

uvx --from nifimcp-server==0.1.0rc1 nifimcp demo --output ./nifimcp-demo

打开 nifimcp-demo/report.html。其中每条陈述都链接到其来源的确切字节。

2. 安装

NiFiMCP 需要 Python 3.12。PyPI 上的软件包名为 nifimcp-server，安装后会提供 nifimcp 命令 （nifi-mcp 是无关的项目，而 PyPI 会将 nifimcp 视为同一个名称）。0.1.0rc1 是预发布版本，因此请固定版本：

uv tool install nifimcp-server==0.1.0rc1   # installs the nifimcp command
nifimcp --version

或者，在 Python 3.12 虚拟环境中使用 pip 执行 pip install nifimcp-server==0.1.0rc1。

从源码安装，用于开发或运行测试套件：

git clone https://github.com/nifimcp/nifimcp.git
cd nifimcp
uv sync --frozen
uv run nifimcp demo --output ./nifimcp-demo

对于无法访问互联网的机器，请使用 GitHub 发布页中的离线安装包（包含哈希锁定的 wheel、SBOM 和许可证），并按照 docs/OFFLINE_INSTALL.md 操作。

3. 工作原理

1. 了解（预览版）：通过只读身份读取范围限定的流程、配置和实时状态。
2. 调查（预览版）：沿着证据追查问题；明确标出未知事项，并为每条陈述注明其来源字节。
3. 提出方案（预览版，实验性）：生成可供审核的本地流程草稿文件；由人员决定是否导入，并可先用独立的实验室 CLI 在一次性 NiFi 中测试。
4. 经批准后执行（路线图规划，当前预览版不包含）：此版本没有任何工具会更改 NiFi。

4. 连接权限受限的 NiFi 身份

NiFiMCP 有三种运行模式：

模式	读取内容	用途
demo	随附的合成采集数据	试用
bundle	你注册的流程定义和证据包	离线审查、共享案例
live	通过 HTTPS 和双向 TLS 连接到一个 NiFi 2.12.0 来源	调查运行中的系统

对于 live 模式，请创建一个专用的 NiFi 身份（客户端证书），并授予它对你希望助手查看的流程组的只读访问权限，仅此而已：

NiFi 策略	用途
查看用户界面（/flow）	每次 live 调用
查看每个受限流程组中的组件	描述和运行状况
查询沿袭（/provenance），并查看每个受限组中的沿袭	trace_feed、未匹配的历史记录
查看每个受限组中的数据	沿袭查询和队列元数据采样（NiFi 2.12.0 要求这两项都具备此权限）

NiFi 的“查看数据”策略还会允许此身份在 NiFi UI 中打开 FlowFile 内容。 NiFiMCP 没有访问内容、属性转储或重放的途径，只有列入允许列表的属性值会离开 服务端。没有此策略时，描述和运行状况仍可正常工作，而沿袭和采样会返回一条指出缺失策略的权限错误。

切勿授予写入策略。NiFiMCP 没有可修改 NiFi 的工具，受限身份是你的第二道 防线。然后编写操作员配置（docs/CONFIGURATION.md）并检查它：

nifimcp doctor --config operator.json

将服务添加到你的 MCP 宿主：

{
  "mcpServers": {
    "nifimcp": {
      "command": "uvx",
      "args": ["--from", "nifimcp-server==0.1.0rc1", "nifimcp", "serve", "--config", "/path/to/operator.json"]
    }
  }
}

evidence/host/ 中记录的 Claude Code 会话使用了同一命令的源代码检出形式 （uv run --frozen --project /path/to/nifimcp nifimcp serve --config ...）。其他可启动 stdio 服务的 MCP 宿主也应能使用同一命令，但尚未经过测试。

5. 五个实用提示词

1. “为一位没有构建过该流程的值班操作员解释范围 orders-intake 内的流程。引用证据并列出未知项。”
2. “连接 <id> 上的事件正在堆积。调查过去一小时的情况，并分别列出观察到的事实、合理的解释和缺失的证据。”
3. “追踪 FlowFile <uuid> 在 UTC 时间 09:00 至 10:00 之间经过范围 orders-intake 的情况。它去了哪里？有哪些内容你看不到？”
4. “比较我注册为 before 和 after 的流程定义。路由和队列设置有哪些变化？”
5. “起草一个属性路由器，将 status=critical 发送到 out_critical，将 standard 发送到 out_standard，其他所有情况发送到 out_unmatched。验证它并提供带标签的测试用例。”

该服务还附带三个 MCP 提示词：explain_this_flow、investigate_this_feed 和 draft_bounded_routing_flow。

6. 实际功能

工具	返回内容
get_capabilities	模式、作用域、限制、NiFi 版本及可用功能
describe_flow	有界图、参数、服务及基于固定规则的配置问题
get_flow_health	带时间戳的状态、队列、公告及带标签的假设
trace_feed	一个确切 FlowFile UUID、文件名或获准索引属性的来源时间线（最长 24 h）
inspect_unmatched	为未匹配路由提供数据的内容、近期事件及可选的元数据样本
compare_flow_snapshots	两个已注册快照之间不暴露值的结构差异
export_investigation	将调查结果导出为 JSON 或独立 HTML 报告
get_processor_catalog	用于草稿的固定版本 NiFi 2.12.0 处理器目录
validate_flow_plan	对拟议子流程进行静态检查
draft_flow	已停止的本地 NiFi 流定义，以及审查页面和回执

每个结果都采用同一封装：状态、作用域、源版本、采集时间、证据记录（源哈希及 JSON 指针）、标记为已观察、静态规则、假设或操作员备注的问题、明确列出的缺项，以及所应用的限制。

非 AI 命令行工具涵盖相同功能：nifimcp describe、investigate、report、draft、register、unregister 和 catalog。运行 nifimcp --help。要查看子流程计划示例，请运行 nifimcp draft --example attribute_router > plan.json，然后运行 nifimcp draft --plan plan.json --output ./draft。

7. 三件独立的事：调查、起草、执行

步骤	谁会向 NiFi 写入	身份	位置
调查（describe_flow、get_flow_health、trace_feed、inspect_unmatched、export_investigation）	无人	你的只读观察者证书	你的 NiFi，通过 14 个允许列表中的只读端点
起草（validate_flow_plan、draft_flow）	无人	无；不会连接 NiFi	工件目录中的本地文件
验证草稿（scripts/lab_verify_draft.py，可选）	独立的实验室 CLI	实验室自己的管理员证书，仅存在于实验室创建的一次性容器中	127.0.0.1 上的一次性 NiFi 容器，验证后删除

在记录的 Claude Code 会话中，助手使用 draft_flow 起草了一个路由器；该工具只写入文件，没有接触 NiFi。你在 evidence/host/*/lab-verification/ 中看到的导入操作，是之后由实验室 CLI 使用实验室管理员证书（CN=nifimcp-lab-admin）通过 NiFi 的上传端点，导入到容器的临时组中完成的；该容器随后已被销毁。MCP 服务没有上传、启动或部署路由，观察者身份也不具备任何写入策略。**本次发布不包含对真实 NiFi 的执行。**此功能计划作为独立、受审批控制的组件提供。

8. 边界

• 只读。 不存在启动、停止、删除、上传或部署工具。草稿是本地文件，不会触及 NiFi。
• 范围受限。 只能查看已配置的流程组；对于范围外的 ID，会直接拒绝且不会透露其是否存在。集群请求会被拒绝。
• 设有上限。 对时间窗口、事件、组件、深度、样本大小、结果大小和运行时间均设有硬性限制。
• 不读取内容。 绝不读取 FlowFile 内容。只有列入许可列表的属性值才会显示。敏感值、类似机密的字面值和常见凭据格式会被屏蔽（尽力通过模式匹配实现）。
• 没有隐式调用。 不收集遥测数据、不检查更新，也不内置模型。只调用列入许可列表的 NiFi REST 端点。
• 如实呈现证据。 绝不会将当前设置说成过去事件的原因。空的来源数据结果并不能证明数据从未存在。SEND 事件也不能证明下游已收到数据。
• 草稿仅供实验。 草稿只通过静态检查。只有单独的实验室 CLI 将其导入临时 NiFi 并运行带标签的用例后，才能确定运行时行为。
• 模型由你提供。 NiFiMCP 本身无需网络访问即可运行，但它不内置模型：MCP 宿主会提供模型，并可能将工具结果发送给模型提供方。此处尚未测试完全离线的 AI 配置。

NiFi 名称、消息和属性均视为不可信文本。MCP 宿主的模型仍会决定要说什么；请根据引用的证据核实其说法。

9. 此预览版的已知限制

有三个验收关卡处于 BLOCKED 状态，而非已通过状态，并且它们在实际使用中很重要：

关卡	对你的影响
集群	检测到集群化 NiFi 时，实时模式会拒绝操作（UNSUPPORTED_TOPOLOGY）。Bundle 模式仍可检查从任何 NiFi 导出的流程定义。安全的只读集群支持是路线图上的首要事项。
其他平台	测试套件仅在 Linux x86_64 上运行过。macOS、Windows 和 ARM 均未经测试；代码是纯 Python，很可能可以运行，但尚无人检查这些平台上的文件权限、Docker 实验环境或离线套件。
模型准确性	尚未测量任何 AI 模型使用这些工具的准确度。确定性检查结果已经过测试；助手生成的文本则没有。请将其叙述视为草稿，并查看证据链接。

此外，以下项目也未经测试：除 2.12.0 之外的 NiFi 版本（预检时会拒绝）、使用真实 NiFi 进行持有者令牌登录（仅有单元测试）、除 Claude Code 之外的 MCP 宿主，以及按自定义索引属性搜索来源数据。

10. 证据报告

export_investigation（或 nifimcp report）会生成一个 HTML 文件，其中不含脚本或外部资源，内容包括：集合与时间间隔、流程图、含类型和局限说明的发现、来源数据时间线、数据缺口、所有证据记录以及完整性哈希。

11. 资格验证方式

测试针对真实的临时 NiFi 2.12.0 容器（官方镜像，按摘要固定），使用真实 TLS 身份和策略运行。模拟测试不计为集成测试通过。

测试套件	命令
离线单元、安全性、协议和评估测试	uv run pytest
针对安全 NiFi 的实时适配器	uv run python scripts/lab_bootstrap.py --create-owned-lab 然后 uv run pytest -m integration
草稿导入和带标签的运行时用例	uv run pytest -m lab
禁用网络的离线安装	scripts/offline_acceptance_docker.sh

包含命令、版本和结果的验收记录见 docs/ACCEPTANCE.md，包含校验和的发布验证摘要见 docs/VALIDATION.md。 事件语料库评估的是固定规则，而非任何语言模型。

12. 贡献与路线图

错误报告、其他 NiFi 版本的兼容性报告，以及带有标签的新事件案例，是最有价值的贡献。请先查看入门问题、CONTRIBUTING.md 和 SECURITY.md。路线图 重点关注安全的只读集群支持和外部验证。

13. 工程支持

NiFiMCP 始终免费且开源。对于在受限网络或隔离网络中运行 NiFi 的团队，或正在积累 NiFi 专业能力的团队，维护者的公司 Federal SI 提供三项范围各不相同的服务：

• 隔离网络套件支持： 围绕免费的离线套件提供部署和配置协助、在您的环境中进行验证、操作指导和交接。
• 前沿部署工程： 提供实用的部署、集成和工作流协助，可远程或现场进行。
• 技术交流： 使用有代表性的工作流进行实践知识传授。

这些服务增加的是人员支持，而非软件功能：预览版限制仍然适用，而且尚未测试完全离线的 AI 设置。 讨论您的环境。

本项目依据 Apache License 2.0 授权。第三方声明：NOTICE、ATTRIBUTION.md。