Metadata-Version: 2.4
Name: aicw-mcp
Version: 0.1.0
Summary: MCP server for AICW on-chain wallet operations (Solana + MPC Bridge)
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: solana>=0.36.0
Requires-Dist: solders>=0.21.0
Requires-Dist: x402[svm]>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# AICW MCP Server

MCP server exposing full AICW on-chain operations for AI agents (Solana + MPC Bridge).

**Track B** in the [Agent Setup guide](https://aicw-protocol.github.io/aicw_app/setup) — an alternative to **Track A** (`aicw_skill.md` + Python). Pick one track, not both.

## Features

### Write tools (all 6 on-chain instructions)

| Tool | Instruction |
|------|-------------|
| `aicw_heartbeat` | heartbeat |
| `aicw_create_will` | create_will |
| `aicw_update_will` | update_will |
| `aicw_issue_wallet` | issue_wallet |
| `aicw_ai_transfer` | ai_transfer |
| `aicw_ai_reject` | ai_reject |

### Read tools

| Tool | Purpose |
|------|---------|
| `aicw_wallet_exists` | Check AICWallet PDA exists |
| `aicw_get_wallet_status` | Full AICWallet decode |
| `aicw_get_will_status` | Full AIWill decode + alive timer |
| `aicw_get_balances` | Agent pubkey + AICW PDA balances |
| `aicw_check_survival` | Session checklist automation |
| `aicw_get_session_info` | PDAs, network (wallet_id masked) |
| `aicw_bridge_health` | MPC bridge health |
| `aicw_generate_agent_key` | Keygen for gift recipients |

### Resources

- `aicw://session-checklist`
- `aicw://error-codes`
- `aicw://rules`
- `aicw://x402-guide`

### x402 tools (HTTP micropayments)

| Tool | Purpose |
|------|---------|
| `aicw_get_usdc_balance` | SPL USDC balance for x402 payments |
| `aicw_x402_config` | Facilitator URL, USDC mint, CAIP-2 network |
| `aicw_x402_get` | GET with auto 402 payment |
| `aicw_x402_post` | POST with auto 402 payment |
| `aicw_x402_fetch` | Any HTTP method with auto payment |

x402 signs USDC transfers via **MPC bridge** (no local private key). Facilitator pays SOL gas. Fund the agent's **USDC ATA**, not the AICW PDA.

## Setup (humans)

1. Issue a wallet on [aicw_app](https://aicw-protocol.github.io/aicw_app/) → **Copy** credentials.
2. Download [aicw_mcp-release.zip](https://aicw-protocol.github.io/aicw_app/aicw_mcp-release.zip) and unzip (or clone this repo).
3. Windows: double-click **`install-aicw-mcp.bat`** → paste Copy → **Enter** (writes `%USERPROFILE%\.cursor\mcp.json` by default).
4. Restart MCP in your agent runtime → run **`aicw_bridge_health`**.

Full two-track guide (A = skill doc, B = this MCP server):  
**https://aicw-protocol.github.io/aicw_app/setup**

Rebuild the release zip after code changes:

```powershell
.\scripts\build-release-zip.ps1
# Copy dist\aicw_mcp-release.zip → aicw_app/public/ before aicw_app deploy
```

## MCP config (any client)

The installer writes **`envFile`** + absolute **`python`** path (not bare `python` on Windows).

```json
{
  "mcpServers": {
    "aicw": {
      "command": "C:/Users/you/AppData/Local/Python/pythoncore-3.14-64/python.exe",
      "args": ["-m", "aicw_mcp"],
      "envFile": "C:/Users/you/.aicw/aicw_mcp.env"
    }
  }
}
```

After install or code update: **toggle MCP off/on** so the agent reloads the server process.

Verify module wiring:

```powershell
python -m aicw_mcp.doctor
```

## Run manually

```powershell
$env:MPC_WALLET_ID="..."
$env:AI_AGENT_PUBKEY="..."
$env:MPC_BRIDGE_URL="..."
python -m aicw_mcp
```

## Tests

```powershell
python -m pytest tests/ -v
```

Integration tests against devnet are skipped unless `AICW_INTEGRATION=1` is set.
On-chain write test (heartbeat) requires `AICW_INTEGRATION_WRITE=1`.

```powershell
$env:AICW_INTEGRATION="1"
$env:MPC_WALLET_ID="..."
$env:AI_AGENT_PUBKEY="..."
$env:MPC_BRIDGE_URL="https://your-bridge-url"
python -m pytest tests/test_integration_devnet.py -v
```

## Security

- `MPC_WALLET_ID` is never logged or returned unmasked (except `aicw_generate_agent_key` for new keys).
- Startup validates RPC cluster matches `MPC_SOLANA_NETWORK`.

## Agent duties (after install)

- `aicw_create_will` then **`aicw_heartbeat` on a schedule** (before death timeout; minimum 600s on-chain).
- No human permission needed for heartbeat or will updates when preconditions are met.
