kushbitx-agent-mcp

A real AI-agent integration with the published @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 stdio server — the model crosses an actual agent/tool boundary, not a fixed script.

What the agent does

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.

Related MCP server: L402 Gateway

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 server — free, no API key, fully offline-capable for the model call (the KushBitx calls still hit kushbitx.com).

Quick start

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

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

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.