heddle (Goweft)

Heddle

The policy-and-trust layer for MCP tool servers.

Heddle turns declarative configs into Model Context Protocol servers

with trust enforcement, credential brokering, and tamper-evident audit logging built in.

See It Work · Why Heddle · Current Status · Security · Quick Start

______________________________________________________________________

See It Work

一个配置，一个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

克劳德现在可以用自然语言查询普罗米修斯。

当前演示环境： 通过单个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..."
}

请求被拒绝，违规行为被记录，哈希链将此条目链接到之前和之后的每个事件。

______________________________________________________________________

Why Heddle Instead Of...

| | 赫德尔 | 手写FastMCP | OpenAPI包装器生成器 | n8n/工作流工具 | |:--:|:--:|:--:|:--:|:--:| | 新工具 |编写YAML，完成|为每个工具编写Python处理程序|生成存根，然后进行自定义|拖动节点、接线| | 安全 |信任层、凭证代理、审计日志、输入验证、配置签名——全部内置|您自己构建|无|仅平台级身份验证| | AI可生成 | heddle generate "wrap the Gitea API" → 20s内有效的配置|LLM可以编写代码但无法验证它|不是为LLM生成而设计的|仅可视，不可编写脚本| | 凭证 | {{secret:key}} 在运行时解析，从不在config|硬编码或环境变量|硬编码或者环境变量|平台凭据存储中解析| | 审计跟踪 |哈希链，防篡改，记录每次调用|您自己构建|无|仅记录平台日志| | 可组合性 |配置成为MCP工具，将它们网格在一起|手动接线|独立服务|工作流范围|

Heddle用于将API作为具有实际运行时控件的MCP工具公开，而不仅仅是连接。如果你只需要一个没有策略层的工具，手写的FastMCP更简单。如果您需要可视化工作流构建器，请使用n8n。Heddle介于这两个世界之间：声明性的像工作流工具，可编程的像框架，默认情况下是安全的。

______________________________________________________________________

运作原理

Current Status

Heddle今天可以做什么，部分实施了什么，还有计划做什么：

核心功能

声明性工具配置

在YAML中定义工具。Heddle使用Pydantic验证配置，生成类型化的MCP工具，并将HTTP与 {{param}} 模板渲染。跨字段验证在运行前捕获错误的配置。

AI配置生成器

用简单的英语描述你需要什么。本地LLM生成有效的YAML，Heddle根据模式规则对其进行验证，失败时重试，并保存结果。

$ heddle generate "agent that wraps the Gitea API" --model qwen3:14b
✓ Generated gitea-api-bridge.yaml (2 tools) in 20.3s

Security Architecture

Heddle的安全控制映射到OWASP代理前10名、NIST AI RMF和MAESTRO。查看完整 威胁模型 和 安全控制参考.

______________________________________________________________________

入门包

共同事务的现成配置。复制一个到 agents/，更新基本URL或凭据，验证并运行。看 包装/ 查看完整文档。

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仪表板，用于网格拓扑、代理状态、实时审计流、凭证策略和配置签名。

______________________________________________________________________

Quick Start

克隆并安装

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

Claude桌面集成

将统一的Heddle网格暴露给Claude Desktop（也可以选择 CAS):

{
  "mcpServers": {
    "heddle-mesh": {
      "command": "/path/to/heddle/venv/bin/heddle-mesh"
    }
  }
}

CLI 参考

项目结构

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是信任和政策层。堆栈的其余部分：

Heddle+CAS

CAS独立运行。Heddle集成是可选的，并添加了：

• 信任执行 -CAS调用的每一个工具都通过Heddle的分级系统
• 凭证经纪 — {{secret:key}} 解析，凭据从不在配置中
• 审核日志记录 --每个工作区操作的哈希链、防篡改记录

{
  "mcpServers": {
    "heddle-mesh": {
      "command": "/path/to/heddle/venv/bin/heddle-mesh"
    }
  }
}

许可证

麻省理工学院——见 许可证.