Soccer Graph Analytics MCP 服务器
使用说明（Markdown 格式）
- 项目简介
- 该仓库实现了一个基于 MCP（Model Context Protocol）的后端服务器，专注于通过图分析方式对足球知识图谱进行查询与推理。服务器提供对图数据的资源访问、5 种图分析工具以及对外部工具的注册调用能力，并支持通过 STDIO 方式的 MCP 交互以及可选的 HTTP(S) 服务端口（SPCS 端点）供 Snowflake Containers 服务调用。
- 主要功能点
- MCP 核心能力：处理 MCP 请求与响应，暴露工具集、资源访问与分析能力，支持会话管理与可扩展性。
- 资源与工具：通过嵌入的工具集合实现图路径查找、中心性分析、社区检测、传递网络分析、时间序列分析等图分析工具。
- 数据加载与网络构建：从静态 JSON 数据加载知识图数据，使用 NetworkX 构建玩家网络、俱乐部网络等图结构。
- 图分析工具（5 套工具）：
- graph_shortest_path、graph_centrality_analysis、graph_community_detection、graph_transfer_network_analysis、graph_temporal_analysis
- HTTP endpoints（SPCS）：提供短路径、社区检测、中心性、转移网络、时序分析等功能的 HTTP 接口以便 Snowflake SPCS 调用。
- 数据预加载选项：可在启动时通过 PRELOAD_ON_STARTUP 环境变量预加载数据与建立网络。
- 部署与运行方式：支持 STDIO 方式的 MCP 服务运行，以及可选的基于 HTTP 的 SPCS 部署脚本和容器化部署（Dockerfile、SPCS 部署指南）。
- 安装步骤
- 安装依赖
- 该项目在 mcp_server/ 下有 requirements.txt，包含 Python 环境所需的依赖包（包括 mcp、Flask、pandas、networkx 等）。建议在虚拟环境中安装：
- 运行：pip install -r mcp_server/requirements.txt
- 该项目在 mcp_server/ 下有 requirements.txt，包含 Python 环境所需的依赖包（包括 mcp、Flask、pandas、networkx 等）。建议在虚拟环境中安装：
- 运行服务器（STDIO 模式，默认）
- 在仓库根目录执行：python3 mcp_server/soccer_mcp_server.py
- 服务器将自动以 STDIO 方式启动 MCP 服务（默认 transport 为 stdio），可通过环境变量调整为 http 模式。
- 使用 SPCS 部署（可选）
- 如需通过 Snowflake Container Services 部署图分析服务，请参考 mcp_server/SPCS_DEPLOYMENT_GUIDE.md 与 deploy_spcs.sh、Dockerfile 等文件进行镜像构建、服务部署与 Snowflake 端的函数绑定。
- 数据与模型
- 图数据由 graph_data 下的静态 JSON 文件提供，运行时会被加载并构建为 NetworkX 图。
- 安装依赖
- 服务器配置（MCP 客户端需要的配置信息，JSON 格式，服务器名称、启动命令及参数）
- server_name: soccer-graph-analytics
- command: python3
- args: ["mcp_server/soccer_mcp_server.py"] 注释说明：
- server_name 指定 MCP 服务端的唯一名称，客户端在建立连接时可按该名称识别。
- command 与 args 指定启动服务的命令（在仓库根目录执行时的常用组合为：python3 mcp_server/soccer_mcp_server.py）。
- 实际连接时，MCP 客户端仅需要读取上述字段并据此启动并连接到该 MCP 服务端的 STDIO 通道；若以 HTTP/SPCS 方式部署，请按相应部署指南配置。
- 基本使用方法
- 启动后，MCP 客户端通过制定的 transport（默认 STDIO）与服务器进行 JSON-RPC 交互，调用以下工具：
- graph_shortest_path(source_id, target_id, graph_type)
- graph_centrality_analysis(graph_type, analysis_type, top_n)
- graph_community_detection(graph_type)
- graph_transfer_network_analysis(club_id, player_id, start_date, end_date)
- graph_temporal_analysis(time_range, analysis_type)
- 验证与测试建议
- 以 STDIO 启动后，向客户端发送规范的 MCP 请求，测试短路径、中心性、社区检测等工具是否返回合理的 JSON 结果。
- 如使用 SPCS，调用 Snowflake 的服务函数接口进行批量请求，服务器将返回同样格式的 Service Function 结果。
- 运行结果与监控
- 服务器在日志中输出数据加载、网络构建、工具执行的相关信息，便于排错与性能调优。
- 启动后，MCP 客户端通过制定的 transport（默认 STDIO）与服务器进行 JSON-RPC 交互，调用以下工具：