Supertable MCP 服务端
使用说明（Markdown 格式）
-
项目简介
- 该仓库实现了一个基于 MCP 的后端服务器，核心职责是向 LLM 客户端提供统一的上下文载体：托管与管理资源、注册与执行工具、定义与渲染 Prompt 模板。通过 JSON-RPC 2.0 与客户端进行通信，支持stdio（本地进程间通信）与 streamable-http（远程 HTTP 传输）两种传输方式，并提供会话管理、能力声明和多种传输协议的支持，确保对 LLM 应用的安全、可扩展性。
-
主要功能点
- MCP 核心协议实现与 JSON-RPC 交互：服务器端解析请求、返回响应、支持健康、信息、用户鉴权以及工具调用等能力。
- 资源、表和快照管理：提供数据资源的查询、描述、统计等能力，支持对表格快照（快照存储在对象存储）进行读取与描述。
- 工具（Tools）注册与执行：实现 health、info、whoami、list_supers、list_tables、describe_table、get_table_stats、get_super_meta、query_sql 等工具接口。
- 安全与鉴权：可选 TOKEN、explicit user_hash 等策略，并在 MCP 端进行参数校验与访问控制。
- 传输协议支持：stdio（本地子进程通信）与 streamable-http（HTTP 远程端点，带 SSE 推送）的实现与切换。
- 客户端示例与集成：包含 Web UI、Claude Desktop/CLI 交互的对接示例，以及一个 REST API 封装层。
-
安装与运行步骤
- 基本运行（stdio 形式，开发模式）：
- 启动 MCP 服务器：直接运行 python -u supertable/mcp/mcp_server.py
- 客户端连接：使用支持 MCP 的客户端工具，配置 server 为上述启动命令所对应的参数与路径（客户端将使用 stdio 与服务器对话）。
- 使用 Docker 及 Profile（参考仓库 README 的 Quick Start）：
- 克隆仓库并进入项目根目录。
- 使用 docker compose 启动 MCP 服务器及相关服务（如 Redis、MinIO 等按需 profile 匹配 infra/admin/mcp）。
- 服务器配置（示例，以下为描述性 JSON 配置，非代码块）：
{
"server_name": "supertable-mcp",
"command": "python",
"args": ["-u", "supertable/mcp/mcp_server.py"],
"transport": "stdio",
"auth_token": "<替换为强随机字符串>",
"organizations": "<组织名称，例如kladna-soft>",
"notes": "MCP 服务器默认使用 stdio 传输，若需远程化加上 streamable-http 配置及 HTTP 主机/端口。"
}
注释：
- server_name：服务名，用于客户端识别与日志区分。
- command / args：启动 MCP 服务器所需的启动命令及参数，建议以“python -u 路径/mcp_server.py”形式运行。
- transport：传输协议，stdio 代表本地进程间通信，streamable-http 则通过 HTTP 远端调用。
- auth_token：用于工具调用的鉴权 TOKEN，按需求在客户端与服务器侧开启并轮换。
- 组织名称：用于多租户隔离的组织标识。
- 基本使用方法
- 服务器启动后，客户端需要提供以下关键信息来建立连接：
- 服务器启动命令及路径（如上 JSON 配置所示）。
- 认证信息（如 TOKEN）及需要的用户哈希 user_hash（若配置要求显式哈希）。
- 指定连接方式（stdio 或 streamable-http），以及在需要时的端点路径和鉴权信息。
- 客户端常见操作包括：
- health、info、list_supers、list_tables、describe_table、get_table_stats、get_super_meta、query_sql 等工具调用。
- 通过 query_sql 执行 SQL，并按返回的列与行进行可视化展示。
- 远程连接时可使用 SSE/HTTP 传输进行实时流式输出。
- 服务器启动后，客户端需要提供以下关键信息来建立连接：
- 基本运行（stdio 形式，开发模式）：
-
基本使用方法（实操要点）
- 启动 MCP 服务器后，选择合适的 MCP 客户端（如 Claude Desktop、FastAPI Web UI、或自建前端），并确保客户端的配置指向 MCP 服务器的启动命令及参数（详见上方配置信息）。
- 客户端需要在请求中携带 user_hash（若服务器策略要求），以及可选的 auth_token。
- 使用 Health/Info 进行自检，获取服务器能力与状态。随后可按需使用 list_supers、list_tables、describe_table、get_table_stats、get_super_meta、query_sql 等接口完成数据查看与查询。
- 若需要在云端场景中使用，确保传输通道（streamable-http）及鉴权策略的正确配置，并按照 README 的生产化部署建议执行。