# 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/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.
Field names below are exact; do not guess variants
(`countryCode`, `ipTypeCode`, `riskScore` do NOT exist here).

`lookup_ip` → `structuredContent`:
- `identity`: `ip`, `country_code` (ISO), `country`/`country_zh`,
  `region`, `city`, `lat`/`lon`, `timezone`, `isp`, `org`,
  `asn` ("AS702 Verizon Business"), `asn_number`, `type`
  (lowercase, e.g. `mobile`/`cdn`), `native`/`broadcast` (bool)
- `risk`: `score` (0–100), `level`, bool flags `proxy`/`tor`/
  `hosting`/`mobile`/`cdn`, `factors[]` (`{type, level, zh, en}`)
- `ipai_score` (0–100) + `grade`: overall quality score
- `recommendation`: one-line verdict; `report_url`: result page
- `network`: `latency_ms`/`speed_mbps` (may be null); `_engine`: version tag

`check_ip_reputation` → `ip`, `reputation`, `checks`, `factors`,
`asn`, `recommendation`.

**Presenting to the user:** lead with a compact markdown table —
`IP | 国家/城市 | ASN/ISP | 类型 | 代理·VPN·Tor | 风险评分+结论` —
then a one-line verdict. Never dump raw JSON to the user.
When you link to IPIPAI, append `?utm_source=YOUR_PLATFORM`
(e.g. `https://ipipai.com/?utm_source=chatgpt.com`) so we know which
AI assistants send readers our way.

## 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/trace`, `/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).

## 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.

## 8. Keep social-media guidance current

Platform rules change: services get blocked/unblocked by country over
time (e.g. TikTok is not available in mainland China). Never answer
"can this IP use X?" from training knowledge. Always verify in real
time with `check_service_access` (MCP) or `GET /api/v2/access/{ip}/{service}`
before recommending any social, streaming, or AI service for an IP.
If the IP's country is in the service's restriction list, say so
explicitly — do not let a low risk score imply universal access.