script wrapper MCP server

MCP脚本运行程序

一种模型上下文协议（MCP）服务器，为编码代理提供通用接口，以在Docker化环境中执行开发人员定义的bash脚本。

🚀 快速开始

选项1:Docker（推荐）

# Clone and run with Docker
git clone 
cd devmcp
docker compose up --build -d

# Check logs
docker compose logs -f

选项2：本地安装

# Clone repository
git clone 
cd devmcp

# Install dependencies
pip install -r requirements.txt

# Run the server
python -m mcp_script_runner.server

📋 概述

MCP脚本运行器服务器使AI代理能够：

• 执行预定义的bash脚本 具有可配置的参数
• 管理工作目录 针对不同的项目环境
• 获取脚本信息 包括描述和可用论据
• 列出可用脚本 动态地
• 处理脚本超时 并且错误条件优雅

🐳 Docker支持

该项目包括对容器化执行的完全Docker支持：

• 🔧 即用型容器 所有依赖项
• 🛡️ 孤立的执行环境
• 📦 轻松部署 Docker Compose
• 🔍 调试功能 具有交互式shell访问功能

看 医生.md 完整的Docker使用指南。

快速Docker命令

# Start the MCP server
docker compose up --build -d

# Interactive development shell
docker compose --profile debug up shell

# Test script execution
docker compose exec mcp-script-runner bash scripts/hello.sh

🛠️ 安装

先决条件

• Python 3.11+
• Docker（用于容器化执行）
• Bash兼容shell

本地设置

# Install Python dependencies
pip install -r requirements.txt

# Verify installation
python -c "from src.mcp_script_runner.server import main; print('✅ Installation OK')"

Docker设置

# Build container
docker build -t mcp-script-runner .

# Or use Docker Compose
docker compose up --build

⚙️ 配置

配置文件： .mcp-config.json

{
  "working_directory": ".",
  "scripts": {
    "hello": {
      "path": "scripts/hello.sh",
      "description": "Simple hello world script",
      "arguments": [],
      "timeout": 30
    },
    "list_files": {
      "path": "scripts/list_files.sh",
      "description": "List files in directory with options",
      "arguments": ["directory", "options"],
      "timeout": 10
    }
  }
}

脚本目录结构

project/
├── .mcp-config.json
├── scripts/
│   ├── hello.sh
│   ├── list_files.sh
│   └── system_info.sh
└── src/
    └── mcp_script_runner/

🔧 可用的MCP工具

工具使用示例

{
  "tool": "run_script",
  "arguments": {
    "script_name": "hello",
    "arguments": []
  }
}

🏃‍♂️ 运行服务器

本地执行

# Start MCP server (listens on stdio)
python -m mcp_script_runner.server

# Or with explicit path
PYTHONPATH=src python -m mcp_script_runner.server

Docker执行

# Background service
docker compose up -d

# Interactive mode
docker compose run --rm mcp-script-runner

# Debug shell
docker compose --profile debug up shell

📝 示例脚本

基本Hello脚本(scripts/hello.sh)

#!/bin/bash
echo "Hello from MCP Script Runner!"
echo "Current directory: $(pwd)"
echo "Script arguments: $@"
echo "Date: $(date)"

文件列表脚本(scripts/list_files.sh)

#!/bin/bash
DIRECTORY=${1:-.}
OPTIONS=${2:-"-la"}
echo "Listing files in: $DIRECTORY"
ls $OPTIONS "$DIRECTORY"

系统信息脚本(scripts/system_info.sh)

#!/bin/bash
echo "=== System Information ==="
echo "OS: $(uname -s)"
echo "Kernel: $(uname -r)"
echo "Architecture: $(uname -m)"
echo "Uptime: $(uptime)"
echo "Disk Usage:"
df -h

🧪 测试

单元测试

# Run tests locally
python -m pytest tests/

# Run tests in Docker
docker compose run --rm mcp-script-runner python -m pytest tests/

手动测试

# Test script execution
python -c "
import asyncio
from src.mcp_script_runner.executor import ScriptExecutor
from src.mcp_script_runner.config import ConfigManager

async def test():
    cm = ConfigManager()
    ex = ScriptExecutor(cm)
    result = await ex.execute_script('hello')
    print(f'Exit code: {result.exit_code}')
    print(result.stdout)

asyncio.run(test())
"

🔐 安全考虑

• 🛡️ 容器化执行 隔离脚本执行
• 👤 非root用户 集装箱内部(mcpuser)
• 📁 文件访问受限 通过卷挂载
• ⏱️ 脚本超时 防止失控过程
• 🚫 无外壳注射 -论点安全通过

🎯 用例

开发自动化

• 构建和测试命令
• 代码生成脚本
• 开发环境设置

系统管理

• 系统监控脚本
• 备份和维护任务
• 配置管理

CI/CD集成

• 部署脚本
• 环境验证
• 自动化测试工作流程

项目管理

• 任务自动化
• 报告生成
• 资源管理

🐛 故障排除

常见问题

MCP服务器无法启动

# Check Python path
export PYTHONPATH=src

# Verify dependencies
pip install -r requirements.txt

# Check configuration
python -c "from src.mcp_script_runner.config import ConfigManager; cm = ConfigManager(); print('Config OK')"

脚本执行失败

# Check script permissions
chmod +x scripts/*.sh

# Test script directly
bash scripts/hello.sh

# Check Docker logs
docker compose logs mcp-script-runner

Docker问题

# Rebuild container
docker compose up --build

# Check container status
docker compose ps

# Interactive debugging
docker compose run --rm mcp-script-runner bash

调试模式

# Local debug
PYTHONPATH=src python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from mcp_script_runner.server import main
import asyncio
asyncio.run(main())
"

# Docker debug
docker compose --profile debug up shell

📚 发展

项目结构

devmcp/
├── 📄 README.md              # This file
├── 🐳 DOCKER.md              # Docker usage guide
├── 📋 TASKS.md               # Development tasks
├── ⚙️ .mcp-config.json       # Configuration
├── 🐳 Dockerfile             # Container definition
├── 🐳 docker-compose.yml     # Container orchestration
├── 📦 requirements.txt       # Python dependencies
├── 📦 pyproject.toml         # Python project config
├── 🔧 scripts/               # Example scripts
├── 🐍 src/mcp_script_runner/ # Python source code
└── 🧪 tests/                 # Unit tests

添加新脚本

1. 在中创建脚本 scripts/ 目录
2. 使可执行文件： chmod +x scripts/myscript.sh
3. 增添 .mcp-config.json:

{
  "scripts": {
    "myscript": {
      "path": "scripts/myscript.sh",
      "description": "My custom script",
      "arguments": ["arg1", "arg2"],
      "timeout": 30
    }
  }
}

1. 重新加载配置：使用 reload_config 工具

贡献

1. 分叉存储库
2. 创建特征分支
3. 添加新功能的测试
4. Docker测试： docker compose up --build
5. 提交拉取请求

🚀 部署

生产部署

# Using Docker Compose
docker compose up -d

# Using Docker Swarm
docker stack deploy -c docker-compose.yml mcp-stack

# Using Kubernetes
kubectl apply -f k8s/

与MCP客户端集成

Claude桌面配置

{
  "mcpServers": {
    "script-runner": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/devmcp/docker-compose.yml", "run", "--rm", "mcp-script-runner"]
    }
  }
}

📄 许可证

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

🤝 支持

• 📖 文件：见 医生.md Docker使用
• 🐛 问题：创建GitHub问题
• 💬 讨论：GitHub讨论
• 📧 联系方式：请参阅存储库贡献者

______________________________________________________________________

准备好开始了吗？

🐳 Docker用户: docker compose up --build 🐍 本地用户: pip install -r requirements.txt && python -m mcp_script_runner.server