车辆代理MCP

通过汽车搜索系统 模型上下文协议（MCP）具有 STDIO 服务器/客户端、逼真的数据种子和终端中的对话代理。设计用于技术评估，并作为更复杂的MCP代理的基础。

快速查看

通过 MCP 工具查询 SQLite 中的车辆（search_vehiclesCLI永远不会直接进入银行。
确定性种子 100+车辆 现实主义（假货+市场规则）。
通过离线LLM启发式备份分析自然语言过滤器。
端到端测试流（种子，搜索和代理对话框）。
最小的堆栈，没有强制性的外部依赖关系。

核心技术

Python 3.10+
MCP-SDK (mcp[cli])服务器/客户端STDIO
SQLAlchemy 2.x 对位ORM e模式
Pydantic 2 + 媒染剂设置 用于验证和设置
伪造者 用于数据生成
富有的 对于非终端用户
Pytest/Pytest异步 睾丸旁

文件夹结构

Vehicle-Agent-MCP/
  src/
    cli/           # agente conversacional de terminal
    db/            # engine, sessão e seed do SQLite
    domain/        # enums, esquemas Pydantic e modelos SQLAlchemy
    llm/           # interface de LLM + providers (offline/HTTP/OpenAI compat)
    mcp_server/    # servidor MCP expondo a tool search_vehicles
    mcp_client/    # client que inicia o server via STDIO
  tests/           # cenários cobrindo seed, filtros e diálogo
  data/            # banco SQLite gerado pelo seed

先决条件

python 3.10+
诗歌（推荐）或 venv + pip
能够编译原生依赖关系的 shell 访问（Linux/macOS 中的默认）

一步一步：从零到旋转

选项 1（推荐）：Docker with Postgres

克隆仓库并进入文件夹：

git clone https://github.com/LuccaGianKolenez/Vehicle-Agent-MCP.git
cd Vehicle-Agent-MCP

复制O .env 举个例子。服务的 Postgres URL db 已经准备好在 DB_URL_DOCKER （它优先于 DB_URL_LOCAL那么容器将始终使用Postgres：

cp .env.example .env

全部上传（API + Postgres + 自动种子）：

 docker compose up --build

检查它是否健康和可测试：

docker compose ps
curl http://localhost:${API_PORT:-8000}/health

打开交互式文档（Swagger UI）以在不离开浏览器的情况下测试路线：

   open http://localhost:${API_PORT:-8000}/docs  # macOS
   # ou
   xdg-open http://localhost:${API_PORT:-8000}/docs  # Linux

（如果需要的话，JSON 规范是 /openapi.json).

通过REST搜索示例：

curl -X POST "http://localhost:${API_PORT:-8000}/search" \
  -H "Content-Type: application/json" \
  -d '{"brand": "Honda", "price_max": 120000}'

需要重置吗？停止并删除数据卷：

docker compose down -v

选项 2：本地环境（无 Docker）

克隆仓库并进入文件夹：

git clone https://github.com/LuccaGianKolenez/Vehicle-Agent-MCP.git
cd Vehicle-Agent-MCP

选择并创建 Python 环境：

诗歌（推荐）：

  poetry install --with dev

venv+点：

  python -m venv .venv
  source .venv/bin/activate  # Windows: .venv\Scripts\activate
  pip install -e .

复制O .env默认情况下，应用程序使用 DB_URL_LOCAL （SQLite）如果不在 Docker 中：

cp .env.example .env

创建初始种子（ generate） data/vehicles.db 有100多个记录：

poetry run python -m src.db.seed

运行 CLI 或 API：

# CLI MCP conversacional
poetry run python -m src.cli.main

# ou API FastAPI em modo dev
poetry run uvicorn src.rest.api:app --reload

测试本地 API ：

curl -X POST http://127.0.0.1:8000/search \
  -H "Content-Type: application/json" \
  -d '{"brand": "Toyota"}'

您想通过浏览器进行测试吗？打开 Swagger UI：

open http://127.0.0.1:8000/docs  # macOS
# ou
xdg-open http://127.0.0.1:8000/docs  # Linux

JSON 模式可在 http://127.0.0.1:8000/openapi.json.

如何通过DBeaver检查Docker的Postgres

使用以下值在 DBeaver 中创建新的 PostgreSQL 连接 docker compose up 正在旋转：

主持人： localhost
端口： ${PG_PORT:-5432} （或发布于 .env)
数据库： vehicles
用户： postgres
密码： postgres
司机： PostgreSQL （DBeaver 标准）

如果更改发布到的端口 .env只调整字段端口在连接中。

DBeaver 中没有表格？

确保容器在空气中且健康：

   docker compose up -d
   docker compose ps

在API容器中重新运行种子（它创建架构并填充虚拟数据）：

   docker compose exec api python -m src.db.seed

确认表格是否直接存在于 Postgres 中：

   docker compose exec db psql -U postgres -d vehicles -c "\\dt"

该命令必须将表格列为 vehicles e vehicle_features 无架构 public.

无DBeaver，自然化/刷新架构 public 播种后。如果您连接到错误的银行（例如， postgres）调整字段 数据库 段落 vehicles e确认。

环境变量

复制示例并进行必要的调整：

cp .env.example .env

主键（优先级： DB_URL > DB_URL_DOCKER > DB_URL_LOCAL >默认SQLite）：

DB_URL_LOCAL –默认值 sqlite:///data/vehicles.db 供当地使用
DB_URL_DOCKER –默认值 postgresql+psycopg://postgres:postgres@db:5432/vehicles 服务使用 api Docker编写
DB_URL – 可选手动覆盖高级场景
API_PORT / PG_PORT 可选发布容器端口（如果已经使用 8000/5432）
LLM_PROVIDER – none （离线启发式）， mock_http 或 openai_compat
LLM_API_KEY / LLM_MODEL 仅供外部提供商使用

可选的 AWS 集成

AWS_REGION 按钮使用的区域3（例如： us-east-1).
AWS_EXPORT_BUCKET – 如果定义，则由端点生成的导出 /export 并且通过 CLI 被发送到这个带有密钥的桶 exports/{dataset_hash}/{timestamp}_ 并返回 s3_location + download_url （主持）。
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 可选的；如果没有通知，boto3 使用默认的本地/链配置文件。
LLM_PROVIDER=bedrock –编织或供应商 BedrockLLM （美国客户 bedrock-runtime 按钮3）。如果没有有效的凭据，则会恢复为默认行为。

Política建议使用S3铲斗

如果您使用导出到 S3 的功能，请对存储桶应用最小策略（根据需要替换名称）：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::vehicle-agent-exports/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": "arn:aws:s3:::vehicle-agent-exports"
        }
    ]
}

种子银行

创建方案并填充虚拟车辆：

poetry run python -m src.db.seed

脚本保证 >=100条记录应用约束/索引，并且可以安全地重新运行。

快速执行

非终端交互代理（启动客户端+服务器MCP）：

  poetry run python -m src.cli.main

例如：“我正在寻找高达12万辆自动SUV”，“Honda 2019 to 2022 flex”。

隔离 MCP 客户端（手动测试）：

  poetry run python -m src.mcp_client.client

如何使用（一步一步）

1）会话CLI

确保银行已被种植（运行一次）：

   poetry run python -m src.db.seed

启动或代理：

   poetry run python -m src.cli.main

正常说话。当显示结果时，代理会询问您是否要导出：

- 逗号分隔值 或 镶木地板: 写入 exports/ （自动创建）并指定路径。硒 AWS_EXPORT_BUCKET 如果设置完毕，文件也会发送到 S3，并显示 URL。 - api/rest：将无终端有效载荷JSON打印到consumo。 - n不要导出。

2） API REST

上传服务器（ FastAPI）：

   poetry run uvicorn src.rest.api:app --reload

测试主要路线：

- 搜索：

     curl -X POST http://127.0.0.1:8000/search \
       -H "Content-Type: application/json" \
       -d '{"brand": "Honda", "price_max": 120000}'

- 导出（生成文件并通过 HTTP 下载）：

     curl -X POST "http://127.0.0.1:8000/export?format=csv" \
       -H "Content-Type: application/json" \
       -d '{"brand": "Toyota"}' --output resultados.csv

健康检查 Health Check GET /health.
直接通过 Swagger UI 浏览和执行呼叫 GET /docs （ou /openapi.json 纯粹的规格）。

2.1 邮递员收藏

金额 postman/vehicle-agent.postman_collection.json 没有邮递员。
保持变量 baseUrl 指向服务器（默认） http://localhost:8000).
使用已填写的身体示例进行测试 /search e /export 快速。

3）数据库和池

使用 DB_URL 手动覆盖或离开 DB_URL_DOCKER/DB_URL_LOCAL 自动从 Docker 或本地 SQLite 获取 Postgres（例如： postgresql+psycopg://user:pass@host:5432/db).

连接池已配置（QueuePool 包括 pre-ping、overflow 和 timeout）对于本地SQLite没有变化。

对于 Postgres 来说，引导是自动的：如果数据库不存在，引擎将通过连接到 postgres也适用 statement_timeout de 5s， timezone=UTC e pool_use_lifo 减少竞争工作负载的延迟。

3.1 如何在实践中使用Postgres

确保 URL 指向目标银行，并且用户有权 创建数据库 连接到维护基地时（postgres）。使用 Docker 的本地示例：

   export DB_URL="postgresql+psycopg://postgres:postgres@localhost:5432/vehicles"
   docker run --rm -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16

正常旋转种子（ R）python -m src.db.seed).O助手 ensure_postgres_database 检测缺少数据库 vehicles创建与 CREATE DATABASE 然后重新使用原始URL上传引擎。
像往常一样上传 CLI 或 API。所有查询继承相同的生产调整： statement_timeout=5s, timezone=UTC, pool_pre_ping=True e pool_use_lifo=True （当有多个同时请求时，延迟较低）。
如果您需要指向一个没有创建数据库权限的托管集群，请手动创建数据库，并保持其余的不变 - 助手会检测到其存在，而不会尝试重新创建。

3.2）通过 Docker 运行所有内容

创建您的 .envCompose 已注入 DB_URL_DOCKER 指向服务 db (postgresql+psycopg://postgres:postgres@db:5432/vehicles).
构建和上传服务（Postgres + API）：

   docker compose up --build

检查一切是否正常（compose 已经等待 Postgres 并执行 API 的健康检查）：

   docker compose ps
   docker compose logs -f api
   curl http://localhost:${API_PORT:-8000}/health

API容器在启动FastAPI之前自动运行种子 http://localhost:${API_PORT:-8000}.
要清理环境，请停止服务并删除数据卷：

   docker compose down -v

3.2.1）端口和覆盖

API端口：可变 API_PORT 不 .env （默认值 8000）。如果有东西在 8000 上运行，请定义 API_PORT=8080 然后再次上升。
Postgres 端口：可变 PG_PORT 不 .env （默认值 5432）。如果您已经有另一个本地 Postgres 在运行，则很有用。
Postman 默认 URL （baseUrl）必须反映已配置的端口（例如： http://localhost:8080).

3.2.2）有用的命令（诊断）

仅在更改代码后重新启动 API：

  docker compose build api && docker compose up -d api

如果您想要更新数据，手动运行种子（无关紧要）：

  docker compose exec api python -m src.db.seed

检查 Postgres 数据库是否已创建并且可访问：

  docker compose exec db pg_isready -U postgres -d vehicles

自动化测试

poetry run pytest -q

涵盖最小种子，工具过滤器和确定性LLM对话流。

建筑流程

Usuário → Agente CLI → MCP Client → (STDIO) → MCP Server → SQLite

通过MCP隔离可以轻松切换后端（PostgreSQL，HTTP API等），同时保持CLI完整。

模式和高级提示

LLM的提供者是注射； LLM_PROVIDER=none 使用稳定的离线启发式进行测试。
一个工具 search_vehicles 接受多个过滤器（品牌，年份，燃油，变速箱，价格，车身类型，公里等）。
过滤器解析器是确定性的，允许可靠的测试快照。
种子美国 faker.Vehicle 对价格/年/燃料的一致性进行调整。
在模块中构建新的 MCP 提供程序 mcp_server 重新使用现有合同。
CLI与银行的所有通信都通过MCP服务器进行，这对审计和安全非常有用。
索引和限制 Vehicle 按品牌/年份/价格范围优先进行搜索。
该项目完全脱机运行；外部凭据是可选的评估。
调整 data/ 不 .gitignore 如果你想修改演示银行。

额外功能

直接导出结果到 CSV或拼花地板 通过 CLI，或通过新编程消费 API REST (uvicorn src.rest.api:app --reload).
支持 PostgreSQL 可配置为 DB_URL （或自动通过 DB_URL_DOCKER 没有作曲），com 连接池 用于生产的标准。
结果由 语义相似性 考虑过滤器（品牌/型号）和 用户配置文件 可选的。

常见问题及如何解决

端口 8000 或 5432 已在使用中：默认值 API_PORT 或 PG_PORT 不 .env e骑马 docker compose up -d 再一次。
在 Postgres 中创建数据库失败检查用户是否有权 CREATE DATABASE 或创建基础 vehicles 手动；或者帮助 ensure_postgres_database 不要重复命令，如果基础已经存在。
API扫描电镜响应器ao健康检查：骑马 docker compose logs -f api 检查种子是否已完成。容器在发生故障时自动重新启动。
有无效数据的旧卷清洁 com docker compose down -v 然后再上去。
导出为 CSV/Parquet 出错 Docker 之外：确保 pandas e pyarrow 已安装（poetry install --with dev).

数据质量的想法

合同验证创建合同测试 pytest 和 Pydantic/Pandera 保证价格范围/年，允许燃料，最小里程和没有 null 在关键领域。
种子完整性检查：在坚持之前，车轮声称的唯一性（板/VIN），之间的一致性 year e price除了规则之间的一致性 fuel_type e transmission.
自动分析: 使用添加笔记本或脚本 pandas-profiling/ydata-profiling 生成 HTML 报告 vehicles.db，有助于检测异常值或新种子后破碎的分布。
生产监控导出质量指标（有效日志的百分比，丢弃的行，重复）到结构化日志或Prometheus；如果低于设定的门槛。
审计和可追溯性：包括列 created_at/source 并记录导出的数据集的哈希值，以便能够重现搜索并调查数据差异。

如何验证质量（本地和Docker）

合同 + 指标: poetry run python -m src.db.quality --fail-under 0.98 （当地）ou docker compose run --rm api python -m src.db.quality --fail-under 0.98 （使用 Compose 的 Postgres）。命令记录总计数，有效，无效，重复和 dataset_hash 副礼堂。
分析HTML: poetry run python -m src.db.quality --profile-html data/reports/vehicles-profile.html 生成数据分析报告；没有 Docker，使用 docker compose run --rm -v $PWD/data:/app/data api python -m src.db.quality --profile-html data/reports/vehicles-profile.html 将 HTML 保存到 data/reports.
可追踪导出每个 CSV/Parquet 导出都会生成一个 .meta.json 与旁边 dataset_hash列和 created_at这有助于比较不同回合或环境的结果。

快速笔记

我更喜欢保持字符串干净：在播放解析器之前将重音和特殊字符标准化，以便过滤器更准确。
使用价格/年/公里的数字转换器保持在十进制/浮点一致，避免格式意外。
当我没有LLM时，离线启发式解决了对话的基本问题，并优先考虑非常明确的过滤器。
邮递员的收藏已经涵盖了健康，搜索和出口；我只指出 baseUrl 快速测试。
REST API 接受与 CLI 相同的有效负载，因此在终端和 HTTP 之间切换而不会重写任何内容。
我可以直接将搜索导出为CSV或Parquet，或者拖动 /export 并在客户端保存。

Vehicle Agent MCP

快速接入

详细介绍

车辆代理MCP

快速查看

核心技术

文件夹结构

先决条件

一步一步：从零到旋转

选项 1（推荐）：Docker with Postgres

选项 2：本地环境（无 Docker）

如何通过DBeaver检查Docker的Postgres

DBeaver 中没有表格？

环境变量

可选的 AWS 集成

Política建议使用S3铲斗

种子银行

快速执行

如何使用（一步一步）

1）会话CLI

2） API REST

2.1 邮递员收藏

3）数据库和池

3.1 如何在实践中使用Postgres

3.2）通过 Docker 运行所有内容

3.2.1）端口和覆盖

3.2.2）有用的命令（诊断）

自动化测试

建筑流程

模式和高级提示

额外功能

常见问题及如何解决

数据质量的想法

如何验证质量（本地和Docker）

快速笔记

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

Vehicle Agent MCP

快速接入

详细介绍

车辆代理MCP

快速查看

核心技术

文件夹结构

先决条件

一步一步：从零到旋转

选项 1（推荐）：Docker with Postgres

选项 2：本地环境（无 Docker）

如何通过DBeaver检查Docker的Postgres

DBeaver 中没有表格？

环境变量

可选的 AWS 集成

Política建议使用S3铲斗

种子银行

快速执行

如何使用（一步一步）

1） 会话CLI

2） API REST

2.1 邮递员收藏

3） 数据库和池

3.1 如何在实践中使用Postgres

3.2） 通过 Docker 运行所有内容

3.2.1） 端口和覆盖

3.2.2）有用的命令（诊断）

自动化测试

建筑流程

模式和高级提示

额外功能

常见问题及如何解决

数据质量的想法

如何验证质量（本地和Docker）

快速笔记

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1）会话CLI

3）数据库和池

3.2）通过 Docker 运行所有内容

3.2.1）端口和覆盖