AI导哈

MCP服务器模板

一个演示如何实现MCP（模型上下文协议）服务器的模板，用于连接AI代理和服务与工具及数据源。

  • by Alexander-Nestor-Bergmann
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 alexander-nestor-bergmann/agents-mcp-demo

使用说明

模板MCP服务器

此存储库用作模板，演示如何实现MCP(模型上下文协议)服务器-一种开放标准，旨在将人工智能代理和服务（如克劳德）连接到工具和数据源。 此存储库的主要目标是说明如何构建、配置和运行基本的MCP服务器。 这些工具是简化的示例，不用于生产。

这个特定的示例服务器使用一个简单的PostgreSQL数据库后端来管理用户数据，展示了MCP如何弥合AI代理和外部资源之间的差距。

概述

服务器充当MCP客户端（例如AI代理）和外部数据源（在这种情况下，是一个包含 users 桌子）。它演示了如何：

  • 通过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）

    # Navigate to the project root directory (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。导航到项目根目录。
    # Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate # or .\.venv\Scripts\activate on Windows
# Install using uv
uv pip install -e .[dev]
  2. 设置环境变量：确保所需 DB_URL 在shell环境中设置或存在于 .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
    }
  }
}

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

这允许客户端直接管理服务器进程。

{
  "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。 （测试尚未实施）.
    # Placeholder command, add tests to tests/ directory
# uv run pytest
    • 测试应添加在 tests/ 目录，镜像 sqlmcp 结构。遵循标准的Pytest约定。

贡献

这主要是一个示例存储库。欢迎通过Pull Requests为提高MCP服务器开发的清晰度、正确性或演示最佳实践做出贡献。请确保代码在提交前已格式化并过梁。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息或访问 https://opensource.org/licenses/MIT.

相关 MCP