使用说明内容（Markdown格式）

• 项目简介

  • Symbiote Lite Analyst MCP 服务器实现是一套后端服务，用于为大型语言模型客户端提供结构化的上下文服务。核心职责包括通过 MCP 边界安全地执行 SQL、分析查询并返回结构化结果，同时暴露分析工具以供 LLM 调用。

• 主要功能点

  • 提供 MCP 边界：将资源管理、工具执行与查询结果封装为统一的接口，面向 MCP 客户端提供 JSON-RPC 风格的请求和响应。
  • 两个 MCP 工具入口：
    • analyze_taxi_data：基于自然语言对 NYC 出租车数据进行分析的入口
    • execute_taxi_sql：在边界内执行只读 SELECT/WITH SQL，并返回结构化结果
  • 安全与合规性：
    • 通过 safe_select_only、detect_sql_injection 等机制保障 SQL 的只读性与防注入能力。
  • 组件分层与边界：
    • 欲通过 MCP 调用，需通过工具边界（DirectToolExecutor）执行 SQL，避免直接在代理中执行 SQL。
    • 提供 MCP 客户端适配层（MCPAgentAdapter），将外部请求路由至内部分析核心。
  • 服务入口与部署：
    • 代码中提供的 mcp_server.py 使用 FastMCP 搭建服务器，暴露 analyze_taxi_data 和 execute_taxi_sql 两个工具。

• 安装步骤

  • 环境准备
    • 需要安装 Python 运行环境，并安装依赖库（如 pandas、mcp、openai 等，详见项目的 environment.yml/Makefile/requirements）。
  • 获取代码
    • 将代码克隆到本地或服务器。
  • 安装依赖
    • 建议使用虚拟环境：创建并激活一个虚拟环境，然后安装项目依赖（可参考 repository 的环境配置文件）。
  • 启动 MCP 服务器
    • 使用命令运行入口：
      • python -m scripts.mcp_server
  • 可能的依赖与版本
    • mcp 库需可用且兼容当前脚本。
    • 运行前确保 Python 路径能找到脚本位置，以及所需的数据文件和数据库可访问。

• 服务器配置（MCP 客户端使用，示例为 JSON 结构，描述服务器的启动信息）

  • server_name: symbiote-lite
  • command: python
  • args: ["-m", "scripts.mcp_server"]
  • 说明：以上配置用于 MCP 客户端连接并启动服务器。server_name 对应服务器在 MCP 客户端中的标识，command/args 指定启动服务器的命令及参数。客户端通常只需要连接信息，不需要包含实现细节代码。

• 基本使用方法

  • 连接与调用
    • 启动后，MCP 客户端可通过 JSON-RPC 风格的请求，调用 analyze_taxi_data（NL 分析入口）与 execute_taxi_sql（SQL 执行入口）。
  • 常用工作流
    • 客户端将自然语言问题发送给服务器的 analyze_taxi_data，以获取分析计划和中间结果。
    • 客户端在获批后可调用 execute_taxi_sql 传入安全的 SELECT/WITH SQL，获取查询结果多列数据（rows、columns、row_count 等字段）。
  • 安全性
    • 服务器实现对可能的 SQL 注入进行检测，确保所有执行的查询为只读 SELECT/WITH，并对危险语句进行拦截。
  • 部署与扩展
    • 如需扩展工具入口，可以按照 mcp_server.py 的方式继续暴露额外的工具，或对现有工具进行授权与日志记录增强。