800bus-mcp 1.0.0__tar.gz

800bus_mcp-1.0.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 800BUS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+注意：本许可证仅覆盖本包的代码。通过本包获取的 800BUS 站点数据与图片
+遵循 CC BY-NC-ND 4.0（署名 800BUS、非商业用途、禁止演绎），且禁止用于
+模型训练或批量镜像。

800bus_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,144 @@
+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。

800bus_mcp-1.0.0/README.md

@@ -0,0 +1,120 @@
+# 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。

800bus_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "800bus-mcp"
+version = "1.0.0"
+description = "800BUS 公交图片档案站的 MCP 服务（只读）：让 AI 检索档案、资讯、地区、公司、用户公开资料、排行榜与地图标记"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "800BUS" }]
+keywords = ["mcp", "model-context-protocol", "800bus", "bus", "photo", "archive", "openapi"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+dependencies = [
+  "mcp>=1.2.0",
+  "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://800bus.cn/openapi/"
+Documentation = "https://800bus.cn/yszc/openapi.html"
+
+[project.scripts]
+800bus-mcp = "bus800_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

800bus_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

800bus_mcp-1.0.0/src/800bus_mcp.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+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。

800bus_mcp-1.0.0/src/800bus_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/800bus_mcp.egg-info/PKG-INFO
+src/800bus_mcp.egg-info/SOURCES.txt
+src/800bus_mcp.egg-info/dependency_links.txt
+src/800bus_mcp.egg-info/entry_points.txt
+src/800bus_mcp.egg-info/requires.txt
+src/800bus_mcp.egg-info/top_level.txt
+src/bus800_mcp/__init__.py
+src/bus800_mcp/__main__.py
+src/bus800_mcp/client.py
+src/bus800_mcp/server.py

800bus_mcp-1.0.0/src/800bus_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

800bus_mcp-1.0.0/src/800bus_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+800bus-mcp = bus800_mcp.server:main

800bus_mcp-1.0.0/src/800bus_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp>=1.2.0
+httpx>=0.27.0

800bus_mcp-1.0.0/src/800bus_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+bus800_mcp

800bus_mcp-1.0.0/src/bus800_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""800BUS MCP 服务包。"""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

800bus_mcp-1.0.0/src/bus800_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""支持 `python -m bus800_mcp`。"""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

800bus_mcp-1.0.0/src/bus800_mcp/client.py

@@ -0,0 +1,104 @@
+"""800BUS 开放接口（/api/v1）的极简 HTTP 客户端。
+
+约定：
+- 全部为 GET 请求，匿名调用，无需 API Key；
+- 默认 60 次/分钟/IP，超限返回 429；
+- 响应信封为 {"success": true, "data": ..., "meta": ...} 或
+  {"success": false, "error": {"code": ..., "message": ...}}。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+import httpx
+
+from . import __version__
+
+DEFAULT_BASE_URL = "https://800bus.cn"
+TIMEOUT_SECONDS = 20.0
+USER_AGENT = f"800bus-mcp/{__version__} (+https://800bus.cn/openapi/)"
+
+_client: httpx.Client | None = None
+
+
+class ApiError(Exception):
+    """接口调用失败的统一异常，code 与开放接口的 error.code 保持一致。"""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def base_url() -> str:
+    """接口根地址，可用环境变量 800BUS_API_BASE 覆盖（自建反代 / 调试用）。"""
+    raw = os.environ.get("800BUS_API_BASE") or DEFAULT_BASE_URL
+    return raw.strip().rstrip("/")
+
+
+def _get_client() -> httpx.Client:
+    global _client
+    if _client is None:
+        _client = httpx.Client(
+            base_url=base_url(),
+            timeout=TIMEOUT_SECONDS,
+            headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+            follow_redirects=True,
+        )
+    return _client
+
+
+def _clean_params(params: Mapping[str, Any] | None) -> dict[str, Any]:
+    """去掉 None，布尔值转小写字符串（PHP 侧按字符串判断）。"""
+    out: dict[str, Any] = {}
+    for key, value in (params or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        else:
+            out[key] = value
+    return out
+
+
+def get_json(path: str, params: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """请求一个只读接口并返回解析后的 JSON 信封。失败时抛出 ApiError。"""
+    client = _get_client()
+    try:
+        response = client.get(path, params=_clean_params(params))
+    except httpx.TimeoutException:
+        raise ApiError("timeout", f"请求 {base_url()} 超时（{int(TIMEOUT_SECONDS)} 秒），请稍后重试") from None
+    except httpx.HTTPError as exc:
+        raise ApiError("network_error", f"网络请求失败：{exc}") from None
+
+    if response.status_code == 429:
+        retry_after = response.headers.get("Retry-After") or "60"
+        raise ApiError(
+            "rate_limited",
+            f"请求过于频繁（默认 60 次/分钟/IP），请等待约 {retry_after} 秒后重试",
+        )
+
+    try:
+        payload = response.json()
+    except ValueError:
+        # 站点的 nginx 会把 404 响应替换为 HTML 错误页，这里兜底成可读提示
+        if response.status_code == 404:
+            raise ApiError("not_found", "资源不存在或已下架（HTTP 404）") from None
+        raise ApiError("bad_response", f"接口返回了非 JSON 内容（HTTP {response.status_code}）") from None
+
+    if response.status_code >= 400 or not payload.get("success"):
+        error = payload.get("error") or {}
+        code = str(error.get("code") or f"http_{response.status_code}")
+        message = str(error.get("message") or f"接口返回 HTTP {response.status_code}")
+        raise ApiError(code, message)
+
+    return payload
+
+
+def close() -> None:
+    """关闭底层连接池（主要用于测试）。"""
+    global _client
+    if _client is not None:
+        _client.close()
+        _client = None

800bus_mcp-1.0.0/src/bus800_mcp/server.py

@@ -0,0 +1,302 @@
+"""800BUS MCP 服务（stdio 传输）。
+
+把 800bus.cn 的只读 OpenAPI（12 个 GET 接口）封装成 MCP 工具，
+所有工具都没有副作用：不写数据、不发通知、不改状态。
+
+配置方式（Claude Desktop / Cursor 等）见 README.md。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+try:  # mcp 2.x 将 FastMCP 重命名为 MCPServer
+    from mcp.server.mcpserver import MCPServer as _MCPServer
+except ImportError:  # mcp 1.x
+    from mcp.server.fastmcp import FastMCP as _MCPServer
+
+from . import __version__
+from .client import ApiError, base_url, get_json
+
+mcp = _MCPServer(
+    "800bus",
+    instructions=(
+        "800BUS（800bus.cn）公交图片档案站的只读开放接口。"
+        "所有工具均无副作用。"
+        "检索前建议先调用 get_meta 获取分区 key（section）与排序枚举（sort），再调用 list_photos。"
+        "接口默认 60 次/分钟/IP，超限会返回 rate_limited 提示，请降低调用频率。"
+        "不返回邮箱、精确拍摄地点、审核人等隐私字段；匿名评论固定显示为「匿名用户」。"
+        "图片遵循 CC BY-NC-ND 4.0：非商业、署名 800BUS、禁止演绎，禁止用于模型训练或批量镜像。"
+    ),
+    log_level="WARNING",
+)
+
+
+def _dump(payload: Any) -> str:
+    """紧凑输出，减少上下文占用。"""
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+def _call(path: str, params: dict[str, Any] | None = None) -> str:
+    """统一请求 + 错误包装，保证工具永远返回可读文本而不是抛异常。"""
+    try:
+        return _dump(get_json(path, params))
+    except ApiError as exc:
+        return _dump(
+            {
+                "success": False,
+                "error": {"code": exc.code, "message": str(exc)},
+            }
+        )
+
+
+@mcp.tool()
+def get_site_stats() -> str:
+    """获取 800BUS 站点统计：档案、用户、公司、资讯、评论总数，今日上传数以及分区分布。无参数。"""
+    return _call("/api/v1/stats")
+
+
+@mcp.tool()
+def get_meta() -> str:
+    """获取参数字典：分区 key（sections / draw_sections）、站点（sites）、排序（sorts）与分页上限。
+
+    构造 list_photos 等查询参数前建议先调用本工具，避免使用不存在的分区 key。
+    """
+    return _call("/api/v1/meta")
+
+
+@mcp.tool()
+def list_photos(
+    q: str | None = None,
+    plate: str | None = None,
+    section: str | None = None,
+    region: str | None = None,
+    company_id: int | None = None,
+    author_id: int | None = None,
+    site: str = "all",
+    sort: str = "latest",
+    featured: bool = False,
+    page: int = 1,
+    limit: int = 20,
+) -> str:
+    """搜索 / 列出已审核公开的图片档案，返回分页列表（含缩略图地址、评分、作者）。
+
+    参数：
+    - q：关键词，匹配品牌、车牌、地区、描述、公司名、作者名（≤60 字）
+    - plate：车牌片段，例如 B12345
+    - section：分区 key，取值先用 get_meta 获取
+    - region：地区文本片段，例如「南昌」
+    - company_id：公司 ID
+    - author_id：作者用户 ID
+    - site：all（默认）/ main（公交主站）/ draw（绘画站）
+    - sort：latest（最新）/ oldest（最早）/ hot（热门）/ rating（评分）/ featured（精选优先）
+    - featured：true 时仅返回精选档案
+    - page：页码，从 1 开始
+    - limit：每页条数，1–50，默认 20
+    """
+    return _call(
+        "/api/v1/photos",
+        {
+            "q": q,
+            "plate": plate,
+            "section": section,
+            "region": region,
+            "company_id": company_id,
+            "author_id": author_id,
+            "site": site,
+            "sort": sort,
+            "featured": True if featured else None,
+            "page": page,
+            "limit": limit,
+        },
+    )
+
+
+@mcp.tool()
+def get_photo(photo_id: int) -> str:
+    """获取单个图片档案的完整公开信息（不含拍摄地点）。
+
+    参数：
+    - photo_id：档案 ID，可从 list_photos 结果或 /photo/{id} 链接中获得
+    """
+    return _call(f"/api/v1/photos/{int(photo_id)}")
+
+
+@mcp.tool()
+def get_photo_comments(photo_id: int, page: int = 1, limit: int = 20) -> str:
+    """获取某个档案下已通过审核的评论及嵌套回复。
+
+    参数：
+    - photo_id：档案 ID
+    - page：页码，从 1 开始
+    - limit：每页条数，1–50，默认 20
+    """
+    return _call(
+        f"/api/v1/photos/{int(photo_id)}/comments",
+        {"page": page, "limit": limit},
+    )
+
+
+@mcp.tool()
+def list_news(
+    category: str | None = None,
+    province_id: int | None = None,
+    city_id: int | None = None,
+    page: int = 1,
+    limit: int = 12,
+) -> str:
+    """列出已发布的资讯（按发布时间倒序），列表仅含摘要，正文请再调用 get_news。
+
+    参数：
+    - category：分类名（可选）
+    - province_id：省份 ID（可选）
+    - city_id：城市 ID（可选）
+    - page：页码，从 1 开始
+    - limit：每页条数，1–50，默认 12
+    """
+    return _call(
+        "/api/v1/news",
+        {
+            "category": category,
+            "province_id": province_id,
+            "city_id": city_id,
+            "page": page,
+            "limit": limit,
+        },
+    )
+
+
+@mcp.tool()
+def get_news(news_id: int) -> str:
+    """获取单篇资讯详情，包含 Markdown 正文与图片列表。
+
+    参数：
+    - news_id：资讯 ID，可从 list_news 结果中获得
+    """
+    return _call(f"/api/v1/news/{int(news_id)}")
+
+
+@mcp.tool()
+def list_regions(
+    level: str = "province",
+    parent_id: int | None = None,
+    city_id: int | None = None,
+) -> str:
+    """获取省 / 市 / 公司三级层级，含城市数、公司数与档案数。
+
+    参数：
+    - level：province（省份，默认）/ city（城市）/ company（公司）
+    - parent_id：level=city 时传省份 ID；level=company 时可传城市 ID
+    - city_id：level=company 时可用（与 parent_id 二选一）
+    """
+    return _call(
+        "/api/v1/regions",
+        {"level": level, "parent_id": parent_id, "city_id": city_id},
+    )
+
+
+@mcp.tool()
+def get_company(company_id: int, page: int = 1, limit: int = 12) -> str:
+    """获取公司资料（名称、城市、省份、作品数）以及该公司最新的作品列表。
+
+    参数：
+    - company_id：公司 ID，可从 list_regions(level="company") 结果中获得
+    - page：作品页码，从 1 开始
+    - limit：每页作品数，1–50，默认 12
+    """
+    return _call(
+        f"/api/v1/companies/{int(company_id)}",
+        {"page": page, "limit": limit},
+    )
+
+
+@mcp.tool()
+def get_user(user_id: int) -> str:
+    """获取用户公开资料：昵称、头像、简介、加入时间、作品数与平均分、关注与粉丝数（不含邮箱）。
+
+    参数：
+    - user_id：用户 ID，可从档案作者字段或 /user/{id} 链接中获得
+    """
+    return _call(f"/api/v1/users/{int(user_id)}")
+
+
+@mcp.tool()
+def get_rankings(ranking_type: str = "weekly", limit: int = 10) -> str:
+    """获取排行榜。
+
+    参数：
+    - ranking_type：weekly（近 7 天最热档案，默认）/ monthly（近 30 天贡献者）
+    - limit：条数，1–20，默认 10
+    """
+    return _call("/api/v1/rankings", {"type": ranking_type, "limit": limit})
+
+
+@mcp.tool()
+def get_map_markers(
+    sw_lat: float | None = None,
+    sw_lng: float | None = None,
+    ne_lat: float | None = None,
+    ne_lng: float | None = None,
+    bbox: str | None = None,
+    section: str | None = None,
+    limit: int = 200,
+) -> str:
+    """获取矩形范围内允许公开位置的档案标记（坐标保留 4 位小数，不含详细地址）。
+
+    参数：
+    - sw_lat / sw_lng / ne_lat / ne_lng：西南角与东北角经纬度
+    - bbox：minLng,minLat,maxLng,maxLat，可替代上面四个参数
+    - section：分区 key（可选）
+    - limit：条数，1–500，默认 200（建议按可视范围分批取，避免一次拉太多）
+    """
+    return _call(
+        "/api/v1/map/markers",
+        {
+            "sw_lat": sw_lat,
+            "sw_lng": sw_lng,
+            "ne_lat": ne_lat,
+            "ne_lng": ne_lng,
+            "bbox": bbox,
+            "section": section,
+            "limit": limit,
+        },
+    )
+
+
+def _selftest() -> None:
+    """连通性自检：请求 /api/v1/stats，打印关键计数。"""
+    try:
+        payload = get_json("/api/v1/stats")
+    except ApiError as exc:
+        print(f"FAIL {base_url()} -> [{exc.code}] {exc}", file=sys.stderr)
+        raise SystemExit(1) from None
+
+    data = payload.get("data") or {}
+    print(
+        "OK {base} 档案 {photos} 用户 {users} 公司 {companies} 资讯 {news} 评论 {comments}".format(
+            base=base_url(),
+            photos=data.get("photos", "-"),
+            users=data.get("users", "-"),
+            companies=data.get("companies", "-"),
+            news=data.get("news", "-"),
+            comments=data.get("comments", "-"),
+        )
+    )
+
+
+def main() -> None:
+    """命令行入口：默认启动 stdio MCP 服务，支持 --selftest / --version。"""
+    args = set(sys.argv[1:])
+    if "--version" in args:
+        print(__version__)
+        return
+    if "--selftest" in args:
+        _selftest()
+        return
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()