Feyod MCP Server

Feyod MCP 服务

用于通过自然语言查询 Feyenoord 足球比赛数据的模型上下文协议（MCP）服务。

Streamable HTTP 服务可通过 https://mcp.feyod.nl/mcp 公开访问。Docker 容器可在 Docker Hub 获取。

主要功能

此 MCP 服务提供自然语言接口，用于查询 Feyod：Feyenoord Open Data。用户可以借此获取有关 Feyenoord 比赛、球员、对手及相关事件的问题答案。

底层 Feyod 数据库由 jeroenvdmeer/feyod GitHub repository 维护。你需要从该仓库获取最新的 SQL 文件，以设置所需的数据库。

此服务使用 LangChain 来：

1. 将自然语言问题转换为 SQL 查询（可选择利用少样本示例来提高准确性）。
2. 验证生成的 SQL。
3. 尝试使用大模型修复无效的 SQL。
4. 对 SQLite 数据库执行有效的 SQL。
5. 返回原始查询结果。

LLM 和嵌入模型会根据配置使用提供方工厂（llm_factory.py）动态加载，从而便于在 OpenAI、Google 等提供方之间切换。

使用

使用公共端点

Feyod MCP 服务可通过 https://mcp.feyod.nl/mcp 公开访问。你可以从任何兼容 MCP 的客户端连接到此端点，例如 Claude Desktop。

使用 Docker 容器

Feyod MCP 服务的 Docker 镜像可在 Docker Hub 获取。你可以使用以下命令拉取并运行：

1. 拉取 Docker 镜像：

   docker pull jeroenvdmeer/feyod-mcp
   

2. 运行 Docker 容器： 你需要提供 LLM 提供方和 API 密钥所需的环境变量。如果你想使用本地数据库，而不是镜像中包含的数据库，也可以挂载 feyod.db 文件。

   docker run -p 8000:8000 \
     -e LLM_PROVIDER="your_llm_provider" \
     -e LLM_API_KEY="your_api_key" \
     jeroenvdmeer/feyod-mcp
   

   将 your_llm_provider 和 your_api_key 替换为实际的 LLM 配置。

   挂载本地数据库文件：

   docker run -p 8000:8000 \
     -e LLM_PROVIDER="your_llm_provider" \
     -e LLM_API_KEY="your_api_key" \
     -v <absolute_path_to_feyod_db>:/app/feyod/feyod.db \
     jeroenvdmeer/feyod-mcp
   

   将 <absolute_path_to_feyod_db> 替换为主机上 feyod.db 文件的绝对路径。

工具

此服务提供用于查询 Feyenoord 数据库的 MCP 工具。可通过 MCP 协议（tools/list）发现这些工具。

• answer_feyenoord_question：回答有关 Feyenoord 的问题。问题可以用自然语言和文本提出，内容可以涉及比赛（阵容、结果、进球、红黄牌等）、球员和对手。

设置

1. 克隆仓库：

   # 克隆此仓库以获取 MCP 服务
   git clone https://github.com/jeroenvdmeer/feyod-mcp.git
   
   # 克隆 Feyod 数据库
   git clone https://github.com/jeroenvdmeer/feyod.git
   
   # 切换到 MCP 服务目录
   cd feyod-mcp
   

2. 创建并激活虚拟环境（推荐：uv）：

   安装说明请参阅 https://docs.astral.sh/uv/。

   uv venv
   .venv\Scripts\activate  # Windows
   # or
   source .venv/bin/activate  # macOS/Linux
   

3. 安装依赖项：

   # 使用 uv（推荐）
   uv add "mcp[cli]" langchain langchain-openai langchain-google-genai python-dotenv aiosqlite
   # 或使用 pip
   pip install -r requirements.txt
   

4. 设置数据库：

   # 切换到包含 SQL 文件的 feyod 目录
   cd ../feyod
   
   # 使用 SQL 语句构建 SQLite 数据库
   sqlite3 feyod.db < feyod.sql
   

配置

在 mcp 目录中创建 .env 文件，并填写以下变量：

# Path to the SQLite database file (relative to mcp folder or absolute)
DATABASE_PATH="../feyod/feyod.db"

# Server host binding (defaults to localhost/127.0.0.1)
HOST="127.0.0.1"

# Logging level (e.g., DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# --- LLM Configuration ---
LLM_PROVIDER="google"  # or "openai", etc.
LLM_API_KEY="YOUR_API_KEY_HERE"
LLM_MODEL="gemini-2.5-flash"

# --- Example Loading Configuration (Optional) ---
EXAMPLE_SOURCE="local"  # or "mongodb"
EXAMPLE_DB_CONNECTION_STRING=""
EXAMPLE_DB_NAME="feyenoord_data"
EXAMPLE_DB_COLLECTION="examples"

注意：

• 将占位 API 密钥替换为你的实际密钥。
• HOST 设置默认为 127.0.0.1，用于本地开发。在 Docker 中运行时，该设置会自动设为 0.0.0.0，以允许外部连接。
• 确保 LLM_PROVIDER 与 llm_factory.py 中定义的提供商一致。
• 为你选择的提供商安装必要的 LangChain 集成包（例如 langchain-google-genai）。
• 如果使用 EXAMPLE_SOURCE="mongodb"，请按上述说明配置 MongoDB 设置。

运行服务

你可以通过以下几种方式运行服务：

• 开发模式（支持热重载和 Inspector）：

  mcp dev main.py
  

• 标准运行：

  python main.py
  # or
  mcp run main.py
  

服务将启动并监听 MCP 连接（默认使用 stdio，也可根据配置使用 HTTP/SSE）。

使用 Docker 运行

你可以使用提供的 Dockerfile 将 MCP 服务容器化。

1. 构建 Docker 镜像： 在终端中切换到 mcp 目录并运行以下命令：

   docker build -t feyod-mcp:latest .
   

   这将构建一个标记为 feyod-mcp:latest 的镜像。

2. 运行 Docker 容器： 你可以运行容器，将内部端口 8000 映射到主机上的外部端口（例如 8000）。你还需要将数据库文件挂载为卷，以便容器能够访问它。

   docker run -p 8000:8000 -v <absolute_path_to_feyod_db>:/app/../feyod/feyod.db feyod-mcp:latest
   

   将 <absolute_path_to_feyod_db> 替换为主机上 feyod.db 文件的绝对路径。

   你也可以直接传入环境变量：

   docker run -p 8000:8000 -e DATABASE_PATH="/app/../feyod/feyod.db" -e LLM_PROVIDER="google" -e LLM_API_KEY="YOUR_API_KEY_HERE" -e LLM_MODEL="gemini-2.5-flash" -v <absolute_path_to_feyod_db>:/app/../feyod/feyod.db feyod-mcp:latest
   

   请记得将占位值替换为你的实际配置。

容器中的服务将启动并监听 0.0.0.0:8000。

添加新的大模型提供商

要添加对新提供商的支持：

1. 安装包： 安装所需的 LangChain 集成包（例如 pip install langchain-anthropic）。
2. 更新工厂： 编辑 llm_factory.py 以添加该提供商。
3. 更新 .env / README： 将所需的 API 密钥添加到 .env 文件中。

依赖项

• Python 3.10+
• 具体的软件包依赖项请参阅 requirements.txt。
• 特定提供商的软件包（例如 langchain-openai、langchain-google-genai）。

调试与故障排除

• 使用 mcp dev main.py 和 MCP Inspector 进行本地测试。
• 日志会写入 stderr，可在 Claude Desktop 日志或终端中查看。
• 如遇环境或配置问题，请检查 .env 和 Claude Desktop 配置。
• 更多建议请参阅 MCP 调试指南。

安全性

本节概述 MCP 服务中实施的关键安全措施。这些措施根据风险评估以及 MCP 文档中提供的安全注意事项进行选择。

风险评估

MCP 服务的关键资产包括：

1. Feyod 数据库中的信息
2. 面向公众开放、可供终端用户使用的 Streamable HTTP 服务

这两项资产都服务于 MCP 服务的核心目标：为终端用户的问题提供正确答案。

与 Feyod 数据库中信息相关的风险

作为风险评估的依据，以下概览列出了信息安全标准分析。

标准	影响	描述
机密性	无	由于 Feyod 数据库公开可用，数据泄露不会造成影响。
完整性	高	MCP 服务的核心功能是针对问题提供准确答案。如果数据不再完整和/或正确，MCP 服务就无法兑现这一承诺。
可用性	高	MCP 服务的核心功能是针对问题提供准确答案。如果数据不再可用，MCP 服务就无法兑现这一承诺。

鉴于数据完整性和可用性的重要性，删除和/或修改 Feyod 数据库的数据库交互被视为影响 Feyod 数据库信息安全的主要风险。此类交互可能由以下行为引发：

1. 滥用 MCP 服务生成恶意 SQL 查询（例如，DELETE 和 UPDATE 查询）
2. 未经授权访问 MCP 服务托管平台中的数据库

与公开暴露的 Streamable HTTP 服务相关的风险

为确保向最终用户的问题提供正确答案，以下风险被视为主要风险：

1. LLM 生成不正确的 SQL 查询和/或输出消息，导致答案错误
2. 向 MCP 服务发送过多请求，导致服务不可用并产生高额费用
3. 向 MCP 服务发送恶意请求，触发大量成本高昂的 LLM 调用并产生高额费用

主要安全控制措施

根据已识别的与 Feyod 数据库中信息及公开暴露的 Streamable HTTP 服务相关的主要风险，我们实施了以下主要安全控制措施。

与 Feyod 数据库信息相关的关键控制措施

风险	控制措施	实施详情
滥用 MCP 服务生成恶意 SQL 查询（例如 DELETE 和 UPDATE 查询）	提示词工程与查询验证	提示词级强制措施： 在发送给 LLM 的系统提示词（位于 query_processor.py）中，包含明确指令："DO NOT make any DML statements (INSERT, UPDATE, DELETE, DROP etc.) to the database. Only SELECT statements are allowed." 应用级防护措施： 生成 SQL 后，应用代码会验证返回的 SQL 字符串是否以 SELECT 开头（不区分大小写）。这是一项确定性检查，可防止执行其他类型的语句。 只读访问： 对于公开托管的服务，数据库文件以只读方式挂载。这提供了强有力的基础设施级保障，确保无论生成的 SQL 是什么，都无法执行写入或删除操作。
未经授权访问 MCP 服务托管平台上的数据库	文件系统与网络隔离	本地文件访问： 按照标准配置，SQLite 数据库是本地文件（feyod.db），不会通过网络端口公开。应用（如 database.py 中所示）直接从文件系统访问数据库，从而最大限度地缩小网络攻击面。 最小权限原则： 在生产托管环境中，使用标准文件系统权限，确保只有运行 MCP 服务进程的服务账户可以读取数据库文件。

与公开暴露的 Streamable HTTP 服务相关的关键控制措施

风险	控制措施	实施详情
大模型生成错误的 SQL 查询和／或输出消息，导致答案不正确	多阶段验证工作流	富含上下文的生成： 为提高准确性，会向大模型提供完整的数据库架构（来自 database.get_schema_description），并在可用时提供有效问题－查询对的少样本示例（来自 examples.py）。 执行前语法检查： 在 query_processor.py 中，会先使用 EXPLAIN 语句（check_sql_syntax 函数）检查每个生成的 SQL 查询。此操作会根据数据库架构验证查询语法，但不会实际执行查询，从而捕获大多数错误。 自动修复循环： 如果语法检查失败，工作流（attempt_fix_sql 函数）会触发第二次大模型调用，并向其提供无效查询及其产生的具体数据库错误。模型可以据此尝试修正，修正后的查询会在执行前重新验证。
对 MCP 服务发出过多请求，导致服务不可用并产生高额费用	资源与基础设施限制	查询结果上限： SQL 生成提示词会指示大模型 "always limit your query to at most 5 results"，以防止查询返回过大的数据集，从而给服务器或客户端带来过大负担。 容器化： 使用 Docker 可以对容器施加资源限制（CPU、内存），防止单个失控进程影响整台主机。
向 MCP 服务发起恶意请求，触发大量高成本的大模型调用并导致高额费用	高效工作流与外部监控	优化大模型使用： 查询处理工作流经过设计，力求高效。对于有效的用户问题，通常只需调用大模型一次。只有初次生成的查询失败时，才会触发成本更高的“修复”调用。

安全审计

参考资料

MCP 资源：

• MCP Python SDK
• MCP 文档
• 官方 MCP 服务

生成式 AI 和大模型应用安全：

• 2025 年 OWASP 大模型应用十大风险
• OWASP Agentic AI——威胁与缓解措施 1.0（2025 年 2 月 17 日）
• OWASP 多 Agent 系统威胁建模指南 1.0

免责声明

本项目与 Feyenoord Rotterdam N.V. 无关联，因此并非 Feyenoord 官方产品。通过此服务提供的数据未经官方确认，可能不准确。