# https://github.com/Node804/node804-mcp-toolkit 项目说明书

生成时间：2026-06-21 01:15:06 UTC

## 目录

- [项目概览](#page-1)
- [系统架构与设计理念](#page-2)
- [核心模块详解](#page-3)
- [部署、集成与运维](#page-4)

<a id='page-1'></a>

## 项目概览

### 相关页面

相关主题：[系统架构与设计理念](#page-2), [核心模块详解](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Node804/node804-mcp-toolkit/blob/main/README.md)
- [src/node804_mcp_toolkit/__init__.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/__init__.py)
- [src/node804_mcp_toolkit/rbac.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/rbac.py)
- [src/node804_mcp_toolkit/audit.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/audit.py)
- [src/node804_mcp_toolkit/lean.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/lean.py)
- [src/node804_mcp_toolkit/params.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/params.py)
- [src/node804_mcp_toolkit/tls.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/tls.py)
</details>

# 项目概览

`node804-mcp-toolkit` 是一个面向 IT 运维场景的 Python 库，用于构建**面向令牌（token）效率**且**默认安全**的 [MCP](https://modelcontextprotocol.io) 服务器。它将多个 MCP 服务器在运维场景中需要的横切关注点（权限分级、审计日志、响应整形、TLS 配置、参数规约）抽取为统一的公共组件，从而让同一套件下的各个 MCP 工具以一致的方式暴露能力。资料来源：[README.md:1-5](README.md)

## 项目定位与设计目标

`node804-mcp-toolkit` 的核心价值在于**“一套工具库、一套行为模式”**：同一套件下的任何 MCP 在用户视角下都遵循同一组参数命名（如 `verbose`、`fields`、`limit`、`offset`、`pattern`）和同一套权限/审计语义。这种一致性显著降低了 AI 代理的学习成本和误用风险。资料来源：[README.md:55-61](README.md)

设计哲学可以归纳为四条原则：

- **Default deny（默认拒绝）**：当权限模式环境变量未设置或配置无效时，自动回退到最低权限（`READ`）；更高权限的工具根本不会注册到 MCP 服务器上，AI 客户端连“看见”都做不到。资料来源：[README.md:57-58](README.md)
- **Token-lean by default**：响应默认只暴露 AI 实际推理所需的字段；通过 `verbose=true` 显式选择完整负载。资料来源：[README.md:59](README.md)
- **Best-effort observability**：审计日志写入失败时只会向 `stderr` 输出一次告警，绝不破坏工具调用本身。资料来源：[README.md:60](README.md)
- **One toolkit, one set of patterns**：所有 MCP 共享同一套参数、模式、字段白名单规约。资料来源：[README.md:55-56](README.md)

## 模块组成

公共 API 通过 `src/node804_mcp_toolkit/__init__.py` 统一再导出，便于用户以 `from node804_mcp_toolkit import …` 方式按需引用。资料来源：[src/node804_mcp_toolkit/__init__.py:1-5](src/node804_mcp_toolkit/__init__.py)

| 模块 | 主要职责 |
|---|---|
| `rbac` | 分级权限模式（`READ` / `STANDARD` / `FULL` / `ADMIN`），通过 `gate.tool` 装饰器在注册阶段即决定工具是否对 AI 客户端可见。资料来源：[README.md:11-12](README.md) |
| `audit` | 每一次工具调用都会生成一条 JSON-lines 审计事件，包含时间戳、耗时、是否成功、敏感字段脱敏与长字符串截断。资料来源：[README.md:13-14](README.md) |
| `lean` | 纯函数式的响应整形工具：`whitelist`、`strip_keys`、`filter_by_pattern`、`paginate`，无 I/O、无全局状态，便于组合与测试。资料来源：[src/node804_mcp_toolkit/lean.py:1-18](src/node804_mcp_toolkit/lean.py) |
| `params` | 统一参数规约（`VerboseFlag`、`FieldsList`、`Pagination`、`Pattern`），强制各 MCP 在参数命名、默认值与语义上保持一致。资料来源：[src/node804_mcp_toolkit/params.py:1-15](src/node804_mcp_toolkit/params.py) |
| `tls` | 解析环境变量驱动的 TLS 配置，默认开启证书校验，可通过 `{PREFIX}_TLS_CA` 加载私有 CA，或通过 `{PREFIX}_TLS_VERIFY=false` 关闭校验并发出明显告警。资料来源：[src/node804_mcp_toolkit/tls.py:1-18](src/node804_mcp_toolkit/tls.py) |

## 架构与请求生命周期

下图描述了一次工具调用在 `ModeGate` 控制下的典型生命周期：`ModeGate` 在启动期根据环境变量解析当前权限模式，并在装饰工具时决定其是否注册到 `FastMCP`；被放行的工具调用则会被 `audit` 装饰器包装，自动写入审计日志。

```mermaid
flowchart TD
    A[启动: ModeGate.from_env] --> B{解析 PANOS_MODE / 同类 env}
    B -- 有效 --> C[确定活动 Mode]
    B -- 缺失或非法 --> D[回退为 READ<br/>并打印 stderr 告警]
    C --> E[遍历 gate.tool 装饰的工具]
    D --> E
    E --> F{active_mode ≥ required?}
    F -- 否 --> G[不注册到 MCP<br/>AI 客户端不可见]
    F -- 是 --> H[注册到 FastMCP<br/>并叠加 audit 包装器]
    H --> I[AI 客户端发起调用]
    I --> J[audit 写入 JSON-lines 事件]
    J --> K[返回白名单/分页后的精简响应]
```

资料来源：[src/node804_mcp_toolkit/rbac.py:23-70](src/node804_mcp_toolkit/rbac.py)、[src/node804_mcp_toolkit/audit.py:1-30](src/node804_mcp_toolkit/audit.py)

## 典型使用模式

最常见的集成方式是把 `ModeGate` 与 `JsonlSink` 组合使用：由 `gate.tool` 同时承担“权限门控”与“审计包装”两个职责，业务工具只关心自身的入参与返回结构。资料来源：[README.md:31-39](README.md)

```python
from mcp.server.fastmcp import FastMCP
from node804_mcp_toolkit import Mode, ModeGate, open_sink

mcp = FastMCP("panos-mcp")
sink = open_sink()
gate = ModeGate.from_env(env_var="PANOS_MODE", audit_sink=sink)

@gate.tool(mcp, required=Mode.READ)
async def get_security_rules(...): ...

@gate.tool(mcp, required=Mode.ADMIN)
async def commit(...): ...  # 仅当 PANOS_MODE=admin 时才注册
```

响应整形则借助 `lean` 模块的纯函数组合：先剥离 SDK 内部字段、按名称模糊过滤、分页切片，最后只保留白名单字段，使 AI 实际消费的内容大幅缩小。资料来源：[README.md:41-49](README.md)、[src/node804_mcp_toolkit/lean.py:21-37](src/node804_mcp_toolkit/lean.py)

## 已知使用者与适用场景

`node804-mcp-toolkit` 已被 `node804-panos-mcp`（Palo Alto 防火墙管理）与 `node804-freshservice-mcp`（Freshservice 工单系统）等 MCP 直接采用，PRTG 与 Veeam 的 MCP 已在规划中。资料来源：[README.md:67-72](README.md)

## 常见失败模式

- **环境变量未设置或拼写错误**：会回退为 `READ` 模式并向 `stderr` 打印一次性告警，所有高于 `READ` 的工具都不会被注册。资料来源：[src/node804_mcp_toolkit/rbac.py:51-58](src/node804_mcp_toolkit/rbac.py)
- **CA 文件路径不可读**：`resolve_tls_config` 会在 `stderr` 告警并回退到系统信任库，连接仍会校验证书但使用默认 CA。资料来源：[src/node804_mcp_toolkit/tls.py:19-36](src/node804_mcp_toolkit/tls.py)
- **审计日志写入失败**：仅在首次失败时打印一次告警，后续失败静默，避免审计故障拖累工具调用。资料来源：[src/node804_mcp_toolkit/audit.py:33-50](src/node804_mcp_toolkit/audit.py)

## See Also

- [RBAC 与权限分级](rbac.md)
- [审计日志](audit.md)
- [响应整形工具](lean.md)
- [参数规约](params.md)
- [TLS 配置解析](tls.md)

---

<a id='page-2'></a>

## 系统架构与设计理念

### 相关页面

相关主题：[项目概览](#page-1), [核心模块详解](#page-3), [部署、集成与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Node804/node804-mcp-toolkit/blob/main/README.md)
- [src/node804_mcp_toolkit/__init__.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/__init__.py)
- [src/node804_mcp_toolkit/rbac.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/rbac.py)
- [src/node804_mcp_toolkit/audit.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/audit.py)
- [src/node804_mcp_toolkit/lean.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/lean.py)
- [src/node804_mcp_toolkit/params.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/params.py)
- [src/node804_mcp_toolkit/tls.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/tls.py)
</details>

# 系统架构与设计理念

## 项目定位与适用范围

`node804-mcp-toolkit` 是面向 IT 运维场景构建 [MCP](https://modelcontextprotocol.io) 服务器时复用的共享工具库。它本身**不是**一个独立的 MCP 服务，而是 [node804-panos-mcp](https://github.com/Node804)、[node804-freshservice-mcp](https://github.com/Node804) 等同类项目的横向基础设施层，目的在于把权限门控、审计日志、响应整形、TLS 配置等"每个 MCP 都会重复造一遍"的横切关注点收敛成同一套实现（资料来源：[README.md:1-10]()）。

工具库的公共 API 在 [`src/node804_mcp_toolkit/__init__.py`](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/__init__.py) 中统一重新导出，调用方只需 `from node804_mcp_toolkit import Mode, ModeGate, audit, ...` 即可一次性获得全部组件（资料来源：[src/node804_mcp_toolkit/__init__.py:5-43]()）。

## 模块化结构与职责切分

工具库按照职责拆分为五个相互独立、可组合的模块：

- **`rbac`**：提供层级权限模式 `READ / STANDARD / FULL / ADMIN` 与工具注册门控装饰器 [`ModeGate.tool`](src/node804_mcp_toolkit/rbac.py)。权限不足的工具**不会被注册**到 MCP，AI 客户端无法发现它们（资料来源：[src/node804_mcp_toolkit/rbac.py:30-65]()）。
- **`audit`**：以 JSON-lines 格式记录每次工具调用，包含时间戳、UUID4 `request_id`、耗时、成功/失败、敏感键脱敏与长值截断（资料来源：[src/node804_mcp_toolkit/audit.py:30-55]()）。
- **`lean`**：纯函数式响应整形工具集 `whitelist / strip_keys / paginate / filter_by_pattern`，无 I/O、无全局状态，便于组合与单元测试（资料来源：[src/node804_mcp_toolkit/lean.py:1-15]()）。
- **`params`**：跨 MCP 复用的 Pydantic 参数模式 `VerboseFlag / FieldsList / Pagination / Pattern`，统一了 `verbose`、`fields`、`limit`、`offset`、`pattern` 这些约定（资料来源：[src/node804_mcp_toolkit/params.py:14-60]()）。
- **`tls`**：基于环境变量 `{PREFIX}_TLS_VERIFY` 与 `{PREFIX}_TLS_CA` 解析 [`TlsConfig`](src/node804_mcp_toolkit/tls.py)，默认校验为开（资料来源：[src/node804_mcp_toolkit/tls.py:50-85]()）。

## 核心设计原则

工具库遵循四项贯穿所有模块的设计原则，这些原则既是 README 中"Design philosophy"小节的复述，也是代码实现的真实动机：

1. **统一一套约定**：在任一 MCP 中学会 `verbose` / `fields` / `pagination` / `pattern` 参数语义后，在所有套件内的 MCP 中行为完全一致——避免 AI 在不同服务器间反复学习（资料来源：[src/node804_mcp_toolkit/params.py:5-13](), [README.md:54-58]()）。
2. **默认拒绝**：未设置或取值不合法的模式环境变量会自动回退至 `READ`；[`ModeGate.tool`](src/node804_mcp_toolkit/rbac.py) 在装饰阶段就跳过不达权限的工具，从根源上杜绝越权（资料来源：[src/node804_mcp_toolkit/rbac.py:48-60]()）。
3. **默认 Token 精简**：响应仅暴露工具默认白名单内的字段，`verbose=True` 才返回完整负载；通过 [`whitelist`](src/node804_mcp_toolkit/lean.py) 与 [`strip_keys`](src/node804_mcp_toolkit/lean.py) 主动剥离 SDK 内部键（如 `@uuid`、`@loc`）（资料来源：[src/node804_mcp_toolkit/lean.py:17-45](), [README.md:38-44]()）。
4. **尽力可观测**：审计 sink 写入失败仅向 stderr 警告一次，绝不中断工具调用——日志失败不能成为业务故障的导火索（资料来源：[src/node804_mcp_toolkit/audit.py:60-80]()）。

## 调用链路与组件协作

工具从装饰到执行的完整链路可由下图刻画：

```mermaid
sequenceDiagram
    participant Op as 运维
    participant Boot as MCP 启动期
    participant Gate as ModeGate
    participant Tool as 业务工具函数
    participant Sink as AuditSink
    participant Out as AI 客户端

    Op->>Boot: 导出 PANOS_MODE=admin
    Boot->>Gate: ModeGate.from_env(env_var="PANOS_MODE")
    Gate->>Gate: 解析 Mode 并预登记所有装饰工具
    Note over Gate: 权限不足的工具不调用 mcp.tool()
    Op->>Out: 调用 list_address_objects
    Out->>Tool: MCP 协议派发
    Tool->>Sink: 写入 AuditEvent (request_id, duration_ms, success)
    Sink-->>Tool: 失败仅 stderr 警告，不抛出
    Tool->>Tool: strip_keys → filter_by_pattern → paginate → whitelist
    Tool-->>Out: 返回精简响应
```

[`Mode`](src/node804_mcp_toolkit/rbac.py:40-50) 是一个 `IntEnum`，值越大权限越高，比较运算天然表达"包含"语义；`ModeGate.tool()` 在权限通过时把 [`audit`](src/node804_mcp_toolkit/audit.py) 装饰器自动组合进来，再调用 `mcp.tool()` 完成注册；当权限不足时仅在内部 `self._registry` 中标记 `registered=False`，函数依然存在于模块内但不会暴露为工具（资料来源：[src/node804_mcp_toolkit/rbac.py:96-128]()）。

## 失败模式与韧性策略

工具库刻意采用"软失败 + 显式告警"的策略，避免因配置问题导致安全策略被静默绕过：

- **环境变量缺失/非法**：`Mode.parse` 返回默认值，并通过 `warn_on_invalid=True` 打印一行列出全部合法取值的 stderr 警告（资料来源：[src/node804_mcp_toolkit/rbac.py:48-60]()）。
- **CA 路径不可读**：`resolve_tls_config` 退回到系统信任库并保留 `verify=True`，而非静默关闭校验（资料来源：[src/node804_mcp_toolkit/tls.py:60-85]()）。
- **TLS 显式关闭校验**：打印 stderr 提示，让运维侧能在日志里直接看到该危险选择（资料来源：[src/node804_mcp_toolkit/tls.py:50-70]()）。
- **审计写入失败**：通过 `_NoopSink` 与异常吞咽保证日志层不会反过来破坏工具调用本身（资料来源：[src/node804_mcp_toolkit/audit.py:55-75]()）。

这种"绝不静默"的告警约定是整套工具库的可靠性底色：所有降级行为都伴随 stderr 输出，使运维既能继续运行，又能立刻定位问题。

## See Also

- [README.md](https://github.com/Node804/node804-mcp-toolkit/blob/main/README.md)
- [src/node804_mcp_toolkit/__init__.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/__init__.py)
- [src/node804_mcp_toolkit/rbac.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/rbac.py)
- [src/node804_mcp_toolkit/audit.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/audit.py)

---

<a id='page-3'></a>

## 核心模块详解

### 相关页面

相关主题：[系统架构与设计理念](#page-2), [部署、集成与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/node804_mcp_toolkit/rbac.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/rbac.py)
- [src/node804_mcp_toolkit/audit.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/audit.py)
- [src/node804_mcp_toolkit/lean.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/lean.py)
- [src/node804_mcp_toolkit/params.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/params.py)
- [src/node804_mcp_toolkit/tls.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/tls.py)
- [src/node804_mcp_toolkit/__init__.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/__init__.py)
</details>

# 核心模块详解

## 概述

`node804-mcp-toolkit` 是面向 IT 运维场景的 [MCP](https://modelcontextprotocol.io) 服务器共享工具库，目的是把每个运维 MCP 都需要的横切关注点（权限门控、审计日志、响应塑形、TLS 配置）抽离成统一实现，避免每写一个 MCP 都重新造一遍。其核心设计哲学是「默认拒绝」「按 token 计费」「尽力可观测」——所有模块围绕「一个套件，一套约定」这一理念展开。资料来源：[README.md:1-13]()。

库对外暴露的公共 API 在 [src/node804_mcp_toolkit/__init__.py:1-44]() 中统一重导出，开发者只需 `from node804_mcp_toolkit import ...` 即可使用 `Mode`、`ModeGate`、`audit`、`open_sink`、`whitelist`、`strip_keys`、`paginate`、`filter_by_pattern`、`Pagination`、`VerboseFlag`、`Pattern`、`FieldsList`、`TlsConfig`、`resolve_tls_config` 等关键符号。

下文按「RBAC 权限门控 → 审计日志 → 响应塑形与共享参数 → TLS 配置」的顺序逐一拆解四大核心模块。

## RBAC 权限门控（rbac）

权限系统采用分层整数枚举 `Mode`，自低到高依次为 `READ=0`、`STANDARD=1`、`FULL=2`、`ADMIN=3`，整数比较天然支持层级关系：`active_mode >= Mode.FULL` 可同时让 `FULL` 与 `ADMIN` 通过。解析入口 `Mode.parse()` 接受大小写不敏感的字符串，缺失或非法值会回退到调用方传入的 `default`。资料来源：[src/node804_mcp_toolkit/rbac.py:48-67]()。

真正承担门控职责的是 `ModeGate`。它通过 `ModeGate.from_env(env_var="PANOS_MODE", audit_sink=...)` 从环境变量解析当前生效模式；若环境变量未设置或解析失败，会回退到 `READ`（默认拒绝），并向 stderr 打印一次警告。资料来源：[src/node804_mcp_toolkit/rbac.py:72-103]()。

装饰器 `gate.tool(mcp, required=Mode.READ, category=..., tool_name=..., extra_extractor=...)` 是关键入口：在装饰时即比较 `active >= required`，未通过的函数**根本不会注册到 FastMCP**，AI 客户端看不到、更无法调用；通过的函数会被 `audit` 装饰器自动包裹（当 gate 构造时传入 `audit_sink`），最终才交给 `mcp.tool()` 完成注册。资料来源：[src/node804_mcp_toolkit/rbac.py:130-165]()。`gate.summary()` 返回稳定的诊断结构，可供 `server_status` 类工具与启动日志共用。

```mermaid
flowchart TD
    A[启动: 读取 ENV 解析 Mode] --> B{active >= required?}
    B -- 否 --> C[记录到 _registry<br/>registered=False<br/>不暴露给 AI]
    B -- 是 --> D[用 audit 装饰器包裹<br/>写入 AuditEvent]
    D --> E[调用 mcp.tool 完成注册]
    C --> F[AI 客户端: 工具不可见]
    E --> G[AI 客户端: 工具可调用]
    G --> H[调用产生 JSONL 审计行]
```

## 审计日志（audit）

每个工具调用都会产出一条 JSONL 事件，结构由 `AuditEvent` 强类型定义，包含 `ts`（ISO-8601 毫秒精度）、`request_id`（UUID4 跨日志关联）、`tool`、`category`、`mode`、`args`（已脱敏）、`success`、`duration_ms`、`error`、`extra` 字段，模型 `frozen=True` 以保证不可变。资料来源：[src/node804_mcp_toolkit/audit.py:36-58]()。

`AuditSink` 是一个 `Protocol`，`enabled: bool` 与 `write(event)` 是最小契约；内置的 `JsonlSink` 负责把事件按行追加到文件，sink 写入失败只向 stderr 警告一次，绝不打断工具调用——这是「尽力可观测」的体现。`open_sink(env)` 会根据环境变量名（如 `PANOS_AUDIT_LOG`）自动实例化合适的 sink，未配置时退化为 `_NoopSink`，装饰器成本几乎为零。资料来源：[src/node804_mcp_toolkit/audit.py:60-90]()。

`sanitize_args()` 在写入前递归脱敏：任何出现在 `DEFAULT_SENSITIVE_KEYS`（如 `password`、`secret`、`token`、`authorization`、`x-api-key`）中的键无论嵌套层级一律替换为 `<redacted>`；长度超过 `DEFAULT_MAX_VALUE_LEN=2048` 的字符串会被替换为 `<elided: N chars>`，避免一次 `set_config` 撑爆审计行。资料来源：[src/node804_mcp_toolkit/audit.py:120-150]()。

## 响应塑形与共享参数（lean / params）

`lean.py` 提供四个纯函数（无 I/O、易组合）：`whitelist(data, fields)` 按白名单保留顶层键；`strip_keys(data, drop, recursive=False)` 删除 SDK 内部噪音（如 `@uuid`、`@loc`）；`paginate(items, limit, offset)` 切片并对越界 offset 宽容地返回空列表；`filter_by_pattern(items, pattern, name_field="name", use_regex=False)` 在名称字段上做大小写不敏感子串或正则过滤，缺失 name_field 的项会被剔除。资料来源：[src/node804_mcp_toolkit/lean.py:1-120]()。

为保证跨 MCP 工具参数一致，`params.py` 暴露四个 Pydantic 类型别名：`VerboseFlag`（默认 `False`，开启完整响应；典型可降低 40-70% token）、`FieldsList`（显式字段投影，优先于默认白名单与 verbose）、`Pattern`（服务端子串过滤）、`Pagination`（`limit` 默认 100、上限 1000；`offset` 默认 0）。资料来源：[src/node804_mcp_toolkit/params.py:1-100]()。任何列表型工具的形参应统一命名 `verbose / fields / pagination / pattern`，用户在一个 MCP 中学会的约定可直接复用到其他 MCP。

## TLS 配置（tls）

`TlsConfig` 是冻结的 Pydantic 模型，包含 `verify: bool`（默认 `True`）、`ca_path: Path | None`、`ca_bundle: bytes | None`，并提供 `description` 属性用于启动日志。资料来源：[src/node804_mcp_toolkit/tls.py:30-60]()。

`resolve_tls_config(env, *, prefix, warn_on_disable=True)` 按 `prefix` 隔离地读取 `{PREFIX}_TLS_VERIFY` 与 `{PREFIX}_TLS_CA`：verify 缺失/非法默认 `True`（验证开关是「显式关闭」语义，绝不静默关闭）；CA 文件读取失败时降级到系统信任库并向 stderr 警告；显式关闭 verify 时打印一次性警告使选择可见。资料来源：[src/node804_mcp_toolkit/tls.py:90-130]()。前缀隔离让 `PANOS_TLS_VERIFY` 与 `PRTG_TLS_VERIFY` 不会在共享 shell 会话里互相污染。

## See Also

- [README.md](https://github.com/Node804/node804-mcp-toolkit/blob/main/README.md) — 项目总览与设计哲学
- [`node804-panos-mcp`](https://github.com/Node804) — Palo Alto 防火墙 MCP，本工具库的首个真实落地
- [`node804-freshservice-mcp`](https://github.com/Node804) — Freshservice 工单 MCP

---

<a id='page-4'></a>

## 部署、集成与运维

### 相关页面

相关主题：[项目概览](#page-1), [核心模块详解](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Node804/node804-mcp-toolkit/blob/main/README.md)
- [src/node804_mcp_toolkit/__init__.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/__init__.py)
- [src/node804_mcp_toolkit/rbac.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/rbac.py)
- [src/node804_mcp_toolkit/audit.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/audit.py)
- [src/node804_mcp_toolkit/tls.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/tls.py)
- [src/node804_mcp_toolkit/lean.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/lean.py)
- [src/node804_mcp_toolkit/params.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/params.py)
</details>

# 部署、集成与运维

## 目的与适用场景

`node804-mcp-toolkit` 是一个面向 IT 运维场景的共享工具库，为同一套件中的多个 MCP 服务器提供一致的横切关注点：基于模式的权限网关（RBAC）、JSON-lines 审计日志、面向 token 效率的响应整形以及 TLS 配置解析。它自身不实现业务能力，而是为 Palo Alto、Freshservice、PRTG、Veeam 等下游 MCP 提供"同一套语言"——参数命名、错误处理、可观测性形态保持一致，从而让运维团队只需学习一次即可触类旁通。工具库遵循三条核心原则：默认拒绝（默认权限最低）、默认精炼（响应字段按需裁剪）、最佳努力可观测性（日志失败不影响业务调用）。

资料来源：[README.md:1-15]()、[src/node804_mcp_toolkit/__init__.py:1-39]()

## 安装与发布

工具库以 `node804-mcp-toolkit` 为名称发布在 PyPI，要求 Python 3.11 及以上，包内附带 `py.typed` 标记并通过 `mypy --strict` 静态检查。生产安装命令：

```bash
pip install node804-mcp-toolkit
```

开发模式会同步拉入测试与 lint 依赖：`pip install -e ".[dev]"`。下游 MCP 通过 `from node804_mcp_toolkit import ...` 引入公开 API，所有公共符号集中在 `__init__.py` 中重新导出，包括 `Mode`、`ModeGate`、`audit`、`open_sink`、`JsonlSink`、`AuditEvent`、`resolve_tls_config`、`TlsConfig`、`whitelist`、`strip_keys`、`filter_by_pattern`、`paginate`，以及 `params` 模块中的 `VerboseFlag`、`FieldsList`、`Pagination`、`Pattern`。这种集中导出降低了重构成本，下游只需记住一个稳定入口。

资料来源：[README.md:13-17]()、[README.md:60-66]()、[src/node804_mcp_toolkit/__init__.py:5-38]()

## 集成步骤：构建一个 MCP 服务器

集成流程分为四个阶段，全部在服务器启动时顺序执行：

1. **解析 TLS 配置**：调用 `resolve_tls_config(env, prefix="PANOS")` 读取 `PANOS_TLS_VERIFY`（默认开启）与 `PANOS_TLS_CA`（可选 PEM bundle）。当 CA 文件加载失败时降级为系统信任库并发出 stderr 警告，连接仍然尝试校验。
2. **打开审计通道**：`open_sink(env, env_var="PANOS_AUDIT_LOG")` 根据环境变量返回 `JsonlSink`（启用）或 `_NoopSink`（禁用），目录创建失败时退化为 no-op 而非抛错。
3. **建立权限网关**：`ModeGate.from_env(env_var="PANOS_MODE", audit_sink=sink)` 解析当前模式，未设置或非法值回落至 `READ` 并打印一次性警告。
4. **声明工具**：通过 `@gate.tool(mcp, required=Mode.READ)` 装饰器注册工具；未达模式的工具仅记录在 `_registry` 中而不会进入 MCP 注册表，AI 客户端"看不见也调不到"——这是典型的默认拒绝（default deny）。

```python
from node804_mcp_toolkit import Mode, ModeGate, open_sink, resolve_tls_config

tls = resolve_tls_config(dict(os.environ), prefix="PANOS")
sink = open_sink(env=dict(os.environ), env_var="PANOS_AUDIT_LOG")
gate = ModeGate.from_env(env_var="PANOS_MODE", audit_sink=sink)

@gate.tool(mcp, required=Mode.READ)
async def get_security_rules(...): ...

@gate.tool(mcp, required=Mode.ADMIN)
async def commit(...): ...  # PANOS_MODE != admin 时不会注册
```

业务工具内部使用 `whitelist`、`strip_keys`、`filter_by_pattern`、`paginate` 这组纯函数对响应进行整形，再序列化为 JSON 返回给 MCP 客户端，整个链路保持 token 友好。

资料来源：[src/node804_mcp_toolkit/tls.py:88-129]()、[src/node804_mcp_toolkit/audit.py:113-140]()、[src/node804_mcp_toolkit/rbac.py:64-99]()、[src/node804_mcp_toolkit/lean.py:1-40]()

## 配置矩阵

下表汇总了部署时常用的环境变量及其默认行为。所有变量均可缺省，缺省或非法值都会触发 fail-safe 降级。

| 环境变量 | 默认值 | 用途 | 失效行为 |
|---|---|---|---|
| `<PREFIX>_MODE` | `read` | 权限模式：`read`/`standard`/`full`/`admin` | 未识别值回落 `READ`，stderr 警告一次 |
| `<PREFIX>_TLS_VERIFY` | `true` | 是否校验对端证书 | 未识别值返回 `None`，按 true 处理 |
| `<PREFIX>_TLS_CA` | 无 | 自定义 PEM CA bundle 路径 | 读取失败回落系统信任库并告警 |
| `<PREFIX>_AUDIT_LOG` | 未设置 | JSON-lines 审计日志路径 | 未设置或目录不可写时退化为 no-op |

`PREFIX` 通常是 MCP 简称，如 `PANOS`、`FRESHSERVICE`、`PRTG`，从而在同一台主机上共存多个套件实例而不互相干扰。

资料来源：[src/node804_mcp_toolkit/rbac.py:37-44]()、[src/node804_mcp_toolkit/tls.py:54-82]()、[src/node804_mcp_toolkit/audit.py:113-140]()

## 运维观测与常见故障

工具库的设计原则之一是"尽力而为的可观测性"：`JsonlSink` 写入失败时仅在首次向 stderr 输出警告并静默后续错误，绝不中断业务调用。`ModeGate.summary()` 返回稳定的字典结构，可被下游 `server_status` 工具直接消费，包含 `mode`、`env_var`、`tools_total`、`tools_enabled`、`tools_blocked`、启用与被屏蔽的工具名列表，以及 `audit` 状态字段；`describe_tls()` 给出单行人类可读的 TLS 摘要，便于启动日志核查。

常见故障模式与处置：

- **环境变量拼写错误**：`PANOS_MODE=write` 不会被识别为合法模式，自动回落 `READ` 并发出 `WARNING`，需检查启动日志确认告警已被看到。
- **TLS CA 路径不可读**：`PANOS_TLS_CA=/missing.pem` 触发 `OSError`，回退到系统信任库，TLS 校验仍然开启，只是信任链不同。
- **审计目录无写权限**：`JsonlSink` 构造或写入失败时降级为 `_NoopSink`，后续调用不再尝试落盘，需要排查路径权限或磁盘配额。
- **工具超出当前模式**：被装饰的工具不会出现在 MCP 协议握手列表中，从客户端视角看就是"该工具不存在"，避免越权调用。

资料来源：[src/node804_mcp_toolkit/audit.py:90-110]()、[src/node804_mcp_toolkit/rbac.py:154-181]()、[src/node804_mcp_toolkit/tls.py:97-129]()

## See Also

- [README.md](https://github.com/Node804/node804-mcp-toolkit/blob/main/README.md) — 项目总览、设计哲学与下游使用方
- [params.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/params.py) — 共享 Pydantic 参数模式（`VerboseFlag`、`FieldsList`、`Pagination`、`Pattern`）
- [lean.py](https://github.com/Node804/node804-mcp-toolkit/blob/main/src/node804_mcp_toolkit/lean.py) — 纯函数响应整形（`whitelist`、`strip_keys`、`filter_by_pattern`、`paginate`）

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：Node804/node804-mcp-toolkit

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Node804/node804-mcp-toolkit | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Node804/node804-mcp-toolkit | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Node804/node804-mcp-toolkit | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Node804/node804-mcp-toolkit | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Node804/node804-mcp-toolkit | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Node804/node804-mcp-toolkit | release_recency=unknown

<!-- canonical_name: Node804/node804-mcp-toolkit; human_manual_source: deepwiki_human_wiki -->