Development¶
This guide covers developing with and contributing to haive-mcp.
Development Setup¶
Setting up the development environment:
# Clone the repository
git clone https://github.com/your-org/haive
cd haive
# Install with development dependencies
poetry install --all-extras --with dev
# Install pre-commit hooks
poetry run pre-commit install
# Verify installation
poetry run pytest packages/haive-mcp/tests/ -v
Project Structure¶
The haive-mcp package is organized as follows:
packages/haive-mcp/
├── src/haive/mcp/
│ ├── __init__.py # Package exports
│ ├── config.py # Configuration models
│ ├── manager.py # MCP server management
│ ├── agents/ # MCP-enabled agents
│ │ ├── mcp_agent.py # Main MCP agent
│ │ ├── documentation_agent.py
│ │ └── transferable_mcp_agent.py
│ ├── discovery/ # Server discovery
│ │ ├── analyzer.py # Server analysis
│ │ └── server_discovery.py # Discovery logic
│ ├── mixins/ # Mixin classes
│ │ └── mcp_mixin.py # MCP capabilities mixin
│ ├── servers/ # Server implementations
│ │ ├── dataflow_mcp_server.py
│ │ └── example_server_fastmcp.py
│ └── tools/ # Utility tools
├── tests/ # Test suite
├── docs/ # Documentation
├── examples/ # Usage examples
└── README.md # Package documentation
Running Tests¶
The test suite includes unit tests, integration tests, and examples:
# Run all tests
poetry run pytest packages/haive-mcp/tests/
# Run with coverage
poetry run pytest packages/haive-mcp/tests/ --cov=haive.mcp
# Run specific test file
poetry run pytest packages/haive-mcp/tests/test_config.py -v
# Run integration tests (requires MCP servers)
poetry run pytest packages/haive-mcp/tests/integration/ -v
# Run examples as tests
poetry run python packages/haive-mcp/examples/basic_mcp_example.py
Writing Tests¶
Test Structure¶
Tests are organized by module:
tests/
├── unit/ # Unit tests
│ ├── test_config.py # Configuration tests
│ ├── test_manager.py # Manager tests
│ └── test_agents.py # Agent tests
├── integration/ # Integration tests
│ ├── test_mcp_servers.py # Server integration
│ └── test_full_workflow.py
└── fixtures/ # Test fixtures
├── mock_servers.py # Mock MCP servers
└── test_configs.py # Test configurations
Example Test¶
import pytest
from haive.mcp.config import MCPConfig, MCPServerConfig
from haive.mcp.manager import MCPManager
class TestMCPConfig:
"""Test MCP configuration."""
def test_basic_config_creation(self):
"""Test creating a basic MCP configuration."""
config = MCPConfig(
enabled=True,
servers={
"test": MCPServerConfig(
name="test",
transport="stdio",
command="echo",
args=["hello"]
)
}
)
assert config.enabled is True
assert len(config.servers) == 1
assert config.servers["test"].name == "test"
def test_server_validation(self):
"""Test server configuration validation."""
with pytest.raises(ValidationError):
MCPServerConfig(
name="", # Invalid empty name
transport="invalid_transport"
)
@pytest.mark.asyncio
async def test_manager_integration(self):
"""Test manager with configuration."""
config = MCPConfig(enabled=True)
manager = MCPManager(config)
# Test manager initialization
assert manager.enabled is True
assert len(manager._servers) == 0
Mock Servers¶
For testing without actual MCP servers:
import asyncio
from unittest.mock import AsyncMock, MagicMock
@pytest.fixture
def mock_mcp_client():
"""Mock MCP client for testing."""
client = AsyncMock()
client.connect = AsyncMock(return_value=True)
client.list_tools = AsyncMock(return_value=[
{"name": "test_tool", "description": "A test tool"}
])
client.call_tool = AsyncMock(return_value={"result": "success"})
return client
@pytest.mark.asyncio
async def test_with_mock_server(mock_mcp_client):
"""Test agent with mocked MCP server."""
# Use mock client in test
pass
Code Style¶
The project follows strict coding standards:
Python Style¶
PEP 8 compliance with 88-character line limit
Type hints for all public functions and methods
Google-style docstrings for documentation
Black for code formatting
isort for import sorting
mypy for static type checking
from typing import Dict, List, Optional
def process_servers(
servers: Dict[str, MCPServerConfig],
categories: Optional[List[str]] = None
) -> List[str]:
"""Process MCP server configurations.
Args:
servers: Dictionary of server configurations
categories: Optional list of categories to filter by
Returns:
List of processed server names
Raises:
ValueError: If server configuration is invalid
"""
result = []
for name, config in servers.items():
if categories and config.category not in categories:
continue
result.append(name)
return result
Documentation Style¶
Google-style docstrings for all public APIs
Sphinx autodoc compatible
Type annotations in docstrings
Examples in docstrings where helpful
class MCPAgent:
"""An agent with MCP capabilities.
This agent extends SimpleAgent with MCP server integration,
providing access to external tools and resources.
Attributes:
mcp_config: Optional MCP configuration
Example:
Basic usage::
agent = MCPAgent(
engine=engine,
mcp_config=mcp_config
)
await agent.setup()
"""
Linting and Formatting¶
# Format code
poetry run black packages/haive-mcp/
# Sort imports
poetry run isort packages/haive-mcp/
# Type checking
poetry run mypy packages/haive-mcp/src/
# Lint code
poetry run ruff check packages/haive-mcp/
# Run all checks
poetry run pre-commit run --all-files
Contributing Guidelines¶
Pull Request Process¶
Fork the repository and create a feature branch
Write tests for new functionality
Update documentation including docstrings and guides
Run the full test suite and ensure all tests pass
Submit a pull request with a clear description
Commit Messages¶
Use conventional commit format:
feat(mcp): add health monitoring for MCP servers
fix(agents): resolve tool discovery timeout issue
docs(mcp): improve configuration examples
test(manager): add integration tests for server lifecycle
Code Review Checklist¶
Before submitting, ensure:
[ ] All tests pass
[ ] Code coverage is maintained
[ ] Type hints are included
[ ] Docstrings follow Google style
[ ] Examples are included for new features
[ ] Documentation is updated
[ ] No breaking changes (or marked as such)
[ ] Performance impact is considered
Release Process¶
Version Management¶
The project uses semantic versioning:
MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes
# Update version
poetry version patch|minor|major
# Tag release
git tag v0.2.0
git push origin v0.2.0
Building Documentation¶
# Install docs dependencies
poetry install --extras docs
# Build documentation
cd packages/haive-mcp/docs
poetry run sphinx-build -b html . _build/html
# Serve locally
poetry run python -m http.server 8000 -d _build/html
Publishing¶
# Build package
poetry build
# Publish to PyPI (with proper credentials)
poetry publish
Debugging¶
Common Issues¶
- Import Errors
Check that all dependencies are installed
Verify PYTHONPATH includes the src directory
Use poetry shell to activate the virtual environment
- MCP Server Connection Issues
Verify MCP servers are installed and accessible
Check server startup logs for errors
Enable debug logging for detailed connection info
- Test Failures
Ensure test dependencies are installed
Check that mock servers are configured correctly
Run tests individually to isolate issues
Debug Configuration¶
import logging
# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("haive.mcp")
logger.setLevel(logging.DEBUG)
# Debug specific components
logging.getLogger("haive.mcp.manager").setLevel(logging.DEBUG)
logging.getLogger("haive.mcp.agents").setLevel(logging.DEBUG)
Performance Profiling¶
import cProfile
import pstats
# Profile MCP operations
profiler = cProfile.Profile()
profiler.enable()
# Run MCP operations
await agent.setup()
result = await agent.arun({"messages": [...]})
profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative').print_stats(10)
Getting Help¶
Documentation: Read the full documentation at https://haive-mcp.readthedocs.io
Issues: Report bugs and feature requests on GitHub
Discussions: Ask questions in GitHub Discussions
Discord: Join the community Discord for real-time help
Email: Contact the maintainers for security issues