# AgentStack Kit — CLI tools (`tools/bin/`)

Self-contained Node.js CLIs (Node 18+). No `npm install` required — builtins only.

**Download all:** clone or copy this `bin/` folder, or grab individual `.mjs` files from [agentstackkit.com/tools/bin/](https://agentstackkit.com/tools/bin/).

```bash
node tools/bin/<tool>.mjs --help
```

---

## Quick index

| Tool | File | Purpose |
|------|------|---------|
| mcp-probe | `mcp-probe.mjs` | Probe MCP HTTP endpoint (initialize, tools/list) |
| token-meter | `token-meter.mjs` | Estimate tokens from stdin/file |
| fetch-safe | `fetch-safe.mjs` | Bounded HTTP fetch with allowlist |
| ask-json | `ask-json.mjs` | Validate JSON against simple schema |
| crawl-map | `crawl-map.mjs` | Discover URLs from robots/sitemap/llms.txt |
| prompt-lint | `prompt-lint.mjs` | Scan prompts for risky patterns |
| session-tape | `session-tape.mjs` | Append/print JSONL session tapes |
| diff-pack | `diff-pack.mjs` | Summarize unified diffs |
| env-gate | `env-gate.mjs` | Require env vars before agent runs |
| domain-check | `domain-check.mjs` | DNS check + registrar CTAs |
| catalog-pull | `catalog-pull.mjs` | Fetch site catalog.json |
| model-router | `model-router.mjs` | cheaperllm tier hints + sample curl |
| pack-zip | `pack-zip.mjs` | Zip folder + manifest checksums |
| dual-registrar | `dual-registrar.md` | OpenProvider + Porkbun checklist |

---

## mcp-probe.mjs

Probe an MCP server over HTTP/SSE-style JSON-RPC.

```bash
node mcp-probe.mjs https://mcp.cheaperllm.com/mcp
MCP_API_KEY=sk-... node mcp-probe.mjs --key MCP_API_KEY
```

- Sends `initialize`, `tools/list`, `resources/list`
- Optional GET probe first
- Exit 1 if initialize and tools/list both fail

---

## token-meter.mjs

Estimate token count (~4 chars per token).

```bash
echo "Your prompt text" | node token-meter.mjs
node token-meter.mjs --file prompt.txt --price-per-1m 0.50
```

Output: JSON with `chars`, `words`, `estimated_tokens`, optional `estimated_cost_usd`.

---

## fetch-safe.mjs

Safe HTTP client for agents.

```bash
node fetch-safe.mjs --allow agentstackkit.com --max-bytes 100000 https://agentstackkit.com/
```

Options: `--allow`, `--max-bytes`, `--timeout`, `--method`, `--no-follow`.

Exit 2 if host blocked by allowlist.

---

## ask-json.mjs

Validate JSON against a minimal schema or emit a JSON-only prompt wrapper.

```bash
node ask-json.mjs --schema schema.json --file reply.json
cat reply.json | node ask-json.mjs --schema schema.json
node ask-json.mjs --schema schema.json --template "Extract name and email"
```

Schema supports: `type`, `required`, `properties`, `items`, `enum`.

---

## crawl-map.mjs

Build a URL map from standard discovery files.

```bash
node crawl-map.mjs https://agentstackkit.com
```

Fetches `/robots.txt`, `/sitemap.xml`, `/llms.txt`; follows robots Sitemap directives.

---

## prompt-lint.mjs

Static analysis for prompt packs.

```bash
node prompt-lint.mjs ./my-prompt.md
node prompt-lint.mjs ./packs/prompt-ops/
```

Flags: ignore-previous, exfiltrate, no-constraints, jailbreak, etc. Exit 1 on high-severity hits.

---

## session-tape.mjs

Record and replay agent tool I/O as JSONL.

```bash
node session-tape.mjs init --out run.jsonl
echo '{"tool":"fetch","ok":true}' | node session-tape.mjs record --out run.jsonl
node session-tape.mjs print run.jsonl
```

---

## diff-pack.mjs

Summarize `git diff` for review loops.

```bash
git diff | node diff-pack.mjs
git diff --cached | node diff-pack.mjs --json
```

Reports files changed, +/- lines, risk keyword hits. Exit 2 if risky.

---

## env-gate.mjs

Fail fast on missing secrets.

```bash
node env-gate.mjs CHEAPERLLM_API_KEY ONEAIPASS_TOKEN
```

Exit 1 if any var unset or empty.

---

## domain-check.mjs

DNS resolution + registrar search links.

```bash
node domain-check.mjs mybrand.io
node domain-check.mjs mybrand.io --try-agora
```

See also `dual-registrar.md` for full OpenProvider + Porkbun workflow.

---

## catalog-pull.mjs

Fetch the live AgentStack Kit catalog.

```bash
node catalog-pull.mjs
node catalog-pull.mjs --section tools
node catalog-pull.mjs --url https://agentstackkit.com/api/catalog.json
```

---

## model-router.mjs

cheaperllm routing helper (cheap vs strong tiers).

```bash
node model-router.mjs --task classify
node model-router.mjs --task plan
```

Prints recommended models and sample `curl` to `https://api.cheaperllm.com/v1/chat/completions`.

---

## pack-zip.mjs

Bundle a workflow folder.

```bash
node pack-zip.mjs ./packs/workflow-agent-loop --out ./dist/workflow.zip
```

Writes `manifest.json` with SHA-256 per file. Windows uses PowerShell `Compress-Archive`.

---

## dual-registrar.md

Markdown checklist for comparing **Agora Domains** / **TLD Bazaar** (OpenProvider) vs **Porkbun**. Includes operator-approval gate — never auto-purchase.

---

## Environment variables (common)

| Variable | Used by |
|----------|---------|
| `MCP_API_KEY` | mcp-probe |
| `CHEAPERLLM_API_KEY` | model-router sample curl |

---

## License

Part of [AgentStack Kit](https://agentstackkit.com). Use freely in agent workflows; attribution appreciated.