# kushbitx-agent-mcp

A real AI-agent integration with the published [`@kushbitx/sdk`](https://www.npmjs.com/package/@kushbitx/sdk), built for the kushBitxHQ/kushbitx-sdk#1 free acceptance path.

The agent is **model-directed**: an OpenAI-compatible chat-completions loop decides which tools to call and in what order. The tools are exposed through a real [MCP](https://modelcontextprotocol.io) stdio server — the model crosses an actual agent/tool boundary, not a fixed script.

## What the agent does

| Step | Tool | Result |
| --- | --- | --- |
| 1 | `kushbitx_preview_token` | Free Base token market preview |
| 2 | `kushbitx_evaluate_spend` | One stateless SpendGuard policy evaluation — **advisory only** |
| 3 | `kushbitx_get_payment_challenge` | Discovers the `token-risk` x402 challenge, **stops at HTTP 402** |

SpendGuard never executes or blocks a transaction here; enforcement belongs to the signing/execution layer. The challenge tool decodes the `PAYMENT-REQUIRED` terms and returns them **unsigned and unpaid**.

## Boundary

- Exactly three tools exist. There is no signing, payment, recovery, wallet-funding, or policy-mutation tool — `node audit.mjs` fails if one ever appears.
- No private key is requested, read, stored, logged, or committed anywhere.
- The model API key (if any) travels only in the `Authorization` header of an in-process `fetch` — never in a child-process argv or env. The MCP server child receives a curated env (`PATH`, `HOME`, `KUSHBITX_BASE_URL`).
- Committed evidence is sanitized: EVM addresses, tx hashes, bearer tokens, and JWTs are redacted (`src/sanitize.mjs`, regression-tested).

## Requirements

- Node.js 22+
- A chat-completions endpoint. Default: a local [Ollama](https://ollama.com) server — free, no API key, fully offline-capable for the model call (the KushBitx calls still hit `kushbitx.com`).

## Quick start

```bash
npm ci --ignore-scripts

# Model backend — pick one:
#   a) local Ollama (default; free, no key):
ollama pull qwen3:0.6b && ollama serve
#   b) any OpenAI-compatible endpoint:
#      export AGENT_BASE_URL=https://api.deepseek.com/v1 AGENT_MODEL=deepseek-chat AGENT_API_KEY=sk-...

npm start
```

`npm start` spawns the MCP server, lets the model drive the three checks, prints a PASS/FAIL summary, and writes sanitized evidence to `evidence/run-output.txt`. Exit code is non-zero unless all three checks pass.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `AGENT_BASE_URL` | `http://127.0.0.1:11434/v1` | OpenAI-compatible endpoint |
| `AGENT_MODEL` | `qwen3:0.6b` | Model name for that endpoint |
| `AGENT_API_KEY` | *(unset)* | Optional bearer token for the model endpoint |
| `AGENT_MAX_STEPS` | `15` | Agent-loop step cap |
| `KUSHBITX_BASE_URL` | `https://kushbitx.com` | Service base URL (used by tests for stubbing) |
| `EVIDENCE_FILE` | `evidence/run-output.txt` | Where sanitized evidence is written |
| `KUSHBITX_LIVE` | *(unset)* | Set `1` to enable live-network tests |

No variable accepts or needs a private key. If your network blocks Node's TLS to `kushbitx.com` (some Cloudflare edges do), run the calls through your own proxy — e.g. Node 24+ honors `NODE_USE_ENV_PROXY=1` with `HTTPS_PROXY`.

## Tests

```bash
npm test              # hermetic suite: unit, protocol e2e vs a stub, agent-loop, sanitizer
npm run test:live     # live checks vs kushbitx.com (needs KUSHBITX_LIVE=1; run via the launcher)
node audit.mjs        # boundary probes: tool allowlist, forbidden APIs, env hygiene, evidence
```

## Layout

```
src/server.mjs   MCP stdio server — the only tool surface
src/tools.mjs    three tool schemas + handlers over @kushbitx/sdk
src/agent.mjs    model-directed chat-completions tool loop (the agent)
src/sanitize.mjs evidence redaction
test/            unit, e2e, agent-loop, sanitizer, and gated live tests
audit.mjs        boundary probes (no signing/payment/recovery/private key)
evidence/        sanitized run output
```

## Evidence

`evidence/run-output.txt` is regenerated by `npm start` and committed sanitized — tool arguments and results are preserved with addresses and secrets redacted.

## License

Apache-2.0. Hosted KushBitx services, risk models, and non-public components are not covered by this repository's license.