A Template MCP Server

一个模板 MCP 服务

此存储库是一个模板，演示如何实现 MCP（Model Context Protocol）服务——这是一种开放标准，旨在将 AI Agent 和服务（如 Claude）连接到工具和数据源。**此存储库的主要目标是展示如何构建、配置和运行基础 MCP 服务。**其中的工具是简化示例，不适用于生产环境。

此示例服务使用简单的 PostgreSQL 数据库作为后端来管理用户数据，展示 MCP 如何在 AI Agent 与外部资源之间搭建桥梁。

概览

该服务充当 MCP 客户端（例如 AI Agent）与外部数据源（本例中是包含 users 表的示例 PostgreSQL 数据库）之间的安全网关。它演示了如何：

• 通过 MCP 标准定义和公开自定义工具。
• 处理来自 MCP 客户端的请求。
• 将这些请求转换为对后端资源执行的操作（例如数据库查询）。
• 将结构化结果或错误返回给客户端。

本示例使用的演示 users 表具有以下结构：

• id（整数，主键）
• name（文本）
• email（文本，唯一）

服务公开的示例工具

为说明如何定义和公开工具，此服务实现了以下与用户数据库交互的示例函数：

• add_user：向数据库添加新用户。
  • 参数：name（字符串）、email（字符串）
  • 返回值：确认消息（字符串）或错误。
• get_all_users：从数据库获取所有用户的列表。
  • 参数：无
  • 返回值：用户对象列表（每个对象都是包含 id、name、email 的字典）或错误。
• find_user_by_email：根据电子邮件地址查找特定用户。
  • 参数：email（字符串）
  • 返回值：单个用户对象（字典）；如果未找到，则返回错误。
• delete_user_by_email：根据电子邮件地址从数据库中删除用户。
  • 参数：email（字符串）
  • 返回值：确认消息（字符串）或错误。

这些工具为 MCP 服务可能提供访问权限的操作类型提供了具体示例。

先决条件

• Python 3.10+
• 可访问 PostgreSQL 数据库。服务需要数据库连接信息。
• Docker（推荐用于轻松运行服务）。
• uv（用于本地开发依赖管理）。

配置

使用环境变量配置数据库连接和服务设置。将 .env.example 文件复制为 .env，并更新其中的值：

cp .env.example .env
# Edit .env with your database details and desired server settings

关键变量：

变量	说明	示例	必需	默认值
DB_URL	完整的 PostgreSQL 连接 URL。	postgresql+asyncpg://user:pass@host:5432/dbname	是
DB_HOST	MCP 服务监听的主机地址。	0.0.0.0	否	0.0.0.0
DB_PORT	MCP 服务监听的端口。	8051	否	8051
MCP_SIGNING_KEY	用于对客户端与服务之间的请求进行签名的可选密钥。	your_very_secret_key	否

注意：DB_URL 应使用兼容 asyncpg 的驱动程序前缀，例如 postgresql+asyncpg://。

用法

使用 Docker（推荐）

1. 构建镜像： （请确保已安装并运行 Docker）

   # 导航到项目根目录（agents-mcp-demo）
   docker build -t sql-mcp-demo-server --build-arg PORT=${DB_PORT:-8051} .
   

2. 运行容器：

   docker run --rm -d --env-file .env -p ${DB_PORT:-8051}:${DB_PORT:-8051} --name sql-mcp-server sql-mcp-demo-server
   

本地开发

1. 安装依赖项：需要 uv。导航到项目根目录。

   # 创建虚拟环境（推荐）
   python -m venv .venv
   source .venv/bin/activate # or .\.venv\Scripts\activate on Windows
   # 使用 uv 安装
   uv pip install -e .[dev]
   

2. 设置环境变量：确保在 shell 环境中设置了必需的 DB_URL，或将其放在根目录下的 .env 文件中（使用 dotenv）。
3. 运行服务：

   uv run python sqlmcp/server.py
   

   （服务将使用环境变量中的主机/端口，或使用默认值）

使用 MCP 客户端连接

配置 MCP 客户端以连接正在运行的服务。连接详情取决于服务的运行方式。

SSE 配置示例（通过 Docker/Compose 运行时）：

{
  "mcpServers": {
    "sqlDemoServer": { // Choose a name for this server connection
      "transport": "sse",
      "url": "http://localhost:8051/sse", // Adjust port if changed from default
    }
  }
}

Stdio 配置示例（用于本地开发）：

这样客户端就可以直接管理服务进程。

{
  "mcpServers": {
    "sqlDemoServerLocal": { // Choose a name
      "command": "python", // Or path to python in your venv e.g., ".venv/bin/python"
      "args": ["sqlmcp/server.py"], // Path relative to workspace root
      "env": {
        "TRANSPORT": "stdio", // Crucial: Tells server to use stdio
        "DB_URL": "postgresql+asyncpg://user:pass@host:5432/dbname", // MUST provide DB URL
      },
      "workingDirectory": "." // Ensure paths are resolved correctly
    }
  }
}

（请根据具体设置调整路径、URL、端口和连接详情。）

开发实践

• 代码检查/格式化：使用 Ruff（已在 pyproject.toml 中配置）。

  uv run ruff check .
  uv run ruff format .
  

• 测试：使用 Pytest。（尚未实现测试）。

  # 占位命令，请在 tests/ 目录中添加测试
  # uv run pytest
  

  • 应在 tests/ 目录下添加测试，并遵循 sqlmcp 的结构。请遵循 Pytest 标准规范。

贡献

这主要是一个示例仓库。欢迎通过 Pull Request 提交有助于提升清晰度、正确性，或展示 MCP 服务开发最佳实践的贡献。提交前请确保代码已格式化并通过代码检查。

许可证

本项目采用 MIT License 授权。详情请参阅 LICENSE 文件，或访问 https://opensource.org/licenses/MIT。