mirror of
https://github.com/hanzoai/stack.git
synced 2026-11-19 03:06:57 +00:00
5.8 KiB
5.8 KiB
Hanzo MCP Development Guide
This guide explains how to work with and publish the hanzo-mcp package within the Hanzo IDE monorepo.
Overview
The hanzo-mcp package is integrated into the IDE monorepo as a local development dependency. This allows:
- Seamless Development: Changes to MCP are immediately available in the IDE
- Independent Publishing: MCP can be published to PyPI separately
- Version Control: Both IDE and MCP share the same git history
Project Structure
ide/
├── app/dev/
│ ├── pyproject.toml # IDE dependencies (includes hanzo-mcp as local dep)
│ └── ide/ # IDE source code
├── pkg/
│ ├── mcp/ # hanzo-mcp package
│ │ ├── pyproject.toml # MCP package config
│ │ ├── hanzo_mcp/ # MCP source code
│ │ ├── Makefile # MCP-specific commands
│ │ └── scripts/
│ │ └── publish.sh # Publishing helper
│ ├── aci/ # hanzo-aci package
│ └── mcp-client/ # hanzo-mcp-client package
Development Workflow
1. Local Development
The IDE uses MCP as a local development dependency:
# In app/dev/pyproject.toml
hanzo-mcp = { path = "../../pkg/mcp", develop = true }
This means:
- Changes to MCP code are immediately reflected in IDE
- No need to reinstall after changes
- IDE and MCP can be developed together
2. Making Changes
# From the IDE root
cd pkg/mcp
# Make your changes to hanzo_mcp/
vim hanzo_mcp/tools/my_new_tool.py
# Run tests
make test
# Format code
make format
# The changes are immediately available in IDE!
3. Testing in IDE
# From IDE root
cd app/dev
make dev # Starts IDE with your MCP changes
Publishing Workflow
Quick Method: Using the Makefile
cd pkg/mcp
# Check current version
make version
# Bump version (choose one)
make bump-patch # 0.6.13 -> 0.6.14
make bump-minor # 0.6.13 -> 0.7.0
make bump-major # 0.6.13 -> 1.0.0
# Run full release process
make release
Detailed Method: Step by Step
-
Update Version:
cd pkg/mcp # Edit pyproject.toml and update version vim pyproject.toml -
Run Tests:
make test make lint -
Build Package:
make build -
Publish to Test PyPI (recommended first):
make publish-test # Test installation: pip install -i https://test.pypi.org/simple/ hanzo-mcp==0.6.14 -
Publish to PyPI:
make publish
Using the Publish Script
For a guided publishing experience:
cd pkg/mcp
./scripts/publish.sh
This script will:
- Check for uncommitted changes
- Run tests and linting
- Build the package
- Guide you through publishing to Test PyPI or PyPI
- Create a git tag
Version Management
Version Conventions
- Patch (0.6.X): Bug fixes, minor improvements
- Minor (0.X.0): New features, backwards compatible
- Major (X.0.0): Breaking changes
Coordinating with IDE Versions
The IDE and MCP can have independent version numbers. However:
- IDE Release: Can pin to specific MCP version
- MCP Update: IDE automatically uses latest local version
- Production: IDE Docker images include specific MCP version
After Publishing
-
Create Git Tag:
git tag -a "mcp-v0.6.14" -m "Release hanzo-mcp 0.6.14" git push origin mcp-v0.6.14 -
Update IDE (if needed):
# If you want IDE to use the published version instead of local cd app/dev # Edit pyproject.toml: # hanzo-mcp = "^0.6.14" # Instead of path dependency -
Update Docker Images:
# The build process will use the wheel from pkg/mcp/dist/ cd app/dev make build-docker
CI/CD Integration
GitHub Actions
Push a tag to trigger automated publishing:
git tag -a "mcp-v0.6.14" -m "Release hanzo-mcp 0.6.14"
git push origin mcp-v0.6.14
This will:
- Run tests
- Build packages
- Publish to PyPI
- Create GitHub release
Manual Workflow Dispatch
From GitHub Actions tab:
- Select "Publish Hanzo MCP" workflow
- Click "Run workflow"
- Enter version and choose PyPI/Test PyPI
Troubleshooting
Common Issues
-
Import Errors in IDE:
cd app/dev poetry install # Reinstall dependencies -
Tests Failing:
# Run specific test pytest tests/test_specific.py -v # Run with debugging pytest -vvs -
Build Errors:
# Clean and rebuild make clean make build -
Publishing Authentication:
# Create ~/.pypirc with your API token cat > ~/.pypirc << EOF [pypi] username = __token__ password = pypi-...your-token... EOF
PyPI API Tokens
- Go to https://pypi.org/manage/account/token/
- Create a token scoped to
hanzo-mcp - Add to
~/.pypircor GitHub secrets
Best Practices
- Test Locally First: Always test changes in IDE before publishing
- Use Test PyPI: Test package installation before production
- Semantic Versioning: Follow version conventions
- Document Changes: Update CHANGELOG.md
- Backwards Compatibility: Avoid breaking changes in minor versions
Docker Considerations
When building IDE Docker images:
- Wheels are cached: Built wheels in
pkg/mcp/dist/are used - Version in Docker: Check
wheels/hanzo_mcp-*.whlin Dockerfile - Update Process:
cd pkg/mcp make build # Creates wheel cd ../../app/dev make build-docker # Uses the wheel
Questions?
- IDE Integration: Check
app/dev/pyproject.toml - MCP Package: See
pkg/mcp/README.md - Publishing: Run
make helpinpkg/mcp/