# HuGR_Tools

**630 tools · 37 deployable workers · one frozen kernel · 8,538 tests passing · 1,928 credential-gated integration tests skipped in CI · 0 failing.**

A monorepo of MCP toolkits for Cloudflare Workers, built on a shared `@hugr/kernel`. Each toolkit is an independent JSON-RPC 2.0 server that plugs into any MCP host over HTTP.

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/HumanGuardrail/HuGR_Tools/actions/workflows/ci.yml/badge.svg)](https://github.com/HumanGuardrail/HuGR_Tools/actions/workflows/ci.yml)

---

## What is this?

A modular monolith of MCP tool servers. Provider packages share a single kernel (`@hugr/kernel`) that handles HTTP, auth, rate limiting, the error taxonomy, and JSON-RPC dispatch — written once, frozen. Each toolkit deploys as a standalone Cloudflare Worker and versions independently.

The workspace holds 39 packages:

- **37 deployable Cloudflare Workers** — 630 tools total:
  - 6 SaaS providers: cloudflare (84), stripe (50), vercel (40), sentry (27), pagerduty (34), supabase (35)
  - 26 AWS surface packages: 282 tools across the AWS API
  - 5 Datadog packages: apm, core, dashboards, logs, monitors — 78 tools
- **`@hugr/kernel`** — the shared contract every worker builds on
- **1 internal package** — `shared` (Datadog family internals) — plus a `ci/` helper directory.

Architecture: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

---

## Flagship tools — 25 composite tools

Most of the 630 are focused single-purpose primitives (typed, validated, fail-closed access to one provider endpoint — the baseline an agent needs). These 25 are the composite ones: **one call fans out to several provider APIs and correlates them into a named verdict** — `PROBABLE_CAUSE`, `TRUE_POSITIVE` / `FALSE_POSITIVE`, `GO` / `NO_GO`, `P1` / `P2` / `P3` — the output a senior analyst would produce, not a wrapped endpoint.

Each was selected by reading its **handler implementation**, not its description — every one below was confirmed to actually fan out and correlate. Each links to its handler and has a dedicated test suite beside it.

**Security, threat & access forensics**

| Tool | What one call does |
|---|---|
| [`cf_campaign_ioc_investigation`](packages/cloudflare/src/tools/tl_campaign_ioc_investigation/handler.ts) | Extracts IOCs from a threat campaign, enriches each via domain/IP intel, then cross-references them against *your own* attack surface to score exposure; clusters by ASN to reveal shared campaign infrastructure |
| [`cf_strategic_security_report`](packages/cloudflare/src/tools/tl_strategic_security_report/handler.ts) | Correlates active security insights against observed threat campaigns (a threat-alignment score) and computes intel coverage-gaps into a CISO briefing |
| [`cf_dlp_violation_triage`](packages/cloudflare/src/tools/tl_dlp_violation_triage/handler.ts) | A weighted false-positive model plus a two-stage verdict that overrides `TRUE_POSITIVE`→`INCONCLUSIVE` when corroborating evidence (source device, active gateway rule) is absent |
| [`cf_client_side_threat_analysis`](packages/cloudflare/src/tools/tl_client_side_threat_analysis/handler.ts) | Scans a PageShield script's outbound connections for exfiltration signatures; escalates to Magecart when the script sits on a checkout/payment page |
| [`aws_iam_role_permission_blast_radius`](packages/aws-iam/src/tools/tl_role_permission_blast_radius/handler.ts) | Fans out ~40 IAM calls (role + inline/attached policies, every version) to score privilege-escalation exposure and flag "any principal can assume me" trust misconfig |
| [`supabase_network_threat_view`](packages/supabase/src/tools/tl_network_threat_view/handler.ts) | Real CIDR subnet arithmetic to test each active IP ban against the allowlist, surfacing ban∩allowlist overlaps as a misconfiguration signal |

**Incident response, RCA & observability**

| Tool | What one call does |
|---|---|
| [`root_cause`](packages/core/src/tools/rootCause.ts) (datadog) | Correlates 8 Datadog sources (events, metrics, spans, logs, monitors, SLOs, incidents, deps) in parallel around a timestamp; temporal RCA with graceful degradation per source |
| [`incident_timeline`](packages/core/src/tools/incidentTimeline.ts) (datadog) | Merges 5 sources into one T+0 timeline, auto-detecting the incident start and deriving metric-shift / log-spike signals rather than dumping raw events |
| [`deploy_impact`](packages/core/src/tools/deployImpact.ts) (datadog) | Equal before/after windows classify each metric `REGRESSION` / `IMPROVEMENT` / `STABLE`, with a confound guard that warns on other deploys inside the window |
| [`forecast_risk`](packages/core/src/tools/forecastRisk.ts) (datadog) | Extrapolates metric trend + SLO error-budget burn to project *when* a service breaches ("error_rate hits 5% in ~18h") — the only forward-looking tool |
| [`pd_deployment_rca`](packages/pagerduty/src/tools/tl_deployment_rca/handler.ts) | Ranks change events by temporal proximity to an incident and scores against an MTTR baseline into `PROBABLE_CAUSE` / `POSSIBLE_CAUSE` |
| [`pd_performance_report`](packages/pagerduty/src/tools/tl_performance_report/handler.ts) | Multi-dimensional (service / team / responder) analytics with >2×-median outlier detection and responder-burnout flags |
| [`cf_provider_outage_diagnosis`](packages/cloudflare/src/tools/tl_provider_outage_diagnosis/handler.ts) | Builds a per-provider outage timeline through AI Gateway and computes a recovery verdict (`RECOVERED` / `PARTIAL` / `STILL_DEGRADED`) from pre-vs-post error rates |
| [`aws_ec2_instance_health_triage`](packages/aws-ec2/src/tools/tl_instance_health_triage/handler.ts) | Joins instance + status checks + EBS volumes + security groups into one health verdict — failed checks, unencrypted volumes, SSH/RDP open to `0.0.0.0/0` |
| [`sentry_issue_triage_and_forensics`](packages/sentry/src/tools/tl_issue_triage_and_forensics/handler.ts) | Adaptive drill-down into a single event: in-app stack frames, per-frame local variables, the breadcrumb trail, request/user context |
| [`sentry_replay_evidence_harvest`](packages/sentry/src/tools/tl_replay_evidence_harvest/handler.ts) | Matches a session replay's error IDs to Issue groups and grades escalation `P1` / `P2` / `P3` — error-to-session forensics |

**Billing, fraud & tax**

| Tool | What one call does |
|---|---|
| [`stripe_quarterly_tax_reconciliation`](packages/stripe/src/tools/tl_quarterly_tax_reconciliation/handler.ts) | Reconciles a quarter of invoices against tax registrations per jurisdiction, normalizing multi-currency VAT via FX; flags unregistered-with-liability |
| [`stripe_fraud_coverage_gap_analysis`](packages/stripe/src/tools/tl_fraud_coverage_gap_analysis/handler.ts) | Joins charges × early-fraud-warnings × disputes to score "disputed-without-EFW" gaps against Visa's real 0.1% monitoring threshold |
| [`stripe_failed_payment_recovery`](packages/stripe/src/tools/tl_failed_payment_recovery/handler.ts) | Derives recovery viability (`FULL` / `PARTIAL` / `NO` via credit-balance math) crossed with the dunning ladder and card-expiry detection |
| [`stripe_transaction_dispute_evidence_chain`](packages/stripe/src/tools/tl_transaction_dispute_evidence_chain/handler.ts) | Adaptive forensic walk of the Issuing dispute↔transaction↔authorization chain; flags force-capture when the authorization was declined |

**Release, deploy & on-call gating**

| Tool | What one call does |
|---|---|
| [`vercel_check_gated_promotion`](packages/vercel/src/tools/tl_check_gated_promotion/handler.ts) | Aggregates blocking CI checks + alias-swap safety into a `PASS` / `BLOCK` production-promotion verdict with a typed blocker list |
| [`vercel_canary_health_snapshot`](packages/vercel/src/tools/tl_canary_health_snapshot/handler.ts) | Resolves the canary from the active rolling-release stage and computes an adaptive gate (`SPIKE_TRIAGE` / `STAGE_APPROVAL`) with next-stage eligibility |
| [`pd_oncall_program_health_audit`](packages/pagerduty/src/tools/tl_oncall_program_health_audit/handler.ts) | Models rotation burden (hours per engineer across rotation layers), flags anyone >2× median, and scores escalation-policy compliance |

**Cloud cost & threat intel**

| Tool | What one call does |
|---|---|
| [`aws_rds_db_cost_optimizer`](packages/aws-rds/src/tools/tl_db_cost_optimizer/handler.ts) | Correlates instances × reserved instances to recommend right-sizing (Graviton `r5`→`r6g`, `gp2`→`gp3`, previous-gen) and map RI coverage gaps by class |
| [`cf_weekly_threat_landscape`](packages/cloudflare/src/tools/tl_weekly_threat_landscape/handler.ts) | Computes week-over-week Radar deltas client-side (doubles the window, splits the series — no prior-week API exists) and merges BGP hijack / route-leak events into one report |

The kernel itself is the other thing worth reading: a 3-tier auth verifier chain (RS256 → HMAC → fail-closed introspection, bearer tokens SHA-256-hashed before caching — [`hugr-auth.ts`](packages/kernel/src/identity/hugr-auth.ts), ~1,400 lines of dedicated tests), distributed rate limiting over Durable Objects with deterministic sharding and anti-cascade fail-open ([`rate-limit.ts`](packages/kernel/src/mcp/rate-limit.ts)), and the full dispatch pipeline — CORS → pre-auth gate → auth → tier check → rate limit → Zod validation → provider build → format → audit ([`server.ts`](packages/kernel/src/mcp/server.ts)).

---

## Auth & credentials

- **Fail-closed PAT introspection.** Every worker validates the caller's PAT against an external introspection endpoint on each request. If that endpoint is unreachable, auth fails closed. Scopes are derived from the caller's plan server-side — never read from the token.
- **BYOK, zero stored secrets.** Workers hold no provider credentials. The caller supplies provider creds via per-request headers; when they are absent, the call fails closed.

### Self-hosting (no external auth service needed)

Platform auth is a pluggable `IdentityProvider`, and the bundled one resolves its mode from env, strongest-first: **RS256 → HMAC → introspection** ([`hugr-auth.ts`](packages/kernel/src/identity/hugr-auth.ts)). The introspection mode targets a multi-tenant deployment; a self-hoster needs none of it:

```bash
# 1. Set one secret on your worker (local HS256 verification, no network call)
wrangler secret put HUGR_INLINE_HMAC_SECRET

# 2. Mint your own tokens against it
tsx scripts/auth/mint-token.ts --alg HS256 --secret <secret> \
    --sub me --plan pro --scopes hugr:tools --ttl 3600

# Or asymmetric: generate a keypair, keep the private key, give workers only the public one
tsx scripts/auth/mint-token.ts gen-keypair --out-dir ./keys   # then set HUGR_INLINE_RS256_PUBLIC_KEY
```

Don't run a deployed worker with no auth at all: BYOK means callers bring their own provider keys, but an open worker on a public URL is a free proxy on *your* Cloudflare account. One HMAC secret is the floor.

---

## Deploy

Each toolkit is a standard Cloudflare Worker. Run one locally with `wrangler dev`, or deploy to your own account with `wrangler deploy --env <env>`. Fill in `account_id` and your auth config (the introspect endpoint, or `HUGR_INLINE_HMAC_SECRET` for local HS256 verification — see below) in each `packages/<pkg>/wrangler.toml`; the committed values are placeholders.

---

## Testing & evidence

The 37 workers was tested to exhaustion before release, and every claim traces to a dated record in this repo. Raw JSON for bench runs lives in `scripts/load-test/results/`.

| What was tested | Record |
|---|---|
| Unit + integration — 8,538 passing, 1,928 credential-gated skips, 0 failing (v1.0.0 CI) | [CI run 27887641262](https://github.com/HumanGuardrail/HuGR_Tools/actions/runs/27887641262) |
| Adversarial load, 20 scenarios (`bench:evil`) — e.g. 100,000 requests, 0 errors | [`docs/architecture/BENCHMARKS.md`](docs/architecture/BENCHMARKS.md) |
| Fault injection, 8 chaos scenarios (`bench:chaos`) — provider chaos, state corruption, memory pressure, clock skew, slow-network, schema floods | [`docs/architecture/CHAOS_BENCHMARKS.md`](docs/architecture/CHAOS_BENCHMARKS.md) |
| MCP spec conformance, 10 scenarios incl. the official SDK `Client` end-to-end (`bench:mcp`) | [`docs/architecture/MCP_CONFORMANCE.md`](docs/architecture/MCP_CONFORMANCE.md) |
| Mutation testing over kernel + shared, Stryker (`bench:mutation`) — full kill/survive breakdown published, including the unflattering rows | [`docs/architecture/MUTATION_BENCHMARKS.md`](docs/architecture/MUTATION_BENCHMARKS.md) |
| Also on record: security, observability, quality and supply-chain benches; Node 18 compat | [`docs/architecture/`](docs/architecture/) |

These records are point-in-time (each is dated). Provider APIs drift; the credential-gated integration suites re-verify against live APIs whenever run with real credentials.

---

## Quick start

```bash
# 1. Clone
git clone https://github.com/HumanGuardrail/HuGR_Tools.git
cd HuGR_Tools

# 2. Install (pnpm workspace)
pnpm install

# 3. Run all tests
pnpm -r test

# 4. Typecheck
pnpm -r typecheck

# 5. Run one package in dev mode (example: cloudflare)
pnpm -F @hugr/cloudflare dev
```

Requirements: Node >= 20 for development (CI runs Node 20; deploys use Node 22, required by wrangler 4). Worker code itself keeps Node 18 API compatibility, enforced by `check:node18` — that is why the workspace `engines` floor reads `>=18.17`.

---

## Per-package index

Each package has its own `README.md` with its full tool table, BYOK credential headers, and install snippet.

| Package | Tools | Description |
|---|---:|---|
| [kernel](packages/kernel/README.md) | — | Shared infrastructure: ports, http, formatter, mcp, tool, identity |
| [cloudflare](packages/cloudflare/README.md) | 84 | Cloudflare platform — zones, DNS, WAF, Workers, R2, analytics |
| [stripe](packages/stripe/README.md) | 50 | Stripe payments, subscriptions, billing, disputes, payouts |
| [vercel](packages/vercel/README.md) | 40 | Vercel deployments, domains, projects, logs, analytics |
| [sentry](packages/sentry/README.md) | 27 | Sentry error tracking, issues, releases, performance |
| [pagerduty](packages/pagerduty/README.md) | 34 | PagerDuty incidents, alerts, schedules, escalations |
| [supabase](packages/supabase/README.md) | 35 | Supabase projects, databases, auth (GoTrue), edge functions |
| [aws-ai](packages/aws-ai/README.md) | 7 | Bedrock + BedrockAgent |
| [aws-audit](packages/aws-audit/README.md) | 13 | CloudTrail + Config |
| [aws-backup](packages/aws-backup/README.md) | 6 | Backup + FSx + Glacier |
| [aws-batch](packages/aws-batch/README.md) | 6 | AWS Batch |
| [aws-cache](packages/aws-cache/README.md) | 6 | ElastiCache + Redshift |
| [aws-cicd-ext](packages/aws-cicd-ext/README.md) | 6 | CodeArtifact + CodeCommit + CodeDeploy + Proton |
| [aws-cloudwatch](packages/aws-cloudwatch/README.md) | 14 | CloudWatch + CloudWatchLogs |
| [aws-containers](packages/aws-containers/README.md) | 9 | ECS + EKS |
| [aws-cost](packages/aws-cost/README.md) | 11 | CostExplorer + Organizations |
| [aws-data](packages/aws-data/README.md) | 10 | Athena + EMR + Glue |
| [aws-devops](packages/aws-devops/README.md) | 18 | AutoScaling + CodeBuild + CodePipeline + ECR + SSM + X-Ray |
| [aws-dynamodb](packages/aws-dynamodb/README.md) | 13 | DynamoDB |
| [aws-ec2](packages/aws-ec2/README.md) | 17 | EC2 |
| [aws-iam](packages/aws-iam/README.md) | 11 | IAM |
| [aws-lambda](packages/aws-lambda/README.md) | 15 | Lambda |
| [aws-management](packages/aws-management/README.md) | 8 | CloudFormation + ServiceCatalog + Support |
| [aws-messaging](packages/aws-messaging/README.md) | 15 | EventBridge + SFN + SNS + SQS |
| [aws-ml](packages/aws-ml/README.md) | 6 | SageMaker |
| [aws-network-ext](packages/aws-network-ext/README.md) | 5 | DirectConnect + GlobalAccelerator + EC2 |
| [aws-networking](packages/aws-networking/README.md) | 16 | APIGateway + CloudFront + ELB + Route53 |
| [aws-rds](packages/aws-rds/README.md) | 12 | RDS |
| [aws-s3](packages/aws-s3/README.md) | 16 | S3 |
| [aws-security](packages/aws-security/README.md) | 19 | GuardDuty + Inspector + KMS + SecretsManager + SecurityHub + WAFv2 |
| [aws-security-ext](packages/aws-security-ext/README.md) | 8 | Detective + FMS + Macie2 + SSO Admin |
| [aws-storage](packages/aws-storage/README.md) | 7 | EFS |
| [aws-streaming](packages/aws-streaming/README.md) | 8 | Kafka + Kinesis + MQ |
| [apm](packages/apm/README.md) | 17 | Datadog APM |
| [core](packages/core/README.md) | 15 | Datadog core metrics and infrastructure |
| [dashboards](packages/dashboards/README.md) | 12 | Datadog dashboards |
| [logs](packages/logs/README.md) | 18 | Datadog logs |
| [monitors](packages/monitors/README.md) | 16 | Datadog monitors and alerts |

---

## Status & honest assessment

**As a product.** This space is commoditizing — major providers now ship official MCP servers, so a third-party 630-tool suite carries a real, ongoing maintenance surface. Each worker deploys to your own Cloudflare account; how you isolate environments (separate accounts vs. name suffixes) is your call.

**As an engineering artifact.** The notable part is the structure: 37 independently-deployable workers sharing one frozen kernel contract (HTTP, auth, rate limiting, error taxonomy, JSON-RPC dispatch — written once); a BYOK fail-closed credential model; an OpenAPI→MCP codegen step that generated the AWS surface; and the test / mutation / chaos / leak-hunt discipline behind it.

**Built by an agent fleet.** This toolkit was constructed by an orchestrated fleet of AI coding agents, each working a disjoint, file-scoped slice against the frozen kernel contract — which is exactly what made a parallel, machine-driven build tractable. Stated plainly rather than passed off as hand-crafted; the interesting engineering is the structure that let it work.

Test figures are from the v1.0.0 CI run on `main` (GitHub Actions run 27887641262, 2026-06-20): 8,538 passing, 1,928 skipped, 0 failing (kernel alone: 514). The skips are credential-gated provider-integration suites (`describe.skipIf(!HAS_CREDS)`) that run only with real provider credentials.

---

## Reference

| Document | Purpose |
|---|---|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | High-level navigation hub — start here |
| [`docs/architecture/ADR-001-modular-monolith.md`](docs/architecture/ADR-001-modular-monolith.md) | Why modular monolith + shared kernel |
| [`docs/architecture/KERNEL_SPEC.md`](docs/architecture/KERNEL_SPEC.md) | Kernel API contracts (frozen) |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Branching, commit format, ABORT rules, DoD |
| [`CHANGELOG.md`](CHANGELOG.md) | Version history |

---

## License

[MIT](LICENSE) — Copyright 2026 Gustavo Schneiter / HuGR