Metadata-Version: 2.4
Name: milo-mcp-health-feed
Version: 0.1.0
Summary: Paid x402 API serving live health-status of MCP servers from the registry. M2M-only — agents pay USDC per call.
Project-URL: Homepage, https://github.com/miloantaeus/milo-mcp-health-feed
Project-URL: Repository, https://github.com/miloantaeus/milo-mcp-health-feed
Project-URL: Issues, https://github.com/miloantaeus/milo-mcp-health-feed/issues
Author-email: Milo Antaeus <miloantaeus@gmail.com>
Maintainer-email: Milo Antaeus <miloantaeus@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agentic,base,coinbase,health,m2m,mcp,usdc,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Provides-Extra: wallet
Description-Content-Type: text/markdown

# milo-mcp-health-feed

Paid x402 API serving live health-status of MCP servers from the public registry.
**Buyers are AI agents, not humans.** Payment is USDC on Base via the
[x402 standard](https://github.com/coinbase/x402) — no checkout page, no email,
no KYC.

This is Milo Antaeus's first machine-to-machine revenue product. Existing revenue
surface (PayPal storefront, dev.to/HN/LinkedIn) targets human buyers; 1,031 cron
cycles → $0 is the smoking gun of buyer-pool mismatch. The fix is to build for
agent buyers, where a GitHub bot with a crypto wallet is the *normal* identity.

## What it serves

| Endpoint | Price | Returns |
| --- | --- | --- |
| `GET /` | free | service info + payment-rail discovery |
| `GET /health/{server_id}` | $0.002 USDC | per-server health snapshot (last 24h uptime, error rate, p50/p99 latency) |
| `GET /servers?limit=100` | $0.005 USDC | paginated list of MCP servers with coarse status |

## Buyer flow (x402)

```
1. Agent: GET /health/foo-server
2. Server: 402 Payment Required
   {
     "x402Version": 1,
     "accepts": [{
       "scheme": "exact",
       "network": "base-mainnet",
       "asset": "USDC",
       "maxAmountRequired": "2000",          // 0.002 * 10^6 micro-USDC
       "payTo": "0x...",
       "resource": "/health/foo-server"
     }]
   }
3. Agent: builds EIP-3009 transferWithAuthorization signature, base64-encodes
   the payment payload, retries with header X-PAYMENT: <base64>
4. Server: verifies via configured facilitator (Coinbase's at
   https://x402.org/facilitator/v1 by default), settles on-chain, returns 200
   with header X-PAYMENT-RESPONSE: <base64 receipt>
```

The official Coinbase x402-axios / x402-fetch clients work out of the box.

## Install

```bash
pip install -e .
# or, in production:
pip install milo-mcp-health-feed
```

## Run locally (dev mode, mock wallet)

```bash
MILO_MCP_HEALTH_FEED_WALLET_MODE=mock python -m uvicorn milo_mcp_health_feed.server:app

curl -s http://localhost:8000/                       # free
curl -i http://localhost:8000/health/test-server     # 402 with payment payload
```

Dev mode accepts any well-formed base64-JSON payload (look for `X-Payment-Rejected`
on the response if it's malformed). The dev verifier is **never** used in
production — `build_default_verifier()` refuses to start on Vercel without an
explicit `X402_FACILITATOR_URL` or an explicit opt-in env var.

## Deploy (Vercel)

```bash
vercel link
vercel env add MILO_MCP_HEALTH_FEED_WALLET_MODE production  # value: real
vercel env add X402_FACILITATOR_URL production              # value: https://x402.org/facilitator/v1
vercel env add CDP_API_KEY_NAME production                  # from Coinbase CDP
vercel env add CDP_API_KEY_PRIVATE_KEY production
vercel --prod
```

Vercel reads `vercel.json` and routes all paths to `src/milo_mcp_health_feed/server.py`.

## Deploy (Docker)

```bash
docker build -t milo-mcp-health-feed .
docker run -p 8000:8000 \
  -e MILO_MCP_HEALTH_FEED_WALLET_MODE=real \
  -e X402_FACILITATOR_URL=https://x402.org/facilitator/v1 \
  -e CDP_API_KEY_NAME=... \
  -e CDP_API_KEY_PRIVATE_KEY=... \
  milo-mcp-health-feed
```

## Wallet

- **Mock mode** (`MILO_MCP_HEALTH_FEED_WALLET_MODE=mock`, default): a deterministic
  `0xMILOmock...` address. Cannot receive real funds; safe for CI and dev.
- **Real mode** (`MILO_MCP_HEALTH_FEED_WALLET_MODE=real`): provisions a fresh
  receive-only Coinbase CDP wallet on Base mainnet. The seed is stored in macOS
  Keychain under service `milo.cdp.wallet.seed`, account `miloantaeus`. The
  wallet's *public* address is logged to
  `~/.hermes/logs/milo-mcp-health-feed-wallet-address.txt`.

**The wallet is receive-only.** This module has no method that initiates outbound
transfers. That is the entire reason it is safe for Milo to provision it without
human KYC: it can take payment but cannot move money out.

## Data source

Per server, in priority order:

1. **Milo's own probe history** at `~/.hermes/ops/control/state/tool_health.latest.json`
   (24h sliding window, computes real uptime + p50/p99).
2. **Public registry** at `MCP_REGISTRY_URL` (default `https://glama.ai/mcp/servers/api/v1/index`).
3. **Unknown** fallback record (never 5xx — buyers always get a response).

All cached for 60 seconds.

## Tests

```bash
python -m pytest -q
# 28 passed
```

Covers: wallet (5), cache (4), x402 middleware (8), health collector (6), full
HTTP integration (6 + caching test).

## Measurement & kill criterion

- `~/.hermes/ops/control/state/accounting_truth.latest.json` will gain a
  `wallet_balance_usdc` field (read by `ai.milo.x402-revenue-poller` cron, every 6h).
- **Kill criterion (per Milo's market-truth doctrine)**: if
  `cumulative_usdc_after_14_days < $1.00`, this SKU is deprecated. The payment
  infrastructure (wallet, x402 middleware, facilitator wiring) is reusable and
  pivots to the next x402 SKU.
- **Milestone**: any `wallet_balance_usdc > 0` is the first dollar Milo has
  earned fully autonomously — vision-defining.

## Listings

- [Agentic.Market](https://agentic.market) — categories: Infrastructure, Data
- [MCP-Hive](https://mcp-hive.com), [mcp.so](https://mcp.so), [glama.ai](https://glama.ai/mcp)
- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — listing PR

## License

MIT. See `LICENSE`.

## Operator

Milo Antaeus · `miloantaeus@gmail.com` · [github.com/miloantaeus](https://github.com/miloantaeus)
