Safer Agentic AI MCP

SaferAgenticAI MCP 服务

通过模型上下文协议，将 SaferAgenticAI 框架（规范标准 + 实施模式层）提供给编码助手。

可用平台

已发布到规范的 MCP 目录 — 可通过支持注册表的客户端或下方命令行安装：

• PyPI — saferagenticai-mcp
• 官方 MCP 注册表 — io.github.NellInc/saferagenticai-mcp

目前也正在逐步接入更广泛的 MCP 生态系统：mcp.directory、mcpservers.org、PulseMCP（通过注册表导入），以及 mcp.so。

安装

选择适合你配置的方式。

选项 1 — uvx（最快，无需手动创建 venv）

如果已安装 uv，请将 MCP 客户端指向：

uvx --from git+https://github.com/NellInc/saferagenticai-mcp saferagenticai-mcp

uv 会处理隔离并缓存安装内容。适用于 ~/.claude/mcp.json 中的单命令配置 行。

选项 2 — pipx（隔离的全局安装）

pipx install "git+https://github.com/NellInc/saferagenticai-mcp"

会全局提供 saferagenticai-mcp；使用 pipx upgrade saferagenticai-mcp 更新。

选项 3 — 手动创建 venv（从检出目录离线运行）

Homebrew / 系统 Python 会根据 PEP 668 禁止直接执行 pip install，因此，如果 你已克隆仓库并希望进行可编辑安装：

python3 -m venv research/mcp/.venv
research/mcp/.venv/bin/pip install -e research/mcp/server

生成 research/mcp/.venv/bin/saferagenticai-mcp。仓库中的模式 YAML 修改会 即时生效（可编辑模式）。

选项 4 — 从 PyPI 安装

pipx install saferagenticai-mcp
# or, with the modern uv toolchain:
uv tool install saferagenticai-mcp
# or plain pip:
pip install --user saferagenticai-mcp

为确保审计追踪的可复现性，请固定版本：pipx install saferagenticai-mcp==0.3.6。 该软件包会将 criteria-v1.json + 238 个模式 YAML 文件 + 4 个范例

• operational_heuristics.yaml 打包到 saferagenticai_mcp/_data/ 中，因此 安装 wheel 无需检出仓库即可使用。（0.3.0 wheel 早于语料扩展，仅包含 214 个模式，不含启发式规则；0.3.1 是第一个完整构建版本。）

配置（Claude Code）

添加到 ~/.claude/mcp.json（或 IDE 的 MCP 配置）中。选择与 安装选项相匹配的配置。

使用 uvx

{
  "mcpServers": {
    "saferagenticai": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NellInc/saferagenticai-mcp",
        "saferagenticai-mcp"
      ]
    }
  }
}

使用 pipx 或手动创建 venv

{
  "mcpServers": {
    "saferagenticai": {
      "command": "/absolute/path/to/saferagenticai-mcp"
    }
  }
}

对于手动创建 venv 的检出目录，绝对路径为 <repo>/research/mcp/.venv/bin/saferagenticai-mcp。

编辑后重启 Claude Code / IDE。助手首次调用工具时，服务将启动。

工具（共 12 个）

工具	输入	返回内容
list_suites	—	16 个套件及其标题和子目标数量
get_requirement	id、include_pattern	一个子目标及其 Pattern 层；若没有完全匹配项，则回退到模糊候选项
list_requirements	套件／类型／内容类型／置信度筛选条件	按筛选条件过滤的子目标列表，并附带可靠性信号
search_patterns	query、limit、verbosity	按字段加权排序的匹配项，包含 matched_in；在完整模式下还包含片段和置信度标记。字段权重：标题 10×、摘要 4×、sfr 3×、描述 2×、正文 1×
get_cross_references	id、include_inferred	指向其他条目的邻接关系
get_reverse_references	id	指向该条目的邻接关系（哪些条目引用了此 Pattern）
resolve_id	query	规范化部分 ID、slug 片段或 display_id；始终返回候选项
find_patterns_for_task	task、limit、verbosity	根据任务描述查找按套件分组的最佳 Pattern；默认为紧凑模式，以便快速筛选并降低成本
list_unreviewed	limit	列出没有 reviewed_by 的 Pattern，按置信度从低到高排序
review_stats	—	覆盖率 %、按套件和置信度划分的统计信息，以及验证问题数量
list_operational_heuristics	suite_id?、query?	从生产环境中的智能体 AI 部署经验提炼的操作启发式规则；可按套件或关键词筛选
get_operational_heuristic	id	按 ID 获取单条操作启发式规则（例如 OH::geoffrey-pattern）；返回包含原则、框架映射、设计模式和发现过程说明的完整条目

数据来源

• 规范性框架：framework/catalog/，通过生成的 assessor/src/data/criteria-v1.json 投影加载
• Pattern 层：research/mcp/suites/<SUITE>/<pattern_id>.yaml（238 个文件）
• 示例：research/mcp/exemplars/*.yaml（为四个锚点子目标提供回退数据）
• 操作启发式规则：research/mcp/operational_heuristics.yaml（14 条启发式规则）

启动时，服务会加载上述两类数据，并构建以 pattern_id 为键的内存索引。也支持通过 display_id 查找，但它可能对应多个子目标（带下划线的变体）。

冒烟测试（未安装 MCP 时）

python3 -c "
from saferagenticai_mcp.framework_loader import load_framework
idx = load_framework()
print(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')
"

版本管理

• 规范框架：遵循 criteria-v1.json 的 version 字段。
• Pattern 层：此目录填充期间为 v1-draft；审核完成后为 v1。
• 服务：采用语义化版本控制。当前版本为 0.3.6（包含框架 1.3-draft、完整的 238 个 Pattern 语料库和操作启发式规则）。请明确固定版本，以确保审计可复现。

已内置功能

• 热重载 — 服务会在每次工具调用时遍历源目录；修改内容无需重启即可生效。
• 加载时验证 — 验证必填字段、content_type 枚举值和 confidence 枚举值。无效 Pattern 会记录 WARNING，但不会导致服务失败。
• find_patterns_for_task — 将自然语言任务映射为按套件分组的最佳 Pattern。在当前规模下，无需单独的嵌入索引。
• 反向 xref 索引 — 加载时构建，并通过 get_reverse_references 查询。

尚未实现

• 身份验证 / 远程传输（仅支持 stdio）。
• 基于嵌入的语义搜索 — 目前 238 个模式下，按字段加权的关键词评分已足够；规模达到 10 倍时，嵌入才值得采用。
• mark_reviewed 写入工具 — 有意不添加。第 3 阶段的审核编辑直接通过 YAML 完成（编辑器 + git diff = 可审计）；MCP 保持只读。

更广泛的原生 Agent 架构提出了组合式方向引导、上下文包、工作区、规划、操作和验证操作。它们明确不属于当前的 0.3.6 接口。目标和兼容性计划请参阅 ../../architecture/README.md。

权威目录将当前 MCP 标识符和 slug 映射到永久需求 ID。服务器 0.3.6 保留其十二工具接口，加载生成的打包快照，验证 saai.catalog.v1，并报告共享快照哈希。

许可证

此服务器（本目录中的代码）采用 MIT 许可证 — 详见 LICENSE。

它所提供的安全框架内容（saferagenticai_mcp/_data/ 中打包的模式、规范标准和操作启发式规则）属于 SaferAgenticAI 框架，该框架在仓库根目录下以 CC-BY-4.0 许可证发布。署名：Nell Watson 和 Agentic AI Safety Community of Practice。