MCP dockerized

🐳 MCP已码头化

一种容器化模型上下文协议（MCP）服务器，可通过Docker轻松部署，具有可扩展工具和安全的API密钥验证。

特性

• ✅ 容器化部署：通过Docker Compose轻松部署
• ✅ 可配置端口：通过环境变量监听任何端口
• ✅ 健康检查端点：内置健康监测
• ✅ API密钥验证：使用无限制的API密钥进行安全访问
• ✅ 时间戳日志记录：带有时间戳的可配置日志级别
• ✅ 可扩展工具：抽象工具系统，易于扩展
• ✅ 控制台工具：执行主机命令
• ✅ MCP协议合规性：遵循模型上下文协议规范
• ✅ 工具发现：描述所有可用工具的自动端点

快速开始

1. 克隆和设置:

   git clone 
   cd mcp_dockerized

1. 配置环境 （可选）：

   cp .env.example .env
   # Edit .env file as needed

1. 启动服务器:

   docker-compose up -d

1. 获取API密钥:

   docker-compose logs mcp-server | grep "First API key"

配置

环境变量

示例 .env 文件：

MCPD_PORT=8000
MCPD_LOG_LEVEL=INFO
MCPD_API_KEY_LENGTH=32

API终点

健康检查

GET /health

认证

所有API端点都需要在授权头中使用承载令牌：

Authorization: Bearer 

核心终点

列出工具

GET /api/tools

返回所有可用工具的描述。

执行工具

POST /api/tools/{tool_name}
Content-Type: application/json

{
  "command": "ls -la",
  "timeout": 30
}

生成新的API密钥

POST /api/generate-key

MCP协议端点

初始化MCP连接

GET /api/mcp/initialize

列出MCP工具

GET /api/mcp/tools/list

调用MCP工具

POST /api/mcp/tools/call
Content-Type: application/json

{
  "name": "console",
  "arguments": {
    "command": "echo 'Hello World'"
  }
}

可用工具

控制台工具

在主机上执行命令。

参数：

• command （必填）：要执行的命令
• timeout （可选）：超时秒数（默认值：30）
• working_directory （可选）：执行工作目录

例子：

{
  "command": "ls -la /tmp",
  "timeout": 15,
  "working_directory": "/home/user"
}

API密钥管理

初始API密钥

服务器在第一次启动时生成一个初始API密钥。检查日志：

docker-compose logs mcp-server | grep "API Key generated"

生成其他API密钥

使用API

curl -X POST http://localhost:8000/api/generate-key \
  -H "Authorization: Bearer "

创建自定义工具

1.创建新工具文件

在中创建新文件 mcp_tools/ 遵循命名模式的目录 *_tool.py:

# mcp_tools/my_custom_tool.py
from typing import Dict, Any
from .base import BaseMCPTool

class MyCustomTool(BaseMCPTool):
    @property
    def name(self) -> str:
        return "my_custom_tool"
    
    @property
    def description(self) -> str:
        return "Description of what my custom tool does"
    
    def get_parameters_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "input_param": {
                    "type": "string",
                    "description": "Description of the parameter"
                }
            },
            "required": ["input_param"]
        }
    
    async def execute(self, parameters: Dict[str, Any]) -> Any:
        input_param = parameters.get("input_param")
        # Your tool logic here
        return {"result": f"Processed: {input_param}"}

2.注册工具

将您的工具添加到 load_tools() 方法in main.py:

def load_tools(self):
    # Existing tools...
    
    # Add your custom tool
    from mcp_tools.my_custom_tool import MyCustomTool
    custom_tool = MyCustomTool()
    self.tools[custom_tool.name] = custom_tool
    self.logger.info(f"Loaded tool: {custom_tool.name}")

3.重建和部署

docker-compose down
docker-compose build
docker-compose up -d

发展

VS测试代码扩展

为了获得最佳的开发体验，请安装以下VS Code扩展：

主要测试扩展

• REST客户端 (humao.rest-client)-直接在VS代码中测试API端点

开发扩展

• python (ms-python.python)Python语言支持
• Python调试器 (ms-python.debugpy)-高级Python调试
• 码头工人 (ms-azuretools.vscode-docker)Docker容器管理
• YAML (redhat.vscode-yaml)-YAML文件验证

替代HTTP客户端

• 迅雷客户端 (rangav.vscode-thunder-client)-邮递员式界面
• 邮递员 (postman.postman-for-vscode)-正式邮递员延期

使用REST客户端进行测试

1. 获取API密钥:

   docker-compose logs mcp-server | grep "First API key"

1. 使用您偏好的HTTP客户端 测试API端点

1. 使用VS代码任务 （Ctrl+Shift+P→ “任务：运行任务”）：

- 启动MCP服务器 - 停止MCP服务器 - 测试MCP服务器 - 生成API密钥 - 查看服务器日志

地方发展设置

1. 安装依赖项:

   pip install -r requirements.txt

1. 在本地运行:

   python main.py

测试

测试运行状况端点：

curl http://localhost:8000/health

测试工具列表：

curl -H "Authorization: Bearer " \
     http://localhost:8000/api/tools

测试控制台工具：

curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"command": "echo Hello World"}' \
  http://localhost:8000/api/tools/console

安全考虑

• API密钥：安全存储API密钥，并定期轮换
• 控制台工具：控制台工具可以执行任何命令-谨慎使用
• 网络：考虑在生产环境中运行反向代理
• 集装箱安全：以非root用户身份运行（已配置）

监控和日志

查看日志

# All logs
docker-compose logs -f mcp-server

# Only errors
docker-compose logs mcp-server | grep ERROR

# Follow logs
docker-compose logs -f --tail=50 mcp-server

健康监测

服务器包括一个健康检查端点，由Docker Compose自动使用：

curl http://localhost:8000/health

故障排除

服务器无法启动

1. 检查端口可用性：

   lsof -i :8000

1. 检查日志：

   docker-compose logs mcp-server

API关键问题

1. 使用API生成新的API密钥：

   curl -X POST http://localhost:8000/api/generate-key \
     -H "Authorization: Bearer "

1. 检查现有钥匙：

   cat data/api_keys.json

工具执行失败

1. 检查工具参数模式
2. 验证身份验证
3. 检查服务器日志以获取详细的错误消息

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

1. 复刻仓库
2. 创建要素分支
3. 添加您的更改
4. 如果适用，添加测试
5. 提交拉取请求

支持

有关问题和疑问，请在GitHub存储库上打开问题。

Docker Hub部署

预构建图像

MCP Dockalized可在Docker Hub上使用，支持多个Linux平台：

• Linux AMD64/ARM64/ARM v7: antpavlenkohmcorp/mcp-dockerized:latest

Docker Hub快速入门

Linux/macOS：

# Run with default settings
docker run -d -p 8000:8000 antpavlenkohmcorp/mcp-dockerized:latest

# Run with custom environment variables
docker run -d -p 8000:8000 \
  -e MCPD_PORT=8000 \
  -e MCPD_LOG_LEVEL=INFO \
  -v $(pwd)/data:/app/data \
  antpavlenkohmcorp/mcp-dockerized:latest

窗户：

# Run Linux container on Windows (recommended)
docker run -d -p 8000:8000 antpavlenkohmcorp/mcp-dockerized:latest

# Run with persistent data
docker run -d -p 8000:8000 `
  -e MCPD_PORT=8000 `
  -e MCPD_LOG_LEVEL=INFO `
  -v ${PWD}/data:/app/data `
  antpavlenkohmcorp/mcp-dockerized:latest

使用Docker Compose和Docker Hub：

# Update your docker-compose.yml to use the Docker Hub image:
# image: antpavlenkohmcorp/mcp-dockerized:latest

平台特定拉力

# Force specific architecture (Linux)
docker run --platform linux/amd64 -d -p 8000:8000 antpavlenkohmcorp/mcp-dockerized:latest
docker run --platform linux/arm64 -d -p 8000:8000 antpavlenkohmcorp/mcp-dockerized:latest

# ARM v7 (Raspberry Pi)
docker run --platform linux/arm/v7 -d -p 8000:8000 antpavlenkohmcorp/mcp-dockerized:latest

构建和发布自己的图像

先决条件：

1. Docker 桌面版 支持buildx
2. Docker Hub帐户

手动构建过程：

# 1. Enable Docker buildx
docker buildx create --name mcp-builder --use

# 2. Build and push multi-platform
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  --tag YOUR_DOCKERHUB_USERNAME/mcp-dockerized:latest \
  --push .

# 3. Build Windows (on Windows machine)
docker build -f Dockerfile.windows \
  -t YOUR_DOCKERHUB_USERNAME/mcp-dockerized:latest-windows .
docker push YOUR_DOCKERHUB_USERNAME/mcp-dockerized:latest-windows

使用GitHub操作自动构建：

该存储库包括用于自动构建和测试的GitHub Actions工作流。

对于Pull请求工作流程将构建和测试Docker镜像，无需任何设置。

发布到Docker Hub：如果你想自动将镜像发布到Docker Hub，请在GitHub存储库设置中设置这些机密（设置→ 秘密与变量→ 行动）：

• DOCKER_USERNAME：您的Docker Hub用户名
• DOCKER_PASSWORD：您的Docker Hub密码或访问令牌

备注：如果没有这些秘密，工作流仍将构建和测试拉取请求的映像，但不会将其发布到Docker Hub。