基础Mcp服务器

Name: 基础Mcp服务器
Author: dawsonlp

作者：dawsonlp3 星标更新：2025-10-13

安装使用来源：spider==github.com

项目介绍

BaseMcpServer

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

概览

BaseMcpServer 提供了一个标准化的Docker基础镜像，用于构建模型上下文协议（MCP）服务器。它具有以下特点：

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

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

本地开发

无需Docker即可进行本地开发，每个MCP服务器都包含设置脚本，用于创建和管理具有必要依赖项的Python虚拟环境。

先决条件

安装了Python 3.11+（推荐）
Git（用于克隆此仓库）

使用设置和运行脚本

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

1. 设置脚本

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

# 导航到所需的MCP服务器目录
cd example/

# 运行设置脚本
./setup.sh

这将：

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

2. 运行脚本

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

# 使用SSE协议启动（适用于Claude/Cline集成）
./run.sh sse

# 或者使用stdio协议启动（适用于直接的stdin/stdout通信）
./run.sh stdio

手动设置（如果脚本无法工作）

如果脚本在您的系统上无法正常工作，您可以手动设置环境：

# 导航到所需的MCP服务器目录
cd example/

# 创建虚拟环境
python3.11 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt

# 设置PYTHONPATH并运行服务器
export PYTHONPATH="$PWD/src:$PYTHONPATH"  # 在Windows上：set PYTHONPATH=%CD%\src;%PYTHONPATH%
cd src
python main.py sse  # 或：python main.py stdio

虚拟环境结构

虚拟环境方法：

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

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

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

端口配置

使用正确的端口：基础镜像暴露端口 7501。始终将您的配置与此端口对齐：
- 在 .env 文件中，设置 PORT=7501
- 运行容器时，将外部端口映射到7501：docker run -p EXTERNAL_PORT:7501
- 在VSCode/Claude设置中，使用带有SSE后缀的外部端口："url": "http://localhost:EXTERNAL_PORT/sse"
一致的端口使用：保持端口号的一致性。如果您选择外部端口7777：
- Docker命令：docker run -p 7777:7501
- VSCode/Claude设置："url": "http://localhost:7777/sse"
端口冲突：如果您遇到连接错误，请检查端口冲突：lsof -i :PORT_NUMBER

环境变量

挂载与复制：对于开发，您可以将 .env 文件复制到容器中：
```
COPY ./.env ./.env
```
对于生产，运行时挂载它：
```
docker run -p 7777:7501 --env-file .env your-image
```

健壮的配置加载：实现健壮的环境变量加载，包括日志记录和回退：

# 记录加载的配置值
logger.info(f"JIRA_URL: {settings.JIRA_URL}")
logger.info(f"使用的端口: {settings.port}")

验证环境：明确验证必需的环境变量，并提供清晰的错误消息

MCP Manager 工具

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

安装MCP Manager

# 安装pipx
brew install pipx

# 直接从仓库安装
pipx install git+https://github.com/dawsonlp/BaseMcpServer.git#subdirectory=utils/mcp_manager

主要特性

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

基本用法

# 安装本地MCP服务器
mcp-manager install local example-server --source ./example

# 从Git仓库安装
mcp-manager install git jira-server --repo https://github.com/example/jira-mcp-server.git

# 列出已安装的服务器
mcp-manager list

# 配置VS Code集成
mcp-manager configure vscode

# 手动运行服务器（如有需要）
mcp-manager run server-name --transport stdio

连接到Claude/Cline

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

对于使用mcp-manager安装的本地服务器：
- 您不需要手动启动服务器——VS Code会在需要时自动启动它
- 在安装或更新服务器后，请确保完全重启VS Code
- 默认情况下，服务器将以stdio传输方式运行

对于手动运行的服务器：

./run.sh sse  # 用于本地开发，使用HTTP+SSE传输

或

docker run -p 7501:7501 your-image  # 用于Docker

对于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中的正确服务器名称（server_name设置）
- 对于stdio服务器，使用mcp-manager生成的命令路径
- 确保端口与您的配置匹配（默认是7501）对于HTTP+SSE服务器
- 对于HTTP+SSE服务器，在URL末尾包含"/sse"
对于Claude Desktop，转到：设置 → 高级 → MCP服务器 → 添加MCP服务器

输入：
- 名称：example-mcp-server（或您自定义的服务器名称）
- URL：http://localhost:7501
- API密钥：example_key（或您自定义的API密钥）
在更改MCP服务器配置后，完全重启VS Code

VS Code集成

需要时重启VS Code：在安装或更新MCP服务器时，必须完全重启VS Code：
- 仅使用mcp-manager安装服务器是不够的
- 您必须完全退出VS Code并重新启动它，以便更改生效
- 对于基于stdio的服务器，这一点尤为重要
自动服务器启动：对于使用mcp-manager安装的服务器：
- VS Code将在需要时自动启动服务器
- 您不需要手动运行服务器 mcp-manager run
- 当Claude/Cline尝试使用服务器时，这会透明地发生
清除连接错误：当您看到Claude中的“未连接”错误时，通常表示：
- 在安装后没有完全重启VS Code
- 服务器配置不正确
- 对于HTTP+SSE服务器，服务器可能没有运行或端口不匹配

调试技巧

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

logger.info(f"正在{settings.host}:{settings.port}启动MCP服务器")
logger.info(f"是否使用API密钥：{'是' if settings.api_key else '否'}")

检查服务器日志：始终检查Docker容器日志：docker logs CONTAINER_ID
验证Docker容器：使用 docker ps 确保您的容器正在运行并且端口映射正确

测试方法

增量开发：从已知工作的示例开始（如示例服务器）
逐步更改：每次只做一个小的更改并在每次更改后进行测试
测试核心功能：先使用简单的工具（如计算器）进行测试，然后再添加复杂的集成
仔细检查错误信息：注意服务器日志和Claude响应中的错误信息

更多详细的调试笔记，请参阅项目根目录下的 debugging_notes.md。

主要特性

包含所有MCP SDK依赖项的Python 3.11+环境
多阶段Docker构建，优化镜像大小
使用非root用户提高安全性
通过Starlette和Uvicorn支持HTTP+SSE协议
通过pydantic-settings配置环境变量
支持使用虚拟环境进行本地开发
同时支持两种传输模式（HTTP+SSE和stdio）

使用

构建基础镜像

./build.sh base-mcp-server latest 7501 <your-docker-username>

参数：

base-mcp-server：镜像名称（默认）
latest：标签（默认）
7501：要公开的端口（默认）
<your-docker-username>：必需 —— 您的Docker Hub用户名

这将：

构建基础镜像
为Docker Hub打标签
如果您已登录，则将其推送到Docker Hub

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

在您的Dockerfile中：

# 定义Docker Hub用户名的构建参数
ARG DOCKER_USERNAME

# 使用Docker Hub上的基础MCP服务器镜像
FROM docker.io/${DOCKER_USERNAME}/base-mcp-server:latest

# 复制您的应用程序代码
COPY ./src ./src

# 设置PYTHONPATH以包含src作为源根
ENV PYTHONPATH="/app/src:${PYTHONPATH}"

# 设置工作目录为src
WORKDIR /app/src

# 命令以运行您的MCP服务器，使用sse传输
CMD ["python", "main", "sse"]

技术细节

协议支持

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

HTTP+SSE：适合容器化部署和网络集成
stdio：适用于本地开发和直接与命令行工具集成

HTTP+SSE在MCP中是什么？

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

HTTP：用于客户端到服务器的通信（请求）
SSE：用于服务器到客户端的通信（响应和事件）

HTTP+SSE旨在用于联网环境，使其非常适合：

基于Web的LLM集成
服务到服务的MCP通信
容器化部署（如本例所示）
云环境

stdio在MCP中是什么？

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

stdin：用于接收客户端请求
stdout：用于发送服务器响应

此传输主要用于：

本地开发
直接与命令行工具集成
可以启动进程的桌面应用程序

实现细节

此基础镜像使用：

Starlette：一个轻量级的ASGI框架，处理HTTP+SSE协议
Uvicorn：一个ASGI服务器，服务于Starlette应用
原生Python I/O：用于stdio传输模式

实现由MCP Python SDK提供：

.sse_app() 方法用于HTTP+SSE
直接支持 run("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")

# 将MCP服务器挂载到现有的ASGI应用
app = Starlette(
    routes=[
        Mount('/mcp', app=mcp.sse_app()),
    ]
)

# 或将其挂载为子域
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

# 配置环境变量（仅限非敏感信息！）
ENV HOST=0.0.0.0
ENV PORT=7501
ENV SERVER_NAME=example-mcp-server

# 复制应用程序代码
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依赖项
服务器特定实现目录（example/，jira-clone/）
本地开发脚本（setup.sh，run.sh）

许可证

MIT许可证