BasicMcpServer

一个最小的、可用于生产环境的 MCP (模型上下文协议) 服务器实现，通过 Docker 容器以 HTTP+SSE 的方式暴露。

概述

本项目实现了最简单的 模型上下文协议 (MCP) 服务器，可以部署在 Docker 容器中，并通过带有服务器发送事件 (SSE) 的 HTTP 暴露。它遵循环境变量管理的最佳实践，以确保凭据永远不会提交到版本控制。

该服务器旨在：

• 简单: 最小的样板代码和依赖项
• 安全: 开箱即用的正确凭据管理
• 容器化: 准备好进行 Docker 部署
• 高性能: 使用 FastMCP 和 Uvicorn 实现高性能 HTTP 服务

架构

Python 包

该项目使用以下关键包：

1. MCP SDK: 模型上下文协议的 Python 实现

   • mcp: 核心 MCP 功能
   • mcp.server.fastmcp: 高级 FastMCP 框架

2. Web 框架: FastMCP 的内置 ASGI 支持

   • 在底层利用 Starlette
   • 简化服务器设置和路由
   • 卓越的性能特征

3. ASGI 服务器: Uvicorn

   • 高性能 ASGI 服务器
   • 与 FastMCP 无缝协作
   • 非常适合容器化环境

4. SSE 实现: MCP SDK 的内置 SSE 传输

   • 与 FastMCP 集成
   • 提供服务器发送事件功能

5. 配置管理: pydantic-settings

   • 类型安全的环境变量处理
   • 启动时验证

6. HTTP 客户端 (如果需要): httpx

   • 异步兼容的 HTTP 客户端，用于出站请求

依赖项

这些将在 pyproject.toml 中指定：

[project]
name = "basic-mcp-server"
version = "0.1.0"
description = "一个最小的 MCP 服务器，通过 Docker 容器以 HTTP+SSE 的方式暴露"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "mcp>=1.6.0",
    "uvicorn>=0.34.1",
    "pydantic-settings>=2.8.1",
    "httpx>=0.28.1",
]

凭据管理与安全

为了确保凭据永远不会提交到版本控制：

本地开发

1. 在本地创建一个 .env 文件，其中包含您的凭据：

   API_KEY=your_api_key_here
   OTHER_SECRET=other_secret_here
   

2. 此文件通过 .gitignore 文件自动从 Git 中排除。

3. 使用包含的 .env.example 作为所需变量的模板。

Docker 部署

1. 永远不要将您的 .env 文件直接挂载到容器中。

2. 在运行时传递环境变量：

   docker run -e API_KEY=your_api_key_here -e OTHER_SECRET=other_secret_here basic-mcp-server
   

3. 或者使用带有环境变量的 Docker Compose：

   services:
     mcp-server:
       build: .
       environment:
         - API_KEY=${API_KEY}
         - OTHER_SECRET=${OTHER_SECRET}
   

4. 对于生产环境，请考虑使用 Docker Swarm secrets 或 Kubernetes secrets。

项目结构

basic-mcp-server/
├── .gitignore            # 包括 .env* 模式
├── .env.example          # 带有虚拟值的模板
├── pyproject.toml        # 依赖项和元数据
├── README.md             # 此文件
├── readme_fastmcp.md     # 关于 FastMCP 与低级服务器的文档
├── design_decisions.md   # 项目设计决策日志
├── docker/               # Docker 容器化
│   ├── Dockerfile        # 使用 Python 3.13 的多阶段构建
│   ├── .dockerignore     # 从构建上下文中排除的文件
│   ├── README.md         # Docker 特定文档
│   └── scripts/          # 辅助脚本
│       ├── entrypoint.sh # 容器启动脚本
│       └── run.sh        # 用于替换 docker-compose 的脚本
└── src/
    ├── __init__.py
    ├── main.py           # 入口点
    ├── config.py         # 环境和配置管理
    ├── server.py         # 使用 FastMCP 的 MCP 服务器实现
    └── tools/            # 工具实现（替代组织）
        ├── __init__.py
        └── example.py    # 示例工具

实现细节

配置 (src/config.py)

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    # Server settings
    host: str = "0.0.0.0"
    port: int = 7500
    
    # Add your API keys and credentials here
    api_key: str
    other_secret: str = ""  # Optional, has default empty value
    
    # Configure settings to load from .env file
    model_config = SettingsConfigDict(
        env_file=".env", 
        env_file_encoding="utf-8",
        case_sensitive=False
    )

# Create a settings instance for importing in other modules
settings = Settings()

服务器实现 (src/server.py)

from mcp.server.fastmcp import FastMCP

def create_mcp_server():
    """
    使用 FastMCP 创建和配置 MCP 服务器实例。
    
    Returns:
        FastMCP: 一个配置好的 FastMCP 服务器实例
    """
    # 创建一个具有唯一名称的 FastMCP 服务器实例
    mcp = FastMCP("basic-mcp-server")
    
    # 使用更简单的装饰器语法添加一个示例工具
    @mcp.tool()
    def example(input: str) -> str:
        """一个处理输入文本的示例工具"""
        return f"Processed: {input}"
    
    # 您可以在此处添加更多工具、资源和提示
    
    return mcp

主入口点 (src/main.py)

import logging
import sys

from .config import settings
from .server import create_mcp_server

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    handlers=[logging.StreamHandler(sys.stdout)]
)
logger = logging.getLogger(__name__)

def start():
    """使用 FastMCP 的内置功能启动 MCP 服务器。"""
    logger.info(f"Starting MCP server on {settings.host}:{settings.port}")
    
    # 创建 MCP 服务器
    mcp_server = create_mcp_server()
    
    # 配置服务器设置
    mcp_server.settings.host = settings.host
    mcp_server.settings.port = settings.port
    mcp_server.settings.debug = True
    mcp_server.settings.log_level = "INFO"
    
    # 使用 SSE 传输运行服务器
    mcp_server.run("sse")

# Alternative approach using the FastMCP ASGI application
def create_app():
    """创建一个 ASGI 应用程序，用于与外部 ASGI 服务器一起使用。"""
    mcp_server = create_mcp_server()
    mcp_server.settings.debug = True
    return mcp_server.sse_app()

if __name__ == "__main__":
    start()

Docker 实现

我们将 Docker 容器化问题与应用程序功能分离，以提高可维护性并遵循最佳实践：

目录结构

docker/
├── Dockerfile         # 优化的多阶段 Dockerfile
├── .dockerignore      # 从构建上下文中排除的文件
└── scripts/           # 容器辅助脚本
    ├── entrypoint.sh  # 容器启动脚本
    └── run.sh         # 用于替换 docker-compose 功能的脚本

多阶段 Dockerfile

Docker 实现使用带有 Python 3.13 的多阶段构建方法：

# Stage 1: Builder
FROM python:3.13-slim AS builder

# Set build-time environment variables
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

# Create app directory
WORKDIR /build

# Copy only what's needed for installation
COPY pyproject.toml README.md ./

# Install build dependencies
RUN apt-get update \
    && apt-get install -y --no-install-recommends gcc python3-dev \
    && pip install --upgrade pip \
    && pip install build wheel \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Build wheel package
RUN pip wheel --no-deps --wheel-dir /wheels -e .

# Stage 2: Runtime
FROM python:3.13-slim AS runtime

# Set runtime environment variables
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

# Set working directory
WORKDIR /app

# Copy wheel from builder stage
COPY --from=builder /wheels /wheels

# Copy application code
COPY ./src ./src

# Install dependencies and app
RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir /wheels/* \
    && rm -rf /wheels

# Create non-root user for security
RUN adduser --disabled-password --gecos "" appuser \
    && chown -R appuser:appuser /app
USER appuser

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import http.client; conn = http.client.HTTPConnection('localhost:7501'); conn.request('GET', '/health'); response = conn.getresponse(); exit(0 if response.status == 200 else 1)"

# Expose the port
EXPOSE 7501

# Command to run the application
CMD ["python", "-m", "src.main"]

使用辅助脚本代替 Docker Compose

对于单容器应用程序，我们已将 Docker Compose 替换为辅助脚本，这些脚本提供类似的功能，但复杂性较低：

# 构建 Docker 镜像
./docker/scripts/run.sh build

# 运行服务器
./docker/scripts/run.sh run

# 运行带有热重载的开发环境
./docker/scripts/run.sh dev

# 在容器中运行测试
./docker/scripts/run.sh test

# 清理资源
./docker/scripts/run.sh clean

有关更多详细信息，请参见 docker/README.md。

入门

设置

1. 克隆此存储库
2. 将 .env.example 复制到 .env 并使用您的凭据更新
3. 安装依赖项：

   pip install uv
   uv pip install -e .
   

本地运行

python -m src.main

使用 Docker 构建和运行

# 构建 Docker 镜像
./docker/scripts/run.sh build

# 运行服务器
./docker/scripts/run.sh run

对于带有热重载的开发：

./docker/scripts/run.sh dev

其他有用的命令：

# 在容器中运行测试
./docker/scripts/run.sh test

# 清理资源
./docker/scripts/run.sh clean

测试您的 MCP 服务器

手动测试

使用 MCP SDK CLI

如果您已安装 MCP SDK CLI，则可以使用它来测试您的服务器：

mcp dev http://localhost:7500/sse

使用 Claude

要使用 Claude 进行测试：

1. 使用以下内容更新 Claude 的 MCP 设置文件：

   {
     "mcpServers": {
       "basic-mcp-server": {
         "url": "http://localhost:7500/sse",
         "disabled": false,
         "autoApprove": ["example"]
       }
     }
   }
   

2. 在 Claude 中，使用该工具：

   <use_mcp_tool>
   <server_name>basic-mcp-server</server_name>
   <tool_name>example</tool_name>
   <arguments>
   {
     "input": "Hello MCP World!"
   }
   </arguments>
   </use_mcp_tool>
   

3. 您应该收到：“Processed: Hello MCP World!”

使用 HTTP 请求

您还可以使用 HTTP 请求测试您的服务器：

1. 连接到 SSE 端点：

   curl -N http://localhost:7500/sse
   

2. 在另一个终端中，向服务器发送消息：

   curl -X POST -H "Content-Type: application/json" -d '{"type":"initialize","requestId":"test-123","content":{"clientInfo":{"clientType":"test","clientVersion":"1.0.0"},"capabilities":{"receiveText":true,"receiveImage":false}}}' http://localhost:7500/messages/?session_id=test-session-id
   

自动化端到端测试

我们提供自动化测试，以验证 MCP 服务器在作为容器部署时是否正常工作：

1. 安装测试依赖项：

   cd tests/e2e
   pip install -r requirements.txt
   

2. 运行测试：

   python mcp_container_test.py
   

测试脚本将：

• 构建并启动带有 MCP 服务器的 Docker 容器
• 测试与服务器的 HTTP 连接
• 测试 MCP 协议（初始化、工具列表）
• 测试示例工具功能
• 完成后清理所有资源

有关端到端测试的更多详细信息，请参见 tests/e2e/README.md。

故障排除

如果您遇到问题：

1. 连接被拒绝：

   • 确保容器正在运行：docker ps | grep mcp-server
   • 验证端口映射：docker port [container-id]

2. Claude 中出现“未连接”错误：

   • 确保 URL 包含 /sse 路径：http://localhost:7500/sse
   • 检查容器日志：docker logs [container-id]
   • 尝试重新启动 VSCode 窗口

3. 超时或无响应：

   • 检查服务器日志中是否存在错误
   • 检查是否有其他服务正在使用端口 7500

参考实现

本项目基于模型上下文协议 (MCP) Python SDK。 有关 MCP 规范和 SDK 的更多详细信息，请参阅 原始项目 README。

FastMCP 与低级服务器

本项目已从使用低级 Server 类迁移到使用更符合人体工程学的 FastMCP 方法。 有关差异和优点的详细信息，请参见 readme_fastmcp.md。

下一步

1. 添加更多工具以使您的 MCP 服务器有用
2. 为 HTTP 端点实现身份验证
3. 添加监控和日志记录
4. 部署到您首选的云提供商

---

此实现提供了一个最小但可用于生产环境的 MCP 服务器。 您可以根据需要通过添加更多工具、资源或自定义功能来扩展它。