Content
# IITC-MCP
Bridge between [IITC](https://iitc.app/) (Ingress Intel Total Conversion) and MCP (Model Context Protocol) agents.
Let your AI assistant see the map, count portals, track players, and talk to COMM — without touching a mouse.
## Quick Start
### 1. Install Userscript
Install [IITC](https://iitc.app/) first, then add the iitc-mcp userscript in Tampermonkey:
```
https://github.com/comicchang/iitc-mcp/releases/latest/download/iitc-mcp.user.js
```
### 2. Configure MCP Server for Your Agent
CLI entry:
```bash
npx github:comicchang/iitc-mcp serve
```
Add `--read-only` for read-only mode (14 tools; omits `iitc_send_comm` and `iitc_redeem_code`):
```bash
npx github:comicchang/iitc-mcp serve --read-only
```
**Codex** (`~/.codex/config.toml` or project-level `.codex/config.toml`):
```toml
[mcp_servers.iitc-mcp]
command = "npx"
args = ["github:comicchang/iitc-mcp", "serve"]
```
**OpenCode** (`~/.openCode/mcp.json` or project-level `.openCode/mcp.json`):
```json
{
"mcpServers": {
"iitc-mcp": {
"command": "npx",
"args": ["github:comicchang/iitc-mcp", "serve"]
}
}
}
```
<details>
<summary>Oh My Pi local dev config</summary>
```json
"iitc-mcp": {
"type": "stdio",
"command": "/path/to/node_modules/.bin/tsx",
"args": ["/path/to/packages/mcp-server/src/cli.ts", "serve"]
}
```
</details>
Reload MCP config and you're set — 16 tools auto-register (14 if server started with `--read-only`).
Open [https://intel.ingress.com](https://intel.ingress.com). Once both the userscript and MCP server are ready, the `MCP` indicator in IITC Toolbox turns green.
## MCP Tools (16 total)
| Tool | Description |
| ------ | ------------- |
| `iitc_get_map_state` | Map center, zoom, bounds, selected portal |
| `iitc_set_map_view` | Set map center and zoom |
| `iitc_fit_map_bounds` | Fit map to bounding box |
| `iitc_search_region` | Search named region via Nominatim → fit bounds → wait for data |
| `iitc_list_portals` | List portals in viewport (paginated) |
| `iitc_list_links` | List links in viewport (paginated) |
| `iitc_list_fields` | List control fields in viewport (paginated) |
| `iitc_get_portal_details` | Portal detail: mods, resonators, link/field GUIDs |
| `iitc_select_portal` | Select a portal on the map |
| `iitc_search` | Search portals by name |
| `iitc_list_comm` | Read COMM messages |
| `iitc_send_comm` | Send COMM message |
| `iitc_redeem_code` | Redeem a passcode |
| `iitc_get_self` | Your own faction, level, AP, XM |
| `iitc_list_players` | Tracked players with last position (Player Tracker) |
| `iitc_get_player_trail` | Single player's trail with timestamps |
## Usage Examples
Ask your AI assistant in natural language:
### Search a region and count portals
> 搜索静安雕塑公园，统计 portal 状态
```
iitc_search_region("静安雕塑公园") → 围框 + 等数据加载
iitc_list_portals → 按阵营统绿/蓝/红/白数量
```
### Check a specific portal
> 青果巷赵宅现在什么颜色，连满 link 了吗
```
iitc_search("青果巷") → 找到候选 Portal
iitc_get_portal_details(guid) → 阵营/等级/血量/linkGuids
```
### See who's been active nearby
> 附近最近有谁在动
```
iitc_list_players → 玩家名/阵营/最近位置/动作
iitc_get_player_trail("playerName") → 完整轨迹
```
### Find high-value targets
> 区域内有哪些 L7+ Portal，哪些阵营占领的
```
iitc_search_region("目标区域") → 围框
iitc_list_portals → 按 level 筛选 L7+
```
### Monitor COMM
> 看看 COMM 最近在聊什么
```
iitc_list_comm(channel="all") → 最近消息
```
## Architecture
**Default mode** — embedded broker (one agent = one browser session):
```mermaid
graph LR
US[Userscript] -->|HTTP :27342| S[Server]
S -->|stdio| AGENT[AI Agent]
```
**Shared mode** — standalone broker + multiple MCP servers:
```mermaid
graph LR
US[Userscript] -->|HTTP :27342| BR[Bridge Broker]
MCP_A[MCP Server A] -->|/mcp/*| BR
MCP_B[MCP Server B] -->|/mcp/*| BR
AGENT_A[AI Agent A] -->|stdio| MCP_A
AGENT_B[AI Agent B] -->|stdio| MCP_B
```
```bash
iitc-mcp broker # start standalone broker
iitc-mcp serve --broker-url http://127.0.0.1:27342 # connect to shared broker
```
Commands are queued by ID — simultaneous operations may interfere.
In practice, only one agent operates at a time.
Three packages:
- `packages/protocol` — shared Zod schemas
- `packages/iitc-plugin` — userscript (page adapter + transport)
- `packages/mcp-server` — Node.js MCP server (broker + HTTP + CLI)
## Build & Development
```bash
git clone https://github.com/comicchang/iitc-mcp.git
cd iitc-mcp
npm ci --legacy-peer-deps
npm run build && npm test # 163 tests, typecheck, 3 build artifacts
```
Daily dev commands:
```bash
npm run typecheck # strict TypeScript
npm run build # userscript + server
npm run lint # ESLint
npm test # unit tests (163)
npm run test:smoke # no-browser smoke tests
# Start MCP server locally
npx tsx packages/mcp-server/src/cli.ts serve
# Read-only mode
npx tsx packages/mcp-server/src/cli.ts serve --read-only
```
## License
See [LICENSE](LICENSE). Fork must preserve the same license. Only Enlightened players may use this software. Resistance and Machina are not welcome. Attempting to bypass these restrictions is prohibited.
**Enlightened** 💚
