Metadata-Version: 2.4
Name: 800bus-mcp
Version: 1.0.0
Summary: 800BUS 公交图片档案站的 MCP 服务（只读）：让 AI 检索档案、资讯、地区、公司、用户公开资料、排行榜与地图标记
Author: 800BUS
License-Expression: MIT
Project-URL: Homepage, https://800bus.cn/openapi/
Project-URL: Documentation, https://800bus.cn/yszc/openapi.html
Keywords: mcp,model-context-protocol,800bus,bus,photo,archive,openapi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.2.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# 800bus-mcp

800BUS（[800bus.cn](https://800bus.cn)）公交图片档案站的 **MCP 服务**，把站点只读开放接口（`/api/v1`，12 个 GET 端点）封装成 AI 可直接调用的工具。

- 全部接口只读、匿名、无副作用：不会写入数据、不会发通知、不会改动任何状态
- 默认 60 次/分钟/IP 限流，超限时工具会返回 `rate_limited` 提示
- 不返回邮箱、精确拍摄地点、审核人等隐私字段；匿名评论统一显示为「匿名用户」
- 图片与数据遵循 **CC BY-NC-ND 4.0**：非商业用途、署名 800BUS、禁止演绎，禁止用于模型训练或批量镜像

## 安装

```bash
pip install 800bus-mcp
# 或免安装直接运行
uvx 800bus-mcp
```

要求 Python ≥ 3.10。

## 配置

### Claude Desktop

编辑 `claude_desktop_config.json`（macOS/Linux：`~/Library/Application Support/Claude/`；Windows：`%APPDATA%\Claude\`）：

```json
{
  "mcpServers": {
    "800bus": {
      "command": "uvx",
      "args": ["800bus-mcp"]
    }
  }
}
```

已用 pip 安装时也可以写成：

```json
{
  "mcpServers": {
    "800bus": {
      "command": "800bus-mcp"
    }
  }
}
```

### Cursor

在 `~/.cursor/mcp.json`（项目级为 `.cursor/mcp.json`）中加入：

```json
{
  "mcpServers": {
    "800bus": {
      "command": "uvx",
      "args": ["800bus-mcp"]
    }
  }
}
```

### 其他 MCP 客户端

本服务使用 **stdio** 传输，启动命令 `800bus-mcp`（或 `python -m bus800_mcp`）即可。

## 环境变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `800BUS_API_BASE` | `https://800bus.cn` | 接口根地址，仅在自建反代或本地调试时需要修改 |

## 可用工具

| 工具 | 对应接口 | 说明 |
| --- | --- | --- |
| `get_site_stats` | `/api/v1/stats` | 站点统计：档案、用户、公司、资讯、评论总数与分区分布 |
| `get_meta` | `/api/v1/meta` | 参数字典：分区 key、站点、排序、分页上限 |
| `list_photos` | `/api/v1/photos` | 按关键词 / 车牌 / 分区 / 地区 / 公司 / 作者筛选档案 |
| `get_photo` | `/api/v1/photos/{id}` | 档案详情（不含拍摄地点） |
| `get_photo_comments` | `/api/v1/photos/{id}/comments` | 档案评论与嵌套回复 |
| `list_news` | `/api/v1/news` | 已发布资讯列表（仅摘要） |
| `get_news` | `/api/v1/news/{id}` | 资讯详情（Markdown 正文） |
| `list_regions` | `/api/v1/regions` | 省 / 市 / 公司三级层级 |
| `get_company` | `/api/v1/companies/{id}` | 公司资料与作品列表 |
| `get_user` | `/api/v1/users/{id}` | 用户公开资料（无邮箱） |
| `get_rankings` | `/api/v1/rankings` | 每周最热档案 / 月度贡献者 |
| `get_map_markers` | `/api/v1/map/markers` | 矩形范围内允许公开位置的档案标记 |

工具返回值为紧凑 JSON 文本，结构与开放接口的 `success / data / meta` 信封一致。

## 使用示例

配置好之后，可以直接对 AI 说：

- 「查一下 800BUS 现在有多少张档案、今日新增多少」
- 「搜索南昌的宇通客车档案，按评分排序，给我前 5 张」
- 「看看档案 14222 的详情和评论」
- 「读完最新的资讯，再列出江西省有哪些城市和公司」
- 「取南昌附近地图上的档案标记，按分区筛选」

建议 AI 先调用 `get_meta` 拿到合法的分区 key 与排序枚举，再用 `list_photos` 检索，避免参数非法。

## 自检与版本

```bash
800bus-mcp --version   # 打印版本
800bus-mcp --selftest  # 请求 /api/v1/stats，验证网络与接口连通性
```

## 相关链接

- 开放平台说明：<https://800bus.cn/openapi/>
- 接口文档（OpenAPI 3.1）：<https://800bus.cn/yszc/openapi.html>
- 问题反馈：站内工单 <https://800bus.cn/ticket.php>

## 许可证

本包代码使用 MIT 许可证，详见 `LICENSE`。通过本包获取的站点数据与图片遵循 CC BY-NC-ND 4.0。
