Softpack MCP服务器
一个全面的基于FastAPI的MCP（模型上下文协议）服务器，使LLM和外部服务能够与垃圾邮件包管理命令进行交互。该服务器是Softpack生态系统的一部分，在语言模型和spack包管理器之间提供了一个完整的桥梁，包括会话管理、配方构建和Git集成。
特性
- 🚀 FastAPI集成：具有自动API文档的现代异步/等待web框架
- 🔧 MCP协议：通过fastapi-mcp与语言模型无缝集成
- 📦 垃圾邮件命令：垃圾邮件包管理操作的完整界面
- 🎯 会话管理：用于包开发的独立工作区
- 📝 配方构建：交互式配方创建和管理
- 🔄 Git集成：用于包工作流的自动化Git操作
- 📊 结构化日志记录：全面的日志记录，包括轮换和上下文
- 🛡️ 错误处理：强大的异常处理和验证
- 🔒 安全：CORS和身份验证支持
- 📖 汽车文档：带有Swagger UI的交互式API文档
- 🌐 Web向导界面：用于包创建和管理的交互式6步向导
MCP工具可用
服务器向LLM公开了以下全面的工具集：
垃圾邮件包管理
search_packages-搜索可用的垃圾邮件包list_packages-列出已安装的软件包get_package_info-获取全面的包裹信息install_package-安装带有变体的垃圾邮件包install_package_stream-安装实时流输出uninstall_package-删除已安装的软件包uninstall_package_with_dependents-删除包和所有依赖项copy_existing_package-将现有包从内置复制到会话get_package_versions-获取软件包的可用版本get_package_checksums-获取包版本的校验和create_pypi_package-从PyPI创建spack包create_recipe_from_url-从URL创建垃圾邮件包validate_package-验证包装配方validate_package_stream-通过实时流媒体进行验证
会话管理
create_session-创建独立的开发会话list_sessions-列出所有活动会话get_session_info-获取会话详细信息delete_session-删除会话和所有内容list_session_files-列出会话目录中的文件
配方管理
create_recipe-创建新的包装配方list_recipes-列出会话中的所有食谱read_recipe-阅读食谱内容write_recipe-编写/更新食谱内容delete_recipe-删除配方validate_recipe-验证配方语法和内容get_recipe_info-获取配方元数据
Git操作
pull_spack_repo-拉取最新的垃圾邮件仓库更新get_git_commit_info-获取存储库的提交信息create_pull_request-为包创建拉取请求
访问管理
request_collaborator_access-请求GitHub合作者访问权限
快速开始
先决条件
- Python 3.10+
- 已安装Spack包管理器
- Git（用于存储库操作）
安装
- 克隆存储库：
git clone
cd softpack-mcp- 初始化项目：
make init这将：
- 使用uv安装依赖项
- 设置预提交挂钩
- 创建必要的目录
- 创建一个
.env具有默认值的文件
运行服务器
开发模式（仅后端）
make debug生产模式（后端+前端）
make prod仅限前端
make frontend配置
环境变量
应用程序使用环境变量进行配置。复制 .env.example 向 .env 并根据需要进行修改：
cp .env.example .env可用环境变量
SOFTPACK_HOST：后端服务器主机（默认值：127.0.0.1)SOFTPACK_PORT：后端服务器端口（默认值：8000)SOFTPACK_DEBUG：启用调试模式（默认值：false)SOFTPACK_LOG_LEVEL：日志记录级别（默认值：INFO)SOFTPACK_SPACK_EXECUTABLE：垃圾邮件可执行文件的路径（默认值：spack)SOFTPACK_COMMAND_TIMEOUT：命令执行超时（秒）（默认值：300)API_BASE_URL：前端API基本URL（默认值：http://localhost:8000)
API文档
服务器运行后，请访问：
- 交互式API文档: http://localhost:8000/docs
- ReDoc文档: http://localhost:8000/redoc
- 健康检查: http://localhost:8000/health
- Web向导界面: http://localhost:8001
Web向导界面
该项目包括一个全面的基于web的向导界面(index.html)它提供了一个交互式的6步工作流，用于创建和管理spack包：
向导步骤
- 包裹信息 -输入包名称和类型（Python、R或其他）
- 配方存在检查 -自动检查配方是否已存在于spack仓库中
- 配方创建/版本管理 -创建新配方或管理现有配方的版本
- 配方修改 -交互式配方编辑器，具有语法高亮显示和验证功能
- 构建和测试 -安装包并运行具有实时输出的验证测试
- 创建拉取请求 -准备Git操作并请求协作者访问
主要特点
- 交互式配方编辑器 -带有实时验证的语法高亮编辑器
- 实时流媒体 -包安装和验证的实时输出
- 自动配方生成 -支持PyPI包和现有的spack食谱
- 会话管理 -用于包开发的独立工作区
- Git集成 -自动创建分支和拉取请求准备
- 访问管理 -内置合作者访问请求系统
- 进度跟踪 -可视化进度条和分步指导
访问向导
向导在端口8001上提供，并自动连接到API服务器：
# Start both backend and frontend
make prod
# Or start frontend only (requires backend on port 8000)
make frontend然后访问：http://localhost:8001
核心功能
会话管理
服务器为包构建提供独立的开发会话：
# Create a new session
curl -X POST "http://localhost:8000/sessions/create" \
-H "Content-Type: application/json" \
-d '{"namespace": "my-packages"}'
# List sessions
curl "http://localhost:8000/sessions/list"配方构建
会话中的交互式配方创建和管理：
# Create a new recipe
curl -X POST "http://localhost:8000/recipes/{session_id}/{package_name}/create"
# Write recipe content
curl -X PUT "http://localhost:8000/recipes/{session_id}/{package_name}" \
-H "Content-Type: application/json" \
-d '{"content": "class MyPackage(Package): ..."}'
# Validate recipe
curl -X POST "http://localhost:8000/recipes/{session_id}/{package_name}/validate" \
-H "Content-Type: application/json" \
-d '{"content": "class MyPackage(Package): ..."}'流操作
长时间运行操作的实时流媒体：
# Streaming installation
curl -X POST "http://localhost:8000/spack/install/stream" \
-H "Content-Type: application/json" \
-d '{"package_name": "zlib", "version": "1.2.13"}' \
--no-buffer
# Streaming validation
curl -X POST "http://localhost:8000/spack/validate/stream" \
-H "Content-Type: application/json" \
-d '{"session_id": "my-session", "package_name": "my-package"}' \
--no-bufferGit集成
用于包工作流的自动化Git操作：
# Pull latest spack-repo updates
curl -X POST "http://localhost:8000/git/pull" \
-H "Content-Type: application/json" \
-d '{"repo_path": "/path/to/spack-repo"}'
# Create pull request
curl -X POST "http://localhost:8000/git/pull-request" \
-H "Content-Type: application/json" \
-d '{"package_name": "my-package", "session_id": "my-session"}'例子
请参阅 examples/ 完整工作示例目录：
session_example.py-会话管理工作流程recipe_example.py-配方创建和验证copy_package_example.py-复制现有包streaming_client.py-流媒体安装客户端
发展
设置开发环境
# Initialize the project (installs dependencies and sets up pre-commit)
make init运行测试
# Run all tests
pytest
# Run with coverage
pytest --cov=softpack_mcp
# Run integration tests
make test-integration代码质量
# Format and lint code
uv run ruff check . --fix
uv run ruff format .
# Run pre-commit on all files
uv run pre-commit run --all-files项目结构
softpack-mcp/
├── softpack_mcp/ # Main application package
│ ├── __init__.py
│ ├── main.py # FastAPI application
│ ├── config.py # Configuration management
│ ├── repos.yaml # Spack repository configuration
│ ├── models/ # Pydantic models
│ │ ├── requests.py # Request models
│ │ └── responses.py # Response models
│ ├── tools/ # MCP tool implementations
│ │ ├── spack.py # Spack tool endpoints
│ │ ├── sessions.py # Session management
│ │ ├── recipes.py # Recipe management
│ │ ├── git.py # Git operations
│ │ └── access.py # Access management
│ ├── services/ # Business logic layer
│ │ ├── spack_service.py # Spack service
│ │ ├── session_manager.py # Session management
│ │ ├── git_service.py # Git operations
│ │ └── access_service.py # Access management
│ └── utils/ # Utility modules
│ ├── logging.py # Logging configuration
│ └── exceptions.py # Custom exceptions
├── examples/ # Example scripts and clients
│ ├── session_example.py # Session management example
│ ├── recipe_example.py # Recipe building example
│ ├── copy_package_example.py # Package copying example
│ ├── streaming_client.py # Streaming client example
│ └── README.md # Examples documentation
├── tests/ # Test suite
├── index.html # Web wizard interface for package creation
├── serve_frontend.py # Frontend server
├── run_both.py # Combined server runner
├── Makefile # Build and run commands
├── pyproject.toml # Project configuration
└── README.md # This file贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 进行更改
- 添加新功能的测试
- 确保所有测试通过(
pytest) - 运行代码质量检查(
uv run pre-commit run --all-files) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
支持
- 📧 电子邮件：hgi@sanger.ac.uk
- 🐛 问题：
- 📖 文档： API文件
致谢
- 内置于 快速 API
- MCP集成通过 fastapi-mcp
- Spack包管理器支持
- Softpack生态系统的一部分