smolval
一个轻量级的容器化Python应用程序，用于使用Claude Code CLI评估MCP（模型上下文协议）服务器。smolval提供了一个自包含的Docker环境，内置了Claude Code CLI、开发工具和MCP服务器支持，用于系统化的MCP服务器评估。
✨ 特性
- 独立式集装箱：Claude Code CLI和预安装的所有工具，零主机依赖性
- MCP服务器评估：使用Claude Code的代理功能进行系统测试
- Docker中的Docker支持：具有容器支持的完全MCP服务器隔离
- 多种输出格式：JSON、CSV、Markdown和HTML结果
- 进度指标：评估过程中的视觉反馈，并跟踪经过的时间
- 标准配置：用途
.mcp.json格式与克劳德桌面/光标兼容
🚀 快速开始
先决条件
- 码头工人
- ANTHROPIC_API_键
一个命令设置
# Clone repository
git clone https://github.com/austinlparker/smolval.git
cd smolval
# Build container (includes Claude Code CLI and all tools)
docker build -t ghcr.io/austinlparker/smolval .
# Run your first evaluation - no local installation required!
docker run --rm \
-v $(pwd):/workspace \
-e ANTHROPIC_API_KEY \
ghcr.io/austinlparker/smolval eval /workspace/prompts/simple_test.txt对于需要Docker的MCP服务器
# Enable Docker-in-Docker for containerized MCP servers
docker run --rm \
-v $(pwd):/workspace \
-v /var/run/docker.sock:/var/run/docker.sock \
-e ANTHROPIC_API_KEY \
ghcr.io/austinlparker/smolval eval /workspace/prompts/database-test.txt📖 文档
综合文档可在 docs/ 目录：
🛠️ 命令
单项评价
# Basic evaluation using Claude Code's built-in tools
docker run --rm \
-v $(pwd):/workspace \
-e ANTHROPIC_API_KEY \
ghcr.io/austinlparker/smolval eval /workspace/prompts/file-test.txt
# With specific output format
docker run --rm \
-v $(pwd):/workspace \
-e ANTHROPIC_API_KEY \
ghcr.io/austinlparker/smolval eval /workspace/prompts/file-test.txt --format html自定义MCP配置
# Use custom .mcp.json configuration
docker run --rm \
-v $(pwd):/workspace \
-v /var/run/docker.sock:/var/run/docker.sock \
-e ANTHROPIC_API_KEY \
ghcr.io/austinlparker/smolval eval /workspace/prompts/test.txt --mcp-config /workspace/.mcp.json跑 docker run --rm ghcr.io/austinlparker/smolval --help 对于所有选项。
⚙️ 配置
smolval使用标准 .mcp.json 与Claude Desktop和Cursor兼容的配置格式：
{
"mcpServers": {
"sqlite": {
"command": "docker",
"args": ["run", "--rm", "-i", "mcp/sqlite"],
"env": {}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"env": {}
}
}
}备注：Claude Code内置了文件系统和web获取功能，因此MCP服务器只需要用于数据库、API等其他功能。
示例配置可在 docs/examples/ 目录。
🐳 集装箱特征
预装工具
- 克劳德代码CLI：最新版本已准备就绪
- Node.js和npm/npx：适用于基于NPM的MCP服务器
- Docker命令行界面：用于容器化MCP服务器
- 开发工具：git、vim、树、jq、uvx
- MCP服务器：预装了通用服务器，可加快启动速度
批量安装策略
# Basic workspace mount
-v $(pwd):/workspace
# Docker-in-Docker support
-v /var/run/docker.sock:/var/run/docker.sock
# Custom output directory
-v $(pwd)/results:/results环境变量
# Required
-e ANTHROPIC_API_KEY
# Optional
-e CLAUDE_CONFIG_DIR=/app/.claude🧪 测试
在容器中运行测试套件：
# Build development image
docker build -t ghcr.io/austinlparker/smolval:dev .
# Unit tests only
docker run --rm \
-v $(pwd):/workspace \
-w /workspace \
ghcr.io/austinlparker/smolval:dev uv run pytest -m "not integration and not slow"
# All tests
docker run --rm \
-v $(pwd):/workspace \
-w /workspace \
ghcr.io/austinlparker/smolval:dev uv run pytest
# With coverage
docker run --rm \
-v $(pwd):/workspace \
-w /workspace \
ghcr.io/austinlparker/smolval:dev uv run pytest --cov=smolval --cov-report=html看 tests/README.md 获取详细的测试信息。
📊 MCP服务器支持
smolval通过容器支持各种MCP服务器类型：
- 内置Claude代码工具：文件系统操作、web内容获取
- 预装NPM:
@modelcontextprotocol/server-filesystem,@modelcontextprotocol/server-memory - 基于Docker:
mcp/sqlite，在Docker中通过Docker自定义容器 - 基于Python：任何可安装uvx的MCP服务器
🔧 发展
集装箱优先发展
# Interactive development container
docker run -it --rm \
-v $(pwd):/workspace \
-v /var/run/docker.sock:/var/run/docker.sock \
-e ANTHROPIC_API_KEY \
-w /workspace \
ghcr.io/austinlparker/smolval:dev bash
# Code quality checks in container
docker run --rm \
-v $(pwd):/workspace \
-w /workspace \
ghcr.io/austinlparker/smolval:dev bash -c "uv run black src/ tests/ && uv run isort src/ tests/ && uv run ruff check src/ tests/ && uv run mypy src/"项目结构
smolval/
├── src/smolval/ # Main application code
├── docs/ # Documentation
├── tests/ # Test suite
├── prompts/ # Example evaluation prompts
└── results/ # Generated evaluation results📋 需求
- 码头工人：仅主机系统要求
- ANTHROPIC_API_键：Claude Code CLI的环境变量
📄 许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
🤝 贡献
欢迎投稿！请阅读 架构文档 并在提交更改之前检查测试套件。
- 分叉存储库
- 创建要素分支
- 通过测试进行更改
- 进行质量检查
- 提交拉取请求