# Agent中国通

> 让 AI Agent 真正接入中国互联网的 MCP 工具箱。

[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-339933)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-ready-635BFF)](https://modelcontextprotocol.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

Agent中国通是一个面向中文圈的 Model Context Protocol Server。它把中国互联网常用能力包装成标准 MCP 工具，让 Claude Desktop、Cursor、Cherry Studio、Dify/OpenCode 等 Agent 可以安全、稳定地调用。

## 30 秒快速开始

```bash
npx -y agent-cn-tong banner
npx -y agent-cn-tong list-tools
npx -y agent-cn-tong doctor
```

作为 MCP Server 启动：

```bash
npx -y agent-cn-tong serve
```

源码调试：

```bash
npm install
npm run build
node dist/cli.js list-tools
node dist/cli.js serve
```

## 支持工具

| 工具                     | 分类      | 说明                                    | 配置                |
| ------------------------ | --------- | --------------------------------------- | ------------------- |
| `cn_time_now`            | time      | 中国时区当前时间                        | 无                  |
| `cn_amap_geocode`        | map       | 中文地址转经纬度                        | `AMAP_API_KEY`      |
| `cn_amap_regeocode`      | map       | 经纬度反查中文地址                      | `AMAP_API_KEY`      |
| `cn_amap_weather`        | map       | 中国城市天气                            | `AMAP_API_KEY`      |
| `cn_amap_place_search`   | map       | 中国 POI/地点搜索                       | `AMAP_API_KEY`      |
| `cn_express_track`       | logistics | 中国快递轨迹查询                        | 快递100或快递鸟授权 |
| `cn_rss_fetch`           | content   | RSS/Atom 订阅读取、去重、排序、摘要控制 | 无                  |
| `cn_bilibili_video_info` | content   | B站公开视频基础信息                     | 无                  |
| `cn_webpage_extract`     | web       | 公开网页正文提取，防 SSRF               | 无                  |
| `cn_link_preview`        | web       | 公开链接预览                            | 无                  |
| `cn_ip_lookup`           | security  | 公网 IP 归属地/运营商查询               | 无                  |
| `cn_holiday_info`        | utility   | 中国节假日/工作日查询，内置 2025/2026   | 无                  |
| `cn_text_normalize`      | utility   | 中文文本清洗/脱敏                       | 无                  |

查看单个工具：

```bash
agent-cn-tong inspect cn_amap_weather
agent-cn-tong inspect cn_text_normalize --json
```

## MCP 客户端配置

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "agent-cn-tong": {
      "command": "npx",
      "args": ["-y", "agent-cn-tong", "serve"],
      "env": {
        "AMAP_API_KEY": "替换为你的高德 Web 服务 Key",
        "AGENT_CN_TONG_LOG_LEVEL": "warn"
      }
    }
  }
}
```

源码本地调试：

```json
{
  "mcpServers": {
    "agent-cn-tong-local": {
      "command": "node",
      "args": ["/absolute/path/to/agent-cn-tong/dist/cli.js", "serve"],
      "env": {
        "AMAP_API_KEY": "替换为你的高德 Web 服务 Key"
      }
    }
  }
}
```

更多示例见 `examples/`。

## CLI

```bash
agent-cn-tong serve                 # 启动 MCP stdio server
agent-cn-tong list-tools [--json]   # 漂亮表格/JSON 列出工具
agent-cn-tong inspect <tool>        # 查看工具参数、配置、示例
agent-cn-tong doctor [--json]       # 彩色健康检查
agent-cn-tong config [--json]       # 展示配置说明
agent-cn-tong init [--json]         # 生成 .env.example 和客户端配置示例
agent-cn-tong banner                # 显示项目 banner
agent-cn-tong version               # 输出版本号
```

## 环境变量

```bash
AMAP_API_KEY=
EXPRESS_PROVIDER=              # kuaidi100 或 kdniao
KUAIDI100_CUSTOMER=
KUAIDI100_KEY=
KDNIAO_EBUSINESS_ID=
KDNIAO_API_KEY=
AGENT_CN_TONG_HTTP_TIMEOUT_MS=10000
AGENT_CN_TONG_HTTP_MAX_BYTES=2097152
AGENT_CN_TONG_HTTP_RETRIES=1
AGENT_CN_TONG_LOG_LEVEL=warn
```

### 高德地图

到高德开放平台创建 **Web 服务 Key**，配置 `AMAP_API_KEY` 后可使用高德相关工具。

### 快递查询

为了合规，项目不做未授权网页抓取。你需要选择一个授权服务商：

- 快递100：`EXPRESS_PROVIDER=kuaidi100`，并配置 `KUAIDI100_CUSTOMER`、`KUAIDI100_KEY`。
- 快递鸟：`EXPRESS_PROVIDER=kdniao`，并配置 `KDNIAO_EBUSINESS_ID`、`KDNIAO_API_KEY`。

部分快递公司可能要求手机号后四位，请在工具参数 `phone` 中传入。

## 常见任务示例

```text
查一下北京望京 SOHO 的经纬度，然后找附近 2 公里内的咖啡店。
```

```text
读取这个 RSS，按发布时间排序，总结最新 5 篇文章：https://example.com/feed.xml
```

```text
帮我看这个 B 站视频的标题、UP 主和播放数据：BV1xx411c7mD
```

```text
提取这个公开网页的正文摘要，并返回前 10 个链接：https://example.com/article
```

```text
把这段群聊文本清洗一下，脱敏手机号和邮箱。
```

```text
2026-10-01 是工作日吗？
```

## 安全与合规边界

Agent中国通坚持以下边界：

- 不模拟登录、不绕过验证码、不绕过平台访问限制。
- 不下载受版权保护或需登录授权的内容。
- 不读取本地文件、内网地址、localhost 或 file 协议网页。
- 不保存、不打印、不返回 API Key。
- 网页工具默认禁止 localhost、内网、保留地址，降低 SSRF 风险。
- 工具错误返回结构化 `ok=false`、`error.code`、`error.message`、`error.hint`，方便 Agent 给用户修复建议。

## 开发

```bash
npm install
npm run typecheck
npm run lint
npm run format:check
npm run test
npm run build
```

单项测试：

```bash
npm run test:unit
npm run test:tools
npm run test:mcp
npm run test:cli
```

发布前建议：

```bash
npm run typecheck
npm run lint
npm run format:check
npm run test:unit
npm run test:tools
npm run test:mcp
npm run test:cli
npm run test
npm run build
npm pack --dry-run
node dist/cli.js list-tools
node dist/cli.js list-tools --json
node dist/cli.js doctor
node dist/cli.js doctor --json
node dist/cli.js inspect cn_time_now
```

## 路线图

- 更多本土 API：飞书、企业微信、WPS、OCR。
- 可选 Streamable HTTP 模式。
- 工具市场式插件加载。
- 更完整的中国节假日年度数据。
- 更强网页正文抽取算法。

## 项目理念

国外 MCP 生态已经很丰富，但中文互联网服务适配还很分散。Agent中国通想做的是一个干净、可扩展、合规的中文 Agent 能力底座：

> 让你的 AI 终于认识中国互联网。

## License

MIT