Vast Db Mcp

🚀 VAST 数据库 MCP 服务器实现说明

VAST 数据库 MCP 服务器实现了一系列数据库资源管理和操作功能，可通过 HTTP 请求对数据库架构、表进行查询和操作，还提供了交互式 SQL 执行工具。同时，文档介绍了与 AI 代理框架交互的注意事项、下一步计划、运行说明以及使用的注意事项。

🚀 快速开始

启动 MCP 服务

uvicorn fastapi_mcp.main:app --reload

示例请求

获取所有架构

curl http://localhost:8000/schemas

获取指定架构下的表

curl http://localhost:8000/schemas/my_schema/tables

获取表元数据

curl http://localhost:8000/schemas/my_schema/tables/my_table

获取表数据

curl http://localhost:8000/schemas/my_schema/tables/my_table/data

示例 SQL 查询

curl -X POST "http://localhost:8000/_api" \
-H "Content-Type: application/json" \
-d '{"name": "vast_sql_query", "params": {"sql": "SELECT * FROM my_table LIMIT 5", "format": "json"}}'

✨ 主要特性

1. 资源

a. 列出所有架构（schemas）

• 功能：显示数据库中所有的架构名称。
• 请求方式：GET /schemas
• 响应格式：JSON 数组，包含字符串类型的架构名。

b. 列出指定架构下的表（tables）

• 功能：根据提供的架构名，列出该架构下所有的表信息。
• 请求方式：GET /schemas/{schema_name}/tables
• 响应格式：JSON 数组，每个元素包含以下字段：
  • name：表的名称
  • type：表的类型（如：BASE TABLE）
  • schema：表所属的架构名

c. 获取表元数据

• 功能：根据提供的架构名和表名，返回该表的详细元数据。
• 请求方式：GET /schemas/{schema_name}/tables/{table_name}
• 响应格式：JSON 对象，包含以下字段：
  • name：表名称
  • type：表类型
  • schema：架构名
  • columns：列信息数组，每个列对象包含：
    • name：列名
    • type：数据类型
    • nullable：是否允许为空
    • default_value：默认值（如果存在）

d. 获取表数据

• 功能：根据提供的架构名和表名，返回该表的具体数据。
• 请求方式：GET /schemas/{schema_name}/tables/{table_name}/data
• 响应格式：JSON 数组，每个元素对应一行数据，字段与元数据中的列信息一致。

2. 工具

a. 基于查询的交互式 SQL 执行工具

• 功能：允许通过提供 SQL 查询语句来执行任意数据库操作，并支持指定输出格式。
• 名称：vast_sql_query
• 参数：
  • sql：需要执行的 SQL 查询字符串
  • format：输出格式，可选值为 json 或 csv

📚 详细文档

与 AI 代理框架交互注意事项

提示词/配置

• 在系统提示或配置中必须包含对可用资源和工具的描述（类似“实现的 MCP 特性”部分）。
• 由于 MCP 缺乏标准发现机制，需要显式列出所有 URI 和工具名称及其功能。

身份验证处理

⚠️ 重要提示

绝对不要在发送给 LLM 的提示中包含 VAST 数据库凭证。

• 资源请求：

  • 当 LLM 生成目标 URI 后，由 orchestrator（运行代理逻辑的代码，而非 LLM）负责：
    • 安全加载存储的凭证
    • 构建 headers 字典：{'X-Vast-Access-Key': '...', 'X-Vast-Secret-Key': '...'}。
    • 将 vast:// URI 映射到实际运行中的 MCP 服务器 HTTP URL（例如 http://localhost:8088/）。
    • 使用 MCP 客户端或标准 HTTP 客户端发送 GET 请求，同时传递构建的 headers。

• 工具使用：

  • 当 LLM 决定使用 vast_sql_query 工具并提供 sql 和 format 参数时，由 orchestrator 负责：
    • 安全加载存储的凭证
    • 构建上述 headers 字典，并将其注入到工具执行函数的参数中。LLM 不应自动生成 headers。

请求构造

• LLM 需要生成正确的 URI 路径参数和查询参数。
• 由 LLM 生成 sql 和 format 参数用于工具调用。

响应处理

• 客户端代理代码需要处理不同的响应 MIME 类型（例如 text/plain, application/json, text/csv）。
• 必须检查 HTTP 状态码（特别是资源请求中），以检测错误（如 401, 404, 500, 503）。
• 需要从响应正文解析错误信息（纯文本或 JSON），并可能向用户报告或用于重试/备用操作。

下一步计划

• 实现健壮的日志记录。(完成)
• 添加单元测试。(完成)
• 精细调整输出格式。(完成 - 提供 JSON 与 CSV 选项)
• 增强错误处理机制。(完成)
• 完善文档编写与示例。(进行中)

📄 许可证

文档未提及相关许可证信息。

🔧 注意事项

⚠️ 重要提示

• 所有 API 请求均需包含认证 headers。
• 敏感操作需进行适当的权限控制与日志记录。