项目定位与设计目标

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

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

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

模块组成

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

架构与请求生命周期

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

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/audit.py:1-30

典型使用模式

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

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、src/node804_mcp_toolkit/lean.py:21-37

已知使用者与适用场景

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

常见失败模式

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

See Also

• RBAC 与权限分级
• 审计日志
• 响应整形工具
• 参数规约
• TLS 配置解析

项目定位与适用范围

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

工具库的公共 API 在 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。权限不足的工具不会被注册到 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: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:48-60）。
3. 默认 Token 精简：响应仅暴露工具默认白名单内的字段，verbose=True 才返回完整负载；通过 whitelist 与 strip_keys 主动剥离 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）。

调用链路与组件协作

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

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 是一个 IntEnum，值越大权限越高，比较运算天然表达"包含"语义；ModeGate.tool() 在权限通过时把 audit 装饰器自动组合进来，再调用 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
• src/node804_mcp_toolkit/__init__.py
• src/node804_mcp_toolkit/rbac.py
• src/node804_mcp_toolkit/audit.py

概述

node804-mcp-toolkit 是面向 IT 运维场景的 MCP 服务器共享工具库，目的是把每个运维 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 类工具与启动日志共用。

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 — 项目总览与设计哲学
• node804-panos-mcp — Palo Alto 防火墙 MCP，本工具库的首个真实落地
• node804-freshservice-mcp — Freshservice 工单 MCP

目的与适用场景

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 静态检查。生产安装命令：

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）。

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 通常是 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 — 项目总览、设计哲学与下游使用方
• params.py — 共享 Pydantic 参数模式（VerboseFlag、FieldsList、Pagination、Pattern）
• lean.py — 纯函数响应整形（whitelist、strip_keys、filter_by_pattern、paginate）

Pitfall Log / 踩坑日志

项目：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