Heddle

MCP 工具服务器的策略与信任层。

Heddle 将声明式配置转化为 模型上下文协议 服务器
内置信任执行、凭证代理和防篡改审计日志。

查看演示 · 选择 Heddle · 当前状态 · 安全架构 · 快速开始

查看演示

**一份配置，一个 MCP 服务器。** 这份 YAML 就是一个完整的工具服务器——无需 Python，无需样板代码： ``` agent: name: prometheus-bridge version: "1.0.0" description: "Bridges Prometheus for natural language metric queries" exposes: - name: query_prometheus description: "Run a PromQL query" parameters: query: { type: string, required: true } - name: get_alerts description: "List active Prometheus alerts" http_bridge: - tool_name: query_prometheus method: GET url: "http://localhost:9090/api/v1/query" query_params: { query: query } - tool_name: get_alerts method: GET url: "http://localhost:9090/api/v1/alerts" runtime: trust_tier: 1 # enforced: GET/HEAD only, no writes, no cross-agent calls ``` 运行它： ``` heddle run agents/prometheus-bridge.yaml ``` Claude 现在可以通过自然语言查询 Prometheus。 **当前演示环境：** 通过单个 MCP 连接，来自 9 个活跃配置的 46 个工具（总计 11 个配置，2 个因传输不兼容而被排除）。 ``` daily-ops (T3): daily_briefing, system_health_check, threat_landscape gitea-api-bridge (T1): list_user_repos, list_repo_issues grafana-bridge (T1): list_dashboards, get_dashboard, list_datasources, get_alert_rules, grafana_health ai-platform (T1): health, ai_status, routing_stats, routing_costs, list_apps, detect_drift, ... ollama-bridge (T2): list_models, list_running, generate, show_model prometheus-bridge(T1): query_prometheus, query_range, get_targets, get_alerts, get_metric_names rsshub-bridge (T1): get_hacker_news, get_github_trending, search_arxiv, get_reuters_news vram-orchestrator(T3): vram_status, smart_load, smart_generate, optimize_vram, unload_model, model_library intel-rag-bridge (T2): ask_intel, get_dossier, get_trending, get_patterns, get_communities, get_stats, ... ``` **安全始终开启。** 每个工具调用都经过信任执行、凭证代理和审计日志处理。 示例：一个 T1 (只读) 代理尝试 POST 请求并被阻止： ``` { "event": "trust_violation", "agent": "reader", "trust_tier": 1, "action": "http_POST", "detail": "T1 agent cannot use POST. Allowed: ['GET', 'HEAD', 'OPTIONS']", "severity": "high", "chain_hash": "92c189e3..." } ``` 请求被拒绝，违规行为被记录，哈希链将此条目链接到之前和之后的每个事件。

为何选择 Heddle 而非...

| | **Heddle** | **手动编写的 FastMCP** | **OpenAPI 包装器生成** | **n8n / 工作流工具** | |:--:|:--:|:--:|:--:|:--:| | **新增工具** | 编写 YAML，完成 | 为每个工具编写 Python 处理程序 | 生成桩代码，然后自定义 | 拖拽节点，连接线路 | | **安全** | 信任层级、凭证代理、输入验证、配置签名、异常检测——全部内置 | 需要您自行构建 | 无 | 仅平台级认证 | | **隔离** | Docker 沙箱化：`--cap-drop=ALL`、只读根目录、PID 限制、镜像摘要固定、看门狗 | 仅进程级 | 无 | 无 | | **AI 可生成** | `heddle generate "封装 Gitea API"` → 20 秒内生成有效配置 | LLM 可编写代码但无法验证 | 非为 LLM 生成设计 | 仅视觉化，不可脚本化 | | **凭证** | `{{secret:key}}` 在运行时解析，绝不出现在配置中 | 硬编码或环境变量 | 硬编码或环境变量 | 平台凭证存储 | | **审计追踪** | 哈希链式、防篡改、异常标记、记录每次调用 | 需要您自行构建 | 无 | 仅平台日志 | | **可组合性** | 配置成为 MCP 工具，可网状组合 | 手动连接 | 独立的服务 | 工作流作用域 | Heddle 旨在将 API 暴露为具有真实运行时控制的 MCP 工具——不仅仅是连接性。如果您只需要一个没有策略层的工具，手动编写的 FastMCP 更简单。如果您需要可视化工作流构建器，请使用 n8n。Heddle 介于两者之间：像工作流工具一样声明式，像框架一样可编程，默认安全。 ## 工作原理

当前状态

Heddle 目前的功能、部分实现的功能以及仍计划中的功能： | 层 | 状态 | 详情 | |:-----:|:------:|:-------| | 配置 → MCP 服务器 | **已发布** | YAML 配置成为带 HTTP 桥接的类型化 MCP 工具 | | 信任层级 (T1–T4) | **已发布** | 运行时强制执行，违规行为被阻止并记录 | | 凭证代理 | **已发布** | 每配置的访问策略，`{{secret:key}}` 解析 | | 审计日志 | **已发布** | 哈希链式 JSON Lines，防篡改 | | 输入验证 | **已发布** | 类型检查、注入检测、速率限制 | | 访问模式注解 | **已发布** | 工具的读/写权限，T1 写入在加载和运行时被阻止 | | 升级规则 | **已发布** | 参数阈值匹配时条件性搁置待审 | | 配置签名 | **已发布** | HMAC-SHA256，篡改检测 | | 配置隔离审查 | **已发布** | AI 生成的配置暂存待审 | | AI 配置生成器 | **已发布** | 自然语言 → 通过本地 LLM 生成经验证的 YAML | | 容器沙箱化 | **已发布** | 基于 Docker 的隔离，带加固标志、镜像摘要固定、看门狗 | | 异常检测 | **已发布** | 新颖工具调用、速率限制违规、重复凭证拒绝 | | 注册表完整性 | **已发布** | 每行 HMAC 验证，`heddle reg verify` | | 网络隔离 | **部分实现** | `--network=none` 基线已发布；按主机 nftables 强制执行计划在 v0.3 | ## 核心功能 ### 声明式工具配置 在 YAML 中定义工具。Heddle 使用 Pydantic 验证配置，生成类型化 MCP 工具，并使用 `{{param}}` 模板渲染桥接 HTTP。跨字段验证可在运行前捕获错误配置。 ### AI 配置生成器 用简单英语描述您的需求。本地 LLM 生成有效的 YAML，Heddle 根据 schema 规则验证，失败时重试，并保存结果。 ``` $ heddle generate "agent that wraps the Gitea API" --model qwen3:14b ✓ Generated gitea-api-bridge.yaml (2 tools) in 20.3s ```

安全架构

Heddle 的安全控制映射到 OWASP 代理 Top 10、NIST AI RMF 和 MAESTRO。请参阅完整的[威胁模型](docs/threat-model.md)和[安全控制参考](docs/security-controls.md)。 | 控制 | 功能 | 框架 | |:-------:|:-------------|:---------:| | **信任层级** | 4 个级别（观察者 → 特权），运行时强制执行，违规行为被阻止并记录 | OWASP 代理 #3 | | **凭证代理** | 每配置的访问策略，`{{secret:key}}` 在运行时解析，永不存储在 YAML 中 | OWASP 代理 #7 | | **审计日志** | 哈希链式 JSON Lines，防篡改，5 种事件类型，密钥脱敏 | OWASP 代理 #9 | | **输入验证** | 类型检查、长度限制、注入模式检测（shell、SQL、LLM 提示） | OWASP 代理 #1 | | **配置签名** | 对所有代理配置进行 HMAC-SHA256，篡改检测 | OWASP 代理 #8 | | **配置隔离审查** | AI 生成的配置在提升前暂存待审 | OWASP 代理 #8 | | **速率限制** | 每配置每工具滑动窗口 | OWASP 代理 #4 | | **容器沙箱化** | Docker 隔离：`--cap-drop=ALL`、`--no-new-privileges`、`--read-only`、PID 限制、镜像摘要固定、看门狗超时 | OWASP 代理 #6 | | **异常检测** | 通过审计观察者标记新颖工具调用、速率限制违规、重复凭证拒绝 | OWASP 代理 #9 | | **注册表完整性** | 代理注册表每行 HMAC-SHA256，`heddle reg verify` 检测篡改 | OWASP 代理 #8 | | **升级规则** | 当参数匹配阈值或模式时，条件性搁置待审 | OWASP 代理 #3 | ## 入门套件 适用于常见服务的即用型配置。将其中一个复制到 `agents/`，更新基础 URL 或凭证，验证并运行。请参阅 [packs/](packs/) 获取完整文档。 | 套件 | 工具数 | 信任级别 | 描述 | |:-----|:------|:------|:------------| | [prometheus](packs/prometheus.yaml) | 5 | T1 只读 | PromQL 查询、目标、警报、指标发现 | | [grafana](packs/grafana.yaml) | 5 | T1 只读 | 仪表盘、数据源、警报规则 | | [git-forge](packs/git-forge.yaml) | 3 | T1 只读 | 仓库、议题（Gitea/GitHub/Forgejo） | | [ollama](packs/ollama.yaml) | 4 | T2 工作者 | 模型列表、文本生成、VRAM 状态 | | [sonarr](packs/sonarr.yaml) | 6 | T1 只读 | 电视剧库、下载队列、搜索、日历、历史记录 | | [radarr](packs/radarr.yaml) | 6 | T1 只读 | 电影库、下载队列、搜索、日历、历史记录 | ``` cp packs/prometheus.yaml agents/ heddle validate agents/prometheus.yaml heddle run agents/prometheus.yaml --port 8200 ``` ## 高级示例 这些展示了 Heddle 超越简单 API 桥接的能力。 ### 工具网状网络 多个配置共享到 Claude Desktop 的单个 MCP 连接。网状启动器加载所有配置，合并工具，并通过一个 stdio 传输提供服务。 ### VRAM 编排器 一个更高信任级别的代理，管理 Ollama 和本地 GGUF 模型库之间的 GPU 内存，包括智能加载和 VRAM 受限时的自动驱逐。 ### 日常运维编排器 一个编排代理，它并行查询 Prometheus、RAG 搜索 API 和 Ollama，然后使用本地模型合成每日运维简报。 ### 网页仪表盘 一个 FastAPI + React 仪表盘，用于展示网状拓扑、代理状态、实时审计流、凭证策略和配置签名。

快速开始

### 克隆并安装 ``` git clone https://github.com/goweft/heddle.git cd heddle python -m venv venv source venv/bin/activate pip install -e ".[dev]" ``` ### 验证并运行配置 ``` heddle validate agents/prometheus-bridge.yaml heddle run agents/prometheus-bridge.yaml --port 8200 ``` ### 生成新配置 ``` heddle generate "agent that wraps the weather API at localhost:5000" ``` ### 运行完整网状网络 ``` heddle mesh agents/ ``` ### 安全操作 ``` heddle audit show -n 20 heddle audit verify heddle sign all agents/ heddle sign verify agents/ heddle secrets policy heddle sandbox agents/my-agent.yaml ``` ### 审计日志生命周期 Heddle 位于 `~/.heddle/audit/audit.jsonl` 的审计日志是一个哈希链式 JSONL 文件：每个条目都包含前一个条目的 SHA-256 哈希值，因此任何一行被篡改或缺失都会使其后的链条失效。`heddle audit verify` 会遍历链并在遇到第一个断点时以非零状态退出。 **策略：断链即轮换，而非容忍并记录。** 哈希链要么完整，要么断裂；没有有用的中间状态。如果 `heddle audit verify` 报告断裂，该链将被封存并启动一个新的——断裂的文件作为原始事件数据保留，但不再是活动链。我们**不会**将“已知断裂，请忽略”的异常向前传递，因为每次这样的异常都会削弱 `verify` 的声明，并迫使每个消费者（CI、异常检测、未来的审计员）对其进行特殊处理。 **何时轮换：** - `heddle audit verify` 报告断裂（最常见于没有文件锁定的并发写入——新条目已通过提交 `a50e203` 修复，但早于该修复的历史断裂仍然存在）。 - 活动日志变得过于庞大（数百兆字节），您希望在一个已知良好的边界进行归档切割。 - 您正在准备发布，并希望为下一个开发周期建立一个干净的基线链。 **手动轮换程序**（直到 `heddle audit rotate` 功能上线；见下文）： ``` # 1. 停止 broker 以确保无 writer 活跃 systemctl --user stop heddle-dashboard.service # or just kill heddle-mesh / dashboard # 2. 捕获 seal record 以及文件 cd ~/.heddle/audit SEAL_DATE=$(date -u +%Y-%m-%dT%H-%M-%SZ) sha256sum audit.jsonl > "audit-archive-${SEAL_DATE}.sha256" wc -l audit.jsonl >> "audit-archive-${SEAL_DATE}.sha256" # 3. 将破损/旧的 chain 移至一边 mv audit.jsonl "audit-archive-${SEAL_DATE}.jsonl" # 4. 重启 broker；下一个事件将创建全新的 audit.jsonl systemctl --user start heddle-dashboard.service # 5. 验证新的 chain heddle audit verify # should exit clean immediately ``` 归档的链保存在同一目录中（它们作为事件历史仍然有用），但 `heddle audit verify` 不会重新验证它们——该命令仅遍历活动链。要直接检查已封存的文件，`jq -c '. | {ts, event, agent}' audit-archive-.jsonl` 将其读取为普通 JSONL。 **已有的 2026-03-29 断裂：** 在文件锁定修复提交之前，同时运行仪表盘和测试套件的开发机器在该日期附近存在链断裂。连续链没有恢复路径；按照上述程序轮换是官方支持的做法。生产等效部署（单一代理写入器，存在文件锁定）不应出现新的断裂。 **已跟踪的后续事项：** `heddle audit rotate` 已列入 v0.2 待办事项。它将 (a) 原子性地将活动文件重命名为带时间戳的归档，(b) 同时写入一个 `.sha256` 封印文件，并 (c) 用一个 `chain_seal_predecessor` 事件初始化新链，其有效载荷引用归档的哈希值，以便外部审计员可以将归档链接在一起。在此之前，上述手动程序是记录在案的路径。 ### Claude Desktop 集成 要将统一的 Heddle 网状网络暴露给 Claude Desktop（以及可选的 [CAS](https://github.com/goweft/cas)）： ``` { "mcpServers": { "heddle-mesh": { "command": "/path/to/heddle/venv/bin/heddle-mesh" } } } ``` ## CLI 参考 | 命令 | 描述 | |:--------|:------------| | `heddle run ` | 从 YAML 运行单个代理 | | `heddle validate ` | 验证配置而不运行 | | `heddle generate ""` | 从自然语言生成配置 | | `heddle mesh ` | 将所有代理作为统一网状网络启动 | | `heddle list` | 列出已注册的代理 | | `heddle registry` | 显示所有已注册的工具 | | `heddle info ` | 显示代理详细信息 | | `heddle probe ` | 在运行中的 MCP 服务器上发现工具 | | `heddle audit show` | 检查审计日志条目 | | `heddle audit verify` | 验证哈希链完整性 | | `heddle secrets` | 管理凭证代理 | | `heddle sign` | 签名和验证配置 | | `heddle quarantine` | 暂存 AI 生成的配置待审 | | `heddle sandbox ` | 显示生成的沙箱配置 | | `heddle reg verify` | 验证所有注册表行的 HMAC 完整性 | | `heddle reg resign` | 重新计算所有注册表行的 HMAC | ## 项目结构 ``` heddle/ ├── agents/ # YAML agent configs ├── packs/ # Starter pack configs ├── docs/ │ ├── threat-model.md # Threat analysis, framework-mapped │ └── security-controls.md ├── src/heddle/ │ ├── cli.py # CLI entrypoint │ ├── config/ # Pydantic schema and YAML loader │ ├── mcp/ # MCP server builder, client, registry │ ├── runtime/ # Agent runner and mesh runtime │ ├── generator/ # AI config generator and API discovery │ ├── security/ # Trust, credentials, audit, validation, │ │ # signing, sandbox, escalation │ ├── agents/ # Custom higher-level handlers │ └── web/ # Dashboard backend and frontend ├── tests/ └── pyproject.toml # Entry points: heddle, heddle-dashboard, heddle-mesh ``` ## 技术栈 Python 3.11+ · FastMCP · FastAPI · Pydantic v2 · httpx · Click · SQLite · Ollama ## WEFT 生态系统 Heddle 是信任和策略层。其余的技术栈： | 项目 | 语言 | 功能 | |---|---|---| | **[cas](https://github.com/goweft/cas)** | Go | 对话式代理外壳 — 对话生成工作空间的终端 TUI。Heddle 添加可选的信任执行和审计日志。 | | **[tenter](https://github.com/goweft/tenter)** | Python | 预发布制品扫描器 — 在发布前捕获源映射、密钥、调试制品。在 GitHub Marketplace 上架。 | | **[tenter-rs](https://github.com/goweft/tenter-rs)** | Rust | tenter v2 — 静态二进制文件，无需运行时。 | | **[unshear](https://github.com/goweft/unshear)** | Rust | 分叉差异检测器 — 揭示安全机制在分叉的代理代码库中被移除的位置。 | | **[ratine](https://github.com/goweft/ratine)** | Python | 代理记忆投毒检测器。 | | **[crocking](https://github.com/goweft/crocking)** | Python | 针对 git 仓库的 AI 作者身份检测器。 | ### 6. Heddle + CAS CAS 独立运行。Heddle 集成是可选的，并添加： - **信任执行** — CAS 进行的每个工具调用都经过 Heddle 的层级系统 - **凭证代理** — `{{secret:key}}` 解析，凭证绝不进入配置 - **审计日志** — 哈希链式、防篡改、记录每个工作空间操作 ``` { "mcpServers": { "heddle-mesh": { "command": "/path/to/heddle/venv/bin/heddle-mesh" } } } ``` ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI风险缓解, HTTP桥接, MCP工具服务器, Prometheus集成, Streamlit, YAML配置, 信任层, 信任强制, 信任管理, 凭据代理, 安全层, 安全架构, 安全策略, 审计日志, 工具服务器, 提示词设计, 模型上下文协议, 策略强制, 自动化工具生成, 访问控制, 运行时操纵, 逆向工具, 配置驱动, 配置验证, 防篡改, 验证配置