Basemcpserver

BaseMcpServer

使用MCP Python SDK的MCP服务器的最小容器化基础。

概述

BaseMcpServer为构建模型上下文协议（MCP）服务器提供了一个标准化的Docker基础映像。它是：

• 简单：设计为使用MCP Python SDK的最小实现
• 容器化：专为Docker部署而构建
• 特定协议：同时使用HTTP+SSE和stdio协议
• 可重复使用的：作为衍生MCP服务器实现的基础

此映像提供了MCP服务器所需的所有常见依赖关系和配置，以便派生项目可以专注于实现其特定的工具和资源。

地方发展

对于没有Docker的本地开发，每个MCP服务器都包含设置脚本，用于创建和管理具有必要依赖关系的Python虚拟环境。

先决条件

• 已安装Python 3.11+（推荐）
• Git（克隆此存储库）

使用安装和运行脚本

每个MCP服务器都包含两个shell脚本，便于设置和执行：

1.设置脚本

这 setup.sh 脚本创建一个虚拟环境并安装所有依赖项：

# Navigate to the desired MCP server directory
cd example/

# Run the setup script
./setup.sh

这将：

• 创建一个 .venv 带有Python虚拟环境的目录
• 从安装所有必需的依赖项 requirements.txt
• 配置本地开发环境

2.运行脚本

这 run.sh 脚本激活虚拟环境并运行MCP服务器：

# Start with SSE protocol (for Claude/Cline integration)
./run.sh sse

# Or start with stdio protocol (for direct stdin/stdout communication)
./run.sh stdio

手动设置（如果脚本不起作用）

如果脚本在您的系统上不起作用，您可以手动设置环境：

# Navigate to the desired MCP server directory
cd example/

# Create a virtual environment
python3.11 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set PYTHONPATH and run the server
export PYTHONPATH="$PWD/src:$PYTHONPATH"  # On Windows: set PYTHONPATH=%CD%\src;%PYTHONPATH%
cd src
python main.py sse  # Or: python main.py stdio

虚拟环境结构

虚拟环境方法：

• 为每个MCP服务器创建一个隔离的Python环境
• 仅安装该特定服务器所需的依赖项
• 允许轻松激活/停用
• 自动设置正确的PYTHONPATH
• 跨不同系统提供一致的环境

自定义MCP服务器的最佳实践

在基于此模板创建自定义MCP服务器时，请遵循以下最佳实践以避免常见问题：

端口配置

1. 使用正确的端口：基础映像暴露端口 7501。始终将配置与此端口对齐：

- 在 .env 文件，集 PORT=7501 - 运行容器时，将外部端口映射到7501： docker run -p EXTERNAL_PORT:7501 - 在VSCode/Claude设置中，使用带有SSE后缀的外部端口： "url": "http://localhost:EXTERNAL_PORT/sse"

1. 一致的端口使用：请与您的端口号一致。如果您选择外部端口7777：

- Docker命令： docker run -p 7777:7501 - VSCode/Claude设置： "url": "http://localhost:7777/sse"

1. 端口冲突：如果您遇到连接错误，请检查与的端口冲突 lsof -i :PORT_NUMBER

环境变量

1. 装载与复制：对于开发，您可以复制 .env 将文件放入容器：

   COPY ./.env ./.env

对于生产环境，请在运行时挂载它：

   docker run -p 7777:7501 --env-file .env your-image

1. 强健的配置加载：通过日志记录和回退实现稳健的环境变量加载：

   # Add logging of loaded configuration values
   logger.info(f"JIRA_URL: {settings.JIRA_URL}")
   logger.info(f"Using port: {settings.port}")

1. 验证环境：使用明确的错误消息对所需的环境变量进行显式验证

MCP管理器实用程序

该项目现在包括 mcp-manager 用于轻松安装和管理MCP服务器的实用程序。此工具简化了设置、配置和运行MCP服务器的过程。

安装MCP管理器

# install pipx
brew install pipx

# Install directly from the repository
pipx install git+https://github.com/dawsonlp/BaseMcpServer.git#subdirectory=utils/mcp_manager

主要特点

• 服务器安装：从本地目录或Git存储库安装MCP服务器
• 服务器配置：配置服务器以与VS Code/Cline一起使用
• 服务器管理：列出、运行和管理已安装的服务器
• 孤立的环境：每台服务器都在自己的Python虚拟环境中运行

基本用法

# Install a local MCP server
mcp-manager install local example-server --source ./example

# Install from a Git repository
mcp-manager install git jira-server --repo https://github.com/example/jira-mcp-server.git

# List installed servers
mcp-manager list

# Configure VS Code integration
mcp-manager configure vscode

# Run a server manually (if needed)
mcp-manager run server-name --transport stdio

联系克劳德/克莱恩

要将您的MCP服务器连接到Claude Desktop或VS Code中的Cline：

1. 对于使用mcp管理器本地安装的服务器:

- 您不需要手动启动服务器-VS Code将在需要时自动启动它 - 确保在安装或更新服务器后完全重新启动VS Code - 默认情况下，服务器将使用stdio传输运行

1. 用于手动运行服务器:

   ./run.sh sse  # For local development with HTTP+SSE transport

或

   docker run -p 7501:7501 your-image  # For Docker

1. VS Code中的Cline:

使用mcp manager，您可以简单地运行：

   mcp-manager configure vscode

或者手动编辑设置文件： 路径： ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

配置示例：

   {
     "mcpServers": {
       "example-mcp-server": {
         "url": "http://localhost:7501/sse",
         "apiKey": "example_key",
         "disabled": false,
         "autoApprove": []
       },
       "directlyruntest": {
         "command": "/home/user/.mcp_servers/bin/directlyruntest.sh",
         "disabled": false,
         "autoApprove": []
       }
     }
   }

笔记：

- 对于HTTP+SSE服务器，请使用config.py中的正确服务器名称（服务器名称设置） - 对于stdio服务器，使用mcp管理器生成的命令路径 - 确保HTTP+SSE服务器的端口与您的配置（默认为7501）匹配 - 在HTTP+sse服务器的URL末尾包含“/sse”

1. 适用于克劳德桌面首选

设置→ 高级→ MCP服务器→ 添加MCP服务器

输入：

- 名称：示例mcp服务器（或您的自定义服务器名称） - 网址：http://localhost:7501 - API密钥：example_Key（或您的自定义API密钥）

1. 完全重新启动VS代码 对MCP服务器配置进行任何更改后

VS代码集成

1. 需要时重新启动VS代码：安装或更新MCP服务器时，必须完全重新启动VS Code：

- 仅仅安装带有mcp管理器的服务器是不够的 - 您必须完全退出VS Code并重新启动它才能使更改生效 - 这对于基于stdio的服务器尤为重要

1. 服务器自动启动：对于安装了mcp管理器的服务器：

- VS Code将在需要时自动启动服务器 - 您不需要手动运行服务器 mcp-manager run - 当Claude/Cline尝试使用服务器时，这种情况会透明地发生

1. 清除连接错误：当您看到Claude的“未连接”错误时，通常表示：

- 安装后VS Code尚未完全重新启动 - 服务器配置不正确 - 对于HTTP+SSE服务器，服务器可能未运行或端口不匹配

调试技术

1. 添加详细日志记录：增强日志记录，特别是配置和初始化：

   logger.info(f"Starting MCP server on {settings.host}:{settings.port}")
   logger.info(f"Using API key: {'Yes' if settings.api_key else 'No'}")

1. 检查服务器日志：始终使用以下命令检查Docker容器日志 docker logs CONTAINER_ID

1. 验证Docker容器：使用 docker ps 确保您的容器正在运行并且端口映射正确

测试方法

1. 增量开发：从一个已知的工作示例（如示例服务器）开始
2. 做一些小的改变：每次进行一次更改，并在每次更改后进行测试
3. 测试核心功能：在添加复杂的集成之前，使用计算器等简单工具进行测试
4. 检查错误消息：密切关注服务器日志和Claude响应中的错误消息

有关更详细的调试说明，请参阅 debugging_notes.md 在项目根中。

主要特点

• 预安装了所有MCP SDK依赖项的Python 3.11+环境
• 多阶段Docker构建，优化镜像大小
• 非root用户可提高安全性
• 通过Starlette和Uvicorn支持HTTP+SSE协议
• 通过pydantic设置配置环境变量
• 通过虚拟环境提供本地开发支持
• 双传输支持（HTTP+SSE和stdio）

用法

建立基础形象

./build.sh base-mcp-server latest 7501 

参数：

• base-mcp-server：图像名称（默认）
• latest：标签（默认）
• 7501：要公开的端口（默认）
• ``: 必需 -您的Docker Hub用户名

这将：

1. 构建基础图像
2. 为Docker Hub标记它
3. 如果您已登录，请将其推送到Docker Hub

在衍生项目中使用基础图像

在您的Dockerfile中：

# Define build argument for Docker Hub username
ARG DOCKER_USERNAME

# Use the base MCP server image from Docker Hub
FROM docker.io/${DOCKER_USERNAME}/base-mcp-server:latest

# Copy your application code
COPY ./src ./src

# Set PYTHONPATH to include src as a sources root
ENV PYTHONPATH="/app/src:${PYTHONPATH}"

# Set working directory to src
WORKDIR /app/src

# Command to run your MCP server with sse transport
CMD ["python", "main", "sse"]

技术细节

协议支持

BaseMcpServer现在支持HTTP+SSE和stdio协议：

• HTTP+SSE：非常适合容器化部署和基于网络的集成
• 标准输入输出：可用于本地开发和与命令行工具的直接集成

MCP中的HTTP+SSE是什么？

HTTP+SSE（服务器发送事件）是MCP协议支持的标准传输之一：

• 超文本传输协议：用于客户端到服务器的通信（请求）
• SSE：用于服务器到客户端的通信（响应和事件）

HTTP+SSE专为网络环境而设计，非常适合：

• 基于Web的LLM集成
• 服务对服务MCP通信
• 容器化部署（如此）
• 云环境

MCP中的stdio是什么？

stdio传输使用标准输入/输出流进行通信：

• 标准输入：用于接收客户端请求
• 标准输出：用于发送服务器响应

这种运输方式主要用于：

• 地方发展
• 与命令行工具直接集成
• 可以生成进程的桌面应用程序

实现细节

此基础图像使用：

• 斯塔利特：一个处理HTTP+SSE协议的轻量级ASGI框架
• 乌维科恩：为Starlette应用程序提供服务的ASGI服务器
• 原生Python I/O：用于stdio传输模式

MCP Python SDK通过以下方式提供实现：

• 这 .sse_app() HTTP+SSE方法
• 直接 run("stdio") 支持stdio模式

安装MCP服务器

扩展此基础映像时，您的MCP服务器将通过HTTP+SSE自动提供服务。对于需要与现有web服务集成的更高级场景，您可以将MCP服务器挂载到现有的ASGI应用程序：

from starlette.applications import Starlette
from starlette.routing import Mount, Host
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My App")

# Mount the MCP server to an existing ASGI application
app = Starlette(
    routes=[
        Mount('/mcp', app=mcp.sse_app()),
    ]
)

# Or mount it as a subdomain
app.router.routes.append(Host('mcp.example.com', app=mcp.sse_app()))

安全考虑

在生产环境中使用HTTP+SSE时：

• 在生产环境中始终使用HTTPS
• 考虑为HTTP端点实施身份验证
• 如果公开您的MCP服务器，请使用API密钥或其他身份验证机制
• 对面向公众的服务器实施速率限制

Python SDK实现

该图像直接使用MCP Python SDK，抽象程度最低：

• FastMCP用于人体工程学工具定义
• 基于Python类型提示的内置模式生成
• 自动验证输入/输出格式
• 支持HTTP+SSE和stdio传输模式

环境变量和配置

基础映像支持通过环境变量进行配置，这些变量可以通过多种方式传递给派生映像：

可用环境变量

• HOST：要绑定的接口（默认值：0.0.0.0）
• PORT：要侦听的端口（默认值：7501）
• API_KEY：身份验证所需（必须提供）
• SERVER_NAME：MCP服务器的唯一标识符
• 特定实现所需的任何其他环境变量

衍生图像的配置方法

1.使用命令行环境变量

docker run -p 7501:7501 \
  -e API_KEY=your_api_key \
  -e SERVER_NAME=your-mcp-server \
  yourdockerusername/your-mcp-server:latest

2.使用环境文件

创建一个 .env 使用您的配置文件：

API_KEY=your_api_key
SERVER_NAME=your-mcp-server
HOST=0.0.0.0
PORT=7501

然后运行：

docker run -p 7501:7501 --env-file .env yourdockerusername/your-mcp-server:latest

3.使用Docker Secrets（适用于Docker Swarm）

对于使用Docker Swarm的生产部署：

echo "your_api_key" | docker secret create api_key -
echo "your_server_name" | docker secret create server_name -

docker service create \
  --name your-mcp-server \
  --secret api_key \
  --secret server_name \
  --publish 7501:7501 \
  yourdockerusername/your-mcp-server:latest

4.将配置构建到派生图像中

出于开发或测试目的，您可以直接将配置构建到派生映像中：

FROM docker.io/dawsonlp/base-mcp-server:latest

# Configure environment variables (non-sensitive only!)
ENV HOST=0.0.0.0
ENV PORT=7501
ENV SERVER_NAME=example-mcp-server

# Copy application code
COPY ./src ./src

CMD ["python", "main", "sse"]

安全最佳实践

• 永远不要在Dockerfile或镜像中包含敏感的API密钥或机密
• 对敏感值使用环境变量或挂载的机密
• 考虑使用Docker secrets或vault服务进行生产
• 容器以非root用户身份运行，以提高安全性
• 定期轮换API密钥和机密

发展

此存储库包含：

• docker/Dockerfile：基础映像的多级Dockerfile
• build.sh：使用Docker Hub集成构建脚本
• requirements-base.txt：基本Python依赖项
• 特定于服务器的实现目录（例如/、jira clone/）
• 本地开发脚本（setup.sh、run.sh）

许可证

MIT许可证