heddle

One config, one MCP server. This YAML is a complete tool server — no Python, no boilerplate:

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

Run it:

heddle run agents/prometheus-bridge.yaml

Claude can now query Prometheus in natural language.

Current demo environment: 46 tools from 9 active configs through a single MCP connection (11 configs total, 2 excluded for incompatible transports).

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, ...

Security is always on. Every tool call passes through trust enforcement, credential brokering, and audit logging.

Example: a T1 (read-only) agent attempted a POST and was blocked:

{
  "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..."
}

The request was rejected, the violation was logged, and the hash chain links this entry to every event before and after it.

Heddle is for exposing APIs as MCP tools with real runtime controls — not just connectivity. If you only need one tool with no policy layer, hand-written FastMCP is simpler. If you need a visual workflow builder, use n8n. Heddle sits between those worlds: declarative like a workflow tool, programmable like a framework, secure by default.

How It Works

What Heddle can do today, what is partially implemented, and what is still planned:

Core Features

Declarative Tool Configs

Define tools in YAML. Heddle validates the config with Pydantic, generates typed MCP tools, and bridges HTTP with {{param}} template rendering. Cross-field validation catches bad configs before they run.

AI Config Generator

Describe what you need in plain English. A local LLM generates valid YAML, Heddle validates it against schema rules, retries on failure, and saves the result.

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

Heddle's security controls map to OWASP Agentic Top 10, NIST AI RMF, and MAESTRO. See the full threat model and security controls reference.

Starter Packs

Ready-made configs for common services. Copy one into agents/, update the base URL or credentials, validate, and run. See packs/ for full docs.

cp packs/prometheus.yaml agents/
heddle validate agents/prometheus.yaml
heddle run agents/prometheus.yaml --port 8200

Advanced Examples

These show Heddle beyond simple API bridging.

Tool Mesh

Multiple configs share a single MCP connection to Claude Desktop. The mesh launcher loads all configs, merges tools, and serves them through one stdio transport.

VRAM Orchestrator

A higher-trust agent that manages GPU memory across Ollama and a local GGUF model library, including smart loading and automatic eviction when VRAM is constrained.

Daily Ops Orchestrator

An orchestration agent that queries Prometheus, a RAG search API, and Ollama in parallel, then synthesizes a daily operations briefing with a local model.

Web Dashboard

A FastAPI + React dashboard for mesh topology, agent status, live audit stream, credential policy, and config signatures.

Clone and install

git clone https://github.com/goweft/heddle.git
cd heddle
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Validate and run a config

heddle validate agents/prometheus-bridge.yaml
heddle run agents/prometheus-bridge.yaml --port 8200

Generate a new config

heddle generate "agent that wraps the weather API at localhost:5000"

Run the full mesh

heddle mesh agents/

Security operations

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

Audit log lifecycle

Heddle's audit log at ~/.heddle/audit/audit.jsonl is a hash-chained JSONL file: every entry includes the SHA-256 of the previous entry, so a single tampered or missing line invalidates the chain from that point on. heddle audit verify walks the chain and exits non-zero on the first break.

Policy: rotate-on-break, not tolerate-and-document. A hash chain is either whole or it is broken; there is no useful middle ground. If heddle audit verify reports a break, the chain is sealed and a fresh one is started — the broken file is preserved as raw event data but is no longer the active chain. We do not carry a "known break, please ignore" exception forward, because each such exception weakens what verify is claiming and forces every consumer (CI, anomaly detection, future auditors) to special-case it.

When you'd rotate:

• heddle audit verify reports a break (most commonly from concurrent writers without file locking — fixed for new entries by commit a50e203, but historical breaks pre-dating that fix remain).

• The active log has grown unwieldy (hundreds of MB) and you want an archive cut at a known-good boundary.

• You're cutting a release and want a clean baseline chain for the next development cycle.

Manual rotation procedure (until heddle audit rotate lands; see below):

# 1. Stop the broker so no writer is active
systemctl --user stop heddle-dashboard.service   # or just kill heddle-mesh / dashboard

# 2. Capture a seal record alongside the file
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. Move the broken/old chain aside
mv audit.jsonl "audit-archive-${SEAL_DATE}.jsonl"

# 4. Restart the broker; the next event creates a fresh audit.jsonl
systemctl --user start heddle-dashboard.service

# 5. Verify the new chain
heddle audit verify        # should exit clean immediately

Archived chains are kept in the same directory (they're still useful as event history) but are not re-verified by heddle audit verify — that command only walks the active chain. To inspect a sealed file directly, jq -c '. | {ts, event, agent}' audit-archive-<date>.jsonl reads it as plain JSONL.

Existing 2026-03-29 break: development machines that ran the dashboard plus the test suite concurrently before the file-lock fix landed have a chain break around that date. There is no recovery path for the contiguous chain; rotating per the procedure above is the supported answer. Production-equivalent deployments (single broker writer, file locking present) should not see new breaks.

Tracked follow-up: heddle audit rotate is planned for v0.3. It will (a) atomically rename the active file to a timestamped archive, (b) write a .sha256 seal alongside, and (c) seed the fresh chain with a chain_seal_predecessor event whose payload references the archive's hash so that an external auditor can chain the archives together. Until then, the manual procedure above is the documented path.

Claude Desktop Integration

To expose a unified Heddle mesh to Claude Desktop (and optionally to CAS):

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

CLI Reference

Project Structure

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

Tech Stack

Python 3.11+ · FastMCP · FastAPI · Pydantic v2 · httpx · Click · SQLite · Ollama

The WEFT Ecosystem

Heddle is the trust and policy layer. The rest of the stack:

Heddle + CAS

CAS runs standalone. Heddle integration is optional and adds:

• Trust enforcement — every tool call CAS makes passes through Heddle's tier system

• Credential brokering — {{secret:key}} resolution, credentials never in config

• Audit logging — hash-chained, tamper-evident record of every workspace operation

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

License

MIT — see LICENSE.