# kushbitx-mcp-agent

An **MCP-compatible AI agent integration** for [`@kushbitx/sdk`](https://www.npmjs.com/package/@kushbitx/sdk) — built for the [KushBitx bounty issue #1](https://github.com/kushBitxHQ/kushbitx-sdk/issues/1).

The agent exposes three narrow, read-only tools over the Model Context Protocol and drives them through a real MCP client. It performs the free token preview, one SpendGuard policy evaluation, and one x402 payment-challenge discovery **without signing or paying anything**.

## Security posture

| Guarantee | How it is enforced |
| --- | --- |
| No private key is ever requested, read, stored, or logged | No key argument exists in any tool schema; `viem` / signers are not dependencies |
| No payment is ever signed or executed | The x402 tool stops at the HTTP 402 challenge and returns it verbatim |
| No signing, payment, recovery, or policy-mutation tool is exposed | Only three read-only tools are registered |
| SpendGuard is never claimed to enforce anything | Every description and the run summary state the decision is **advisory** and that enforcement belongs to the signing/execution layer |
| Unexpected responses surface as failures | Any non-402 status or missing challenge throws and is reported with `isError: true`, never as a silent success |

## Tools exposed

| Tool | Free? | Purpose |
| --- | --- | --- |
| `kushbitx_preview_token` | ✅ | Inspect basic Base token market data for an address |
| `kushbitx_evaluate_spend` | ✅ | Evaluate a proposed USDC spend against a policy **before** money moves |
| `kushbitx_get_payment_challenge` | ✅ | Discover the x402 payment requirements for a paid service (stops at 402) |

## Requirements

- Node.js **22 or later** (tested on v22.23.1)
- No API key, no wallet, no funds required for the free acceptance path

## Setup

```bash
git clone <this-repo>
cd kushbitx-mcp-agent
npm install
```

## Run

```bash
node agent.mjs
```

This spawns the MCP server over stdio, lists its tools, then runs the three acceptance steps through the MCP protocol.

### Using the server from another MCP host

```jsonc
// e.g. Claude Desktop / Cursor / any MCP-compatible client
{
  "mcpServers": {
    "kushbitx": {
      "command": "node",
      "args": ["/absolute/path/to/kushbitx-mcp-agent/src/server.mjs"]
    }
  }
}
```

## Verified output

Captured from a real run on 2026-09-19 (full log: [`evidence/run-output.txt`](evidence/run-output.txt)):

```
====================================================================
MCP handshake — tools exposed by the server
====================================================================
- kushbitx_preview_token
    Free. Inspect basic Base token market data for an address.
- kushbitx_evaluate_spend
    Free preview. Evaluate a proposed USDC spend against a policy BEFORE any money moves.
- kushbitx_get_payment_challenge
    Discover the x402 payment requirements for a paid KushBitx service.

====================================================================
Step 2 — SpendGuard evaluation (0.25 USDC)
====================================================================
{
  "version": "spendguard-preview-1",
  "agentId": "kushbitx-demo-agent",
  "amount": "0.25",
  "decision": "HUMAN_APPROVAL",
  "findings": [
    { "code": "RISK_REVIEW", "message": "Risk evidence is not a trusted ALLOW signal." }
  ],
  "advisory": true,
  "executionAuthorized": false,
  "note": "This stateless preview does not hold keys, execute a payment or prove that
           caller-supplied policy and risk inputs are trusted. Enforce the decision in a
           separate signer or approval service."
}

====================================================================
Step 3 — x402 payment challenge discovery (no signing, no payment)
====================================================================
{
  "service": "token-risk",
  "path": "/api/token-risk",
  "challenge": {
    "x402Version": 2,
    "error": "Payment required",
    "accepts": [
      {
        "scheme": "exact",
        "network": "eip155:8453",
        "amount": "250000",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "payTo": "0x0d68028d06af13379C872FEE032568B4Be712f22",
        "maxTimeoutSeconds": 300,
        "extra": { "name": "USD Coin", "version": "2" }
      }
    ]
  }
}

====================================================================
Summary
====================================================================
1. token preview      : PASS
2. SpendGuard evaluate: PASS
3. x402 challenge     : PASS

No private key was requested, read, or stored. No payment was signed.
SpendGuard output is advisory; enforcement belongs to the signing layer.
```

The x402 challenge above is read-only evidence: `amount: "250000"` is 0.25 USDC in 6-decimal base units on Base (`eip155:8453`). Nothing was signed and nothing was paid.

## Notes and observations

- **Upstream flakiness on the free preview.** During testing on 2026-09-19 the `POST /api/token-preview` endpoint returned HTTP `503` with `{"error":"Market data is temporarily unavailable. Please try again shortly; the preview is free."}` intermittently — roughly one call in three — while `/api/spendguard/evaluate` and `/api/token-risk` stayed healthy. `src/retry.mjs` retries only these transient signals with bounded attempts, and a genuine failure is still surfaced as an error rather than a silent success.
- **Schema discovery.** `evaluateSpend` validates progressively and reveals required fields one at a time. The accepted shape is `{ agentId, requestId, amount, chain: 'base', asset: 'USDC', recipient, service?, policy }` with `policy` requiring `maxPerTransaction`, `remainingDailyBudget`, `requireHumanAbove`, `maxRepeats`, `allowedRecipients`, and `blockUnknownRecipients`.
- **Reproducibility.** The maintainer can reproduce this end to end with `npm install && node agent.mjs`. No credentials, wallet, or funding is needed.

## Sanitization

The evidence log contains only public data: the well-known USDC contract address on Base, the SDK's own published `payTo` address from the x402 challenge, and BaseScan-visible values. No private key, seed phrase, wallet address used for personal testing, API key, or personal data appears anywhere in this repository.

## License

Apache-2.0, matching the upstream SDK.