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

实现的 MCP 功能特性

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 代理框架交互注意事项

1. 提示词/配置

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

2. 身份验证处理

   注意: 绝对不要在发送给 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。

3. 请求构造

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

4. 响应处理

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

下一步计划

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

运行说明

启动 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"}}'

注意事项

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