smolval (Austinlparker)

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/ 目录：

• 入门指南 -安装和设置指南
• CLI参考 -完整的命令行文档
• 配置 -配置选项和示例
• 写作提示 -创建有效评估提示的指南
• 例子 -示例提示和配置
• 建筑 -技术设计和实施细节

🛠️ 命令

单项评价

# 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许可证获得许可-有关详细信息，请参阅许可证文件。

🤝 贡献

欢迎投稿！请阅读 架构文档 并在提交更改之前检查测试套件。

1. 分叉存储库
2. 创建要素分支
3. 通过测试进行更改
4. 进行质量检查
5. 提交拉取请求

📚 了解更多

• 模型上下文协议 -了解MCP
• 重演模式 -smolval使用的推理模式
• 项目文件 -全面的指南和参考