内容
# IITC-MCP
Ingress Intel Total Conversion（IITC）与 Model Context Protocol（MCP）代理之间的桥梁。
让您的 AI 助手看到地图、统计 Portal、跟踪玩家并与 COMM 交流 — 无需手动操作。
## 快速入门
### 1. 安装 Userscript
首先安装 [IITC](https://iitc.app/)，然后在 Tampermonkey 中添加 iitc-mcp 用户脚本：
```bash
https://github.com/comicchang/iitc-mcp/releases/latest/download/iitc-mcp.user.js
```
### 2. 为您的代理配置 MCP 服务器
命令行入口：
```bash
npx github:comicchang/iitc-mcp serve
```
添加 `--read-only` 以启用只读模式（14 种工具；省略 `iitc_send_comm` 和 `iitc_redeem_code`）：
```bash
npx github:comicchang/iitc-mcp serve --read-only
```
**Codex** (`~/.codex/config.toml` 或项目级别的 `.codex/config.toml`）：
```toml
[mcp_servers.iitc-mcp]
command = "npx"
args = ["github:comicchang/iitc-mcp", "serve"]
```
**OpenCode** (`~/.openCode/mcp.json` 或项目级别的 `.openCode/mcp.json`）：
```json
{
"mcpServers": {
"iitc-mcp": {
"command": "npx",
"args": ["github:comicchang/iitc-mcp", "serve"]
}
}
}
```
<details>
<summary>Oh My Pi 本地开发配置</summary>
```json
"iitc-mcp": {
"type": "stdio",
"command": "/path/to/node_modules/.bin/tsx",
"args": ["/path/to/packages/mcp-server/src/cli.ts", "serve"]
}
```
</details>
重新加载 MCP 配置，您就可以使用 16 种工具（如果服务器以 `--read-only` 启动，则为 14 种）。
打开 [https://intel.ingress.com](https://intel.ingress.com)。当用户脚本和 MCP 服务器都准备就绪后，IITC 工具箱中的 `MCP` 指示器变为绿色。
## MCP 工具（共 16 种）
| 工具 | 描述 |
| ------ | ------------- |
| `iitc_get_map_state` | 地图中心、缩放级别、边界、选定 Portal |
| `iitc_set_map_view` | 设置地图中心和缩放级别 |
| `iitc_fit_map_bounds` | 将地图适应到边界框 |
| `iitc_search_region` | 通过 Nominatim 搜索命名区域 → 适应边界 → 等待数据 |
| `iitc_list_portals` | 列出视口中的 Portal（分页） |
| `iitc_list_links` | 列出视口中的链接（分页） |
| `iitc_list_fields` | 列出视口中的控制字段（分页） |
| `iitc_get_portal_details` | Portal 详细信息：模组、谐振器、链接/字段 GUID |
| `iitc_select_portal` | 在地图上选择一个 Portal |
| `iitc_search` | 按名称搜索 Portal |
| `iitc_list_comm` | 读取 COMM 消息 |
| `iitc_send_comm` | 发送 COMM 消息 |
| `iitc_redeem_code` | 兑换通行码 |
| `iitc_get_self` | 您自己的派系、等级、AP、XM |
| `iitc_list_players` | 跟踪具有最后位置的玩家（玩家跟踪器） |
| `iitc_get_player_trail` | 具有时间戳的单个玩家的轨迹 |
## 使用示例
用自然语言询问您的 AI 助手：
### 搜索区域并统计 Portal
> 搜索静安雕塑公园，统计 portal 状态
```
iitc_search_region("静安雕塑公园") → 围框 + 等数据加载
iitc_list_portals → 按阵营统绿/蓝/红/白数量
```
### 检查特定 Portal
> 青果巷赵宅现在什么颜色，连满 link 了吗
```
iitc_search("青果巷") → 找到候选 Portal
iitc_get_portal_details(guid) → 阵营/等级/血量/linkGuids
```
### 查看附近活跃的玩家
> 附近最近有谁在动
```
iitc_list_players → 玩家名/阵营/最近位置/动作
iitc_get_player_trail("playerName") → 完整轨迹
```
### 查找高价值目标
> 区域内有哪些 L7+ Portal，哪些阵营占领的
```
iitc_search_region("目标区域") → 围框
iitc_list_portals → 按 level 筛选 L7+
```
### 监控 COMM
> 看看 COMM 最近在聊什么
```
iitc_list_comm(channel="all") → 最近消息
```
## 架构
**默认模式** — 嵌入式代理（一个代理 = 一个浏览器会话）：
```mermaid
graph LR
US[Userscript] -->|HTTP :27342| S[Server]
S -->|stdio| AGENT[AI Agent]
```
**共享模式** — 独立代理 + 多个 MCP 服务器：
```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 # 启动独立代理
iitc-mcp serve --broker-url http://127.0.0.1:27342 # 连接到共享代理
```
命令按 ID 排队 — 同时操作可能会相互干扰。
实际上，通常只有一个代理在运行。
三个软件包：
- `packages/protocol` — 共享 Zod 模式
- `packages/iitc-plugin` — 用户脚本（页面适配器 + 传输）
- `packages/mcp-server` — Node.js MCP 服务器（代理 + HTTP + 命令行界面）
## 构建与开发
```bash
git clone https://github.com/comicchang/iitc-mcp.git
cd iitc-mcp
npm ci --legacy-peer-deps
npm run build && npm test # 163 个测试，类型检查，3 个构建产物
```
日常开发命令：
```bash
npm run typecheck # 严格的 TypeScript
npm run build # 用户脚本 + 服务器
npm run lint # ESLint
npm test # 单元测试（163 个）
npm run test:smoke # 无浏览器烟雾测试
# 在本地启动 MCP 服务器
npx tsx packages/mcp-server/src/cli.ts serve
# 只读模式
npx tsx packages/mcp-server/src/cli.ts serve --read-only
```
## 许可证
参见 [LICENSE](LICENSE)。Fork 必须保留相同的许可证。只有 Enlightened 玩家可以使用此软件。Resistance 和 Machina 不被允许使用。尝试绕过这些限制是被禁止的。
**Enlightened**
