模板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 | 没有 | INFO | |
MCP_SIGNING_KEY | 用于在客户端和服务器之间签名请求的可选密钥。 | your_very_secret_key | 否 |
注： 这 DB_URL 应该使用与asyncpg兼容的驱动程序前缀，如 postgresql+asyncpg://.
用法
使用Docker（推荐）
- 塑造形象:
*（确保您已安装并运行Docker）*
# Navigate to the project root directory (agents-mcp-demo)
docker build -t sql-mcp-demo-server --build-arg PORT=${DB_PORT:-8051} .- 运行容器:
docker run --rm -d --env-file .env -p ${DB_PORT:-8051}:${DB_PORT:-8051} --name sql-mcp-server sql-mcp-demo-server地方发展
- 再进行：需要
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]- 设置环境变量：确保所需
DB_URL在shell环境中设置或存在于.env根目录中的文件（使用dotenv）。 - 运行服务器:
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.