内容
# grand-lyon-mcp
[](https://github.com/ThomasCrouzet/mcp-grand-lyon/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
**法语** | [英语](#english)
本地 **MCP** 服务器，聚合 **里昂大都会** 的开放数据，提供 **10 个只读业务工具**。可与任何stdio MCP客户端（Claude Desktop, Cursor, 自定义代理）配合使用。
> DataGrandLyon的标识 **从不** 被版本控制、记录或由工具返回。
## 功能
- TCL的下一班车（实时 + 理论GTFS）
- 警报 / 移动性 / 无障碍
- Vélo’v + 本地历史
- 停车场和P+R
- 交通和道路事件
- 设备（厕所、喷泉、公园……）
- 环境（可选指标）
- 垃圾分类 + 垃圾处理
- 行程选项比较
- 可配置的个人简报
## 架构
```text
MCP适配器 → 应用服务 → 领域协议 → 提供商 → HTTP / SQLite
```
业务代码不导入MCP SDK（`adapters/mcp/`）。
## 要求
- Python ≥ 3.12
- [uv](https://docs.astral.sh/uv/)
- [DataGrandLyon](https://data.grandlyon.com/) 账户（可选：无账户 → 离线模式/固定数据）
## 安装
### 推荐助手
```bash
git clone git@github.com:ThomasCrouzet/mcp-grand-lyon.git
cd mcp-grand-lyon
make setup # TUI交互式（如果有gum，则使用gum，否则使用提示）
# 或无交互：
make setup-offline # 固定数据，无需账户
```
助手将机密写入`secrets.env`（chmod 600），复制YAML配置文件，安装依赖，迁移SQLite，并启动`doctor`。
> **根据操作系统存储机密的路径**（由[platformdirs](https://pypi.org/project/platformdirs/)解决）：
> - Linux：`~/.config/grand-lyon-mcp/secrets.env`
> - macOS：`~/Library/Application Support/grand-lyon-mcp/secrets.env`
> - Windows：`%APPDATA%\grand-lyon-mcp\secrets.env`
>
> `grand-lyon-mcp env`显示您机器上的实际路径。您也可以通过`GRAND_LYON_MCP_CONFIG_DIR`强制指定目录。
### 手动安装
```bash
uv sync --all-extras --dev
cp .env.example "$(uv run grand-lyon-mcp env --config-dir)/secrets.env"
# 编辑：DATAGRANDLYON_USERNAME / PASSWORD，然后chmod 600
make migrate
```
变量：参见`.env.example`。Makefile自动加载`secrets.env`和本地`.env`。
```bash
make help # 所有目标
make env # 配置状态（隐藏机密）
make serve OFFLINE=true LOG_LEVEL=DEBUG
make client-config # JSON块的mcpServers（绝对路径）
```
## 配置
配置文件模板（`settings`, `sources`, `profiles`, `waste-taxonomy`）**随软件包提供** (`grand_lyon_mcp/_data/config/`). 助手将它们复制到您的配置文件目录：
```bash
grand-lyon-mcp setup # 复制YAML + 迁移（或：make setup）
```
要检查或手动重新配置打包的模板：
```bash
python -c "from grand_lyon_mcp.resources import config_dir; print(config_dir())"
```
## 迁移和数据
```bash
uv run grand-lyon-mcp db migrate
uv run grand-lyon-mcp db info
uv run grand-lyon-mcp doctor
uv run grand-lyon-mcp catalog scan
uv run grand-lyon-mcp catalog validate
uv run grand-lyon-mcp sync gtfs
# 离线GTFS：
uv run grand-lyon-mcp sync gtfs --from-file tests/fixtures/gtfs/mini_gtfs.zip
uv run grand-lyon-mcp snapshot velov
```
## 启动MCP（stdio）
```bash
uv run grand-lyon-mcp serve --transport stdio
# 或
./scripts/run_mcp.sh
```
`stdout`仅用于MCP协议；应用程序日志输出到**stderr**。
## 连接MCP客户端
服务器通过**stdio**使用MCP协议：它与任何兼容的客户端一起工作。使用`make client-config`获取一个可以直接粘贴的块（绝对路径）：
```bash
make client-config # 或：uv run grand-lyon-mcp client-config
```
**Claude Desktop** 配置示例（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"grand-lyon": {
"command": "/绝对路径/mcp-grand-lyon/scripts/run_mcp.sh",
"args": ["serve", "--transport", "stdio"]
}
}
}
```
包装器`scripts/run_mcp.sh`加载`secrets.env`并在没有凭证的情况下切换到离线模式。相同的块适用于Cursor和其他stdio MCP客户端。详细信息和替代方案（继承的环境，机密）：[`docs/mcp-clients.md`](docs/mcp-clients.md).
## MCP工具（10个）
| 工具 | 角色 |
|-------|------|
| `lyon_resolve_place` | 地点解析（地址，站点，站，个人地点） |
| `lyon_next_departures` | TCL下一班车 |
| `lyon_mobility_status` | 警报和交通 |
| `lyon_trip_options` | 模式比较 |
| `lyon_parking_options` | 停车场 / P+R |
| `lyon_accessibility_check` | 无障碍 |
| `lyon_nearby_facilities` | 设备 |
| `lyon_environment_brief` | 环境 |
| `lyon_waste_dropoff` | 垃圾 |
| `lyon_personal_briefing` | 个人简报 |
没有管理员工具 / 原始DataGrandLyon查询暴露。详细参数和输入/输出示例：[`docs/tools.md`](docs/tools.md).
示例 - `lyon_next_departures`：
```jsonc
// 输入
{ "stop": { "query": "Bellecour" }, "line": "A", "limit": 3 }
// 输出（信封摘录）
{
"status": "ok",
"data": { "departures": [
{ "line_name": "A", "destination": "Vaulx-en-Velin La Soie",
"expected_at": "2026-07-20T08:05:00+02:00", "realtime": true }
] },
"sources": [ { "provider": "DataGrandLyon", "attribution": "SYTRAL Mobilités", "realtime": true } ]
}
```
## 测试
```bash
make quality
# 或
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -m "not live" --cov
```
实时测试：`RUN_LIVE_TESTS=1` + 凭证。默认套件**无需网络或凭证**即可运行。
## 文档
| 文档 | 内容 |
|-----|---------|
| [`docs/architecture.md`](docs/architecture.md) | 架构 |
| [`docs/tools.md`](docs/tools.md) | 10个MCP工具（参数，示例） |
| [`docs/mcp-clients.md`](docs/mcp-clients.md) | MCP客户端配置 |
| [`docs/data-sources.md`](docs/data-sources.md) | 来源和许可证 |
| [`ATTRIBUTIONS.md`](ATTRIBUTIONS.md) | 开放数据归属和依赖 |
| [`docs/operations.md`](docs/operations.md) | 操作 |
| [`docs/troubleshooting.md`](docs/troubleshooting.md) | 故障排除 |
| [`docs/adr/`](docs/adr/) | 架构决策 |
## 限制（v0.1）
- 可选的Transitous（功能标志）；没有路由器，`lyon_trip_options`仍然是TCL的部分内容。
- 仅当解析源时才激活环境指标。
- 不包括MCP HTTP传输（仅stdio）。
## 隐私 / GDPR
- **100% 本地，无任何遥测**。服务器在您的机器上运行；配置文件（家/工作），简报和Vélo’v历史记录保留在本地SQLite数据库中。
- **离开机器的内容**（仅在实时模式下）：必要查询和坐标用于地理编码和路线计算发送到相关服务（DataGrandLyon，Photon实例，Transitous如果激活），受其自身政策的约束。
- 示例配置文件（`profiles.example.yaml`）仅使用通用位置（Bellecour，Lyon 3ᵉ）- 没有实际个人数据被版本控制。
## 许可证和归属
代码在 **MIT** 许可证下（参见 [`LICENSE`](LICENSE)）。数据来自第三方来源，具有其自身的许可证和归属义务 - 参见 [`ATTRIBUTIONS.md`](ATTRIBUTIONS.md) 和 [`docs/data-sources.md`](docs/data-sources.md).
> **独立项目**，与里昂大都会，SYTRAL Mobilités，Keolis-TCL或JCDecaux无关。“TCL”，“Vélo'v”等名称是其各自所有者的商标，仅在此用于描述。
---
<a id="english"></a>
## English
本地 **MCP** 服务器，聚合 **Métropole de Lyon** 开放数据，提供 **10 个只读业务工具**。可与任何stdio MCP客户端（Claude Desktop, Cursor, 自定义代理）配合使用。
### 安装
```bash
uv sync --all-extras --dev
uv run grand-lyon-mcp db migrate
uv run grand-lyon-mcp doctor
uv run grand-lyon-mcp serve --transport stdio
```
凭证仅通过环境变量（`DATAGRANDLYON_USERNAME` / `DATAGRANDLYON_PASSWORD`）提供 - 绝不提交，记录或由工具返回。应用程序日志输出到 **stderr**；**stdout**仅用于MCP协议。无需凭证运行 → 离线模式（固定数据）。
### 连接客户端
使用`make client-config`获取一个可以直接粘贴的`mcpServers`块（绝对路径）。参见 [`docs/mcp-clients.md`](docs/mcp-clients.md).
### 质量门控
```bash
uv run ruff format --check . && uv run ruff check . && uv run mypy src
uv run pytest -m "not live" --cov
```
### 文档和许可
架构，工具，数据源/许可证，操作和故障排除在`docs/`下。归属在 [`ATTRIBUTIONS.md`](ATTRIBUTIONS.md). 代码是MIT；数据归属于其各自提供者。独立项目，与里昂大都会，SYTRAL，Keolis-TCL或JCDecaux无关。
