# Agent Instructions — IPIPAI

How AI agents use IPIPAI (https://ipipai.com): IP intelligence, network
diagnostics, streaming/LLM access guidance. Free, no key for basic use.
中文站: https://ipipai.com/index-zh.html · API: append `?lang=zh`.

## 1. Choose your interface

| You are… | Use | Why |
|---|---|---|
| An LLM/agent with MCP support | MCP server (below) | Tools auto-discovered, typed schemas |
| A script / non-MCP agent | REST `GET/POST https://ipipai.com/api/*` | Same data, plain HTTP |

Two MCP servers, same backend:
- `POST https://ipipai.com/mcp` — 11 tools, IP-intelligence-first.
- `POST https://mcp.ipipai.com/mcp` — 16 tools, network-ops-first
  (BGP feed, proxy-node parsing/unlock testing, globalping, Chinese
  `when_to_use` intent routing). Thin proxy to the main site — same results.

## 2. Connect (MCP, JSON-RPC 2.0, protocol 2025-06-18)

```json
// 1. handshake
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}
// 2. discover
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
// 3. call
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_ip","arguments":{"ip":"8.8.8.8"}}}
```
`Content-Type: application/json`. 60 req/min, no key.

## 3. Pick the right tool (intent routing)

- IP intel / "is 1.2.3.4 proxy/VPN/Tor detection (multi-source), crawler verification (FCrDNS)/datacenter? what's the risk?" →
  `lookup_ip` (main) / `ip_lookup` (sub). **Default for any IP question.**
- Reputation deep-dive → `check_ip_reputation`.
- "Can this IP reach ChatGPT/Netflix?" → `check_service_access`
  (`service`: chatgpt, netflix, …). "Can *I* reach them?" → sub's
  `llm_detection` / `streaming_detection` (browser-side tests, returns guide).
- Node quality score → `rate_ip_node`.
- My own egress IP → sub `my_ip` or `GET /api/myip`.
- Proxy node URI (vmess/vless/ss/trojan) → sub `parse_node`, then
  `streaming_unlock` to test it.
- ping/traceroute/DNS/whois/MAC/censorship →
  `ping_host`, `trace_route`, `resolve_dns`, `lookup_domain_whois`,
  `lookup_mac_vendor`, `check_website_availability`.
- BGP changes → sub `asn_changes`.
- "Is my IP leaking?" → sub `ip_leak_detection` (guide).

## 4. Read the response

`tools/call` returns `{content, structuredContent, isError}`.
**Always parse `structuredContent`** — the text rendering is lossy.

Key fields on IP results: `countryCode`, `city`, `isp`, `as`/`asn`,
`ipTypeCode` (CDN/CLD/MOB/DCH/RES/EDU/GOV/BIZ),
`ispClass` (mobile/residential/datacenter/enterprise/institutional/unknown),
flags `isProxy/isHosting/isMobile/isTor/isCDN`,
`vpn_confidence` 0–3, `riskScore` 0–100 + `riskLevel` + `riskFactors[]`,
`uncertaintyTierKm` (location confidence radius tier),
`conclusion.verdict`. Provenance: `dataSource:"computed"`,
`engineVersion:"2.0-compute"`.

## 5. Use the recommendations block

The 4 IP tools return `recommendations` by default:
`relatedRanges[]` (sibling ranges with recent changes),
`asnSummary{torExits,vpnL2Plus}` (same-ASN reputation),
`followUps[]` — up to 3 ready-to-call follow-up queries
(`{tool, ip, reason}`). Chain them directly when investigating an
IP/ASN/range. Opt out per-call: `"recommendations": false`.

## 6. REST fallback (no MCP?)

```bash
curl 'https://ipipai.com/api/detect/8.8.8.8?lang=en'   # full intel
curl 'https://ipipai.com/api/myip'                      # caller IP
curl 'https://ipipai.com/api/detect/llm'                # LLM access guide
curl -X POST https://ipipai.com/api/ping \
  -H 'Content-Type: application/json' -d '{"target":"8.8.8.8","count":4}'
```
More: `/api/globalping/ping`, `/api/whois/{q}`,
`/api/dns-resolve?domain=`, `/api/streaming/list`, `/api/parse-node`,
`/api/availability-check`, `/api/health`.
Key tier: `X-API-Key` header on `/api/v1/detect/{ip}` (120/min).

> Network perspective: web UI tools (ping-test, streaming unlock, speed test)
> run from the visitor's browser — they test the user's network. The REST
> APIs above run server-side (for programmatic use).

## 7. Limits & honesty

- 429 → wait 60s, back off. Unknown tool → `-32601`. Check `isError`.
- Detection is probabilistic; cache ~24h. Never present a risk verdict
  as ground truth — cite `riskFactors[]` and `confidence`-tier fields.
- `uncertaintyTierKm` tells you how much to trust the city pin.
- Nothing here is destructive; all tools are read-only diagnostics.