Development
This guide covers setting up LazyMCP for local development, building from source, and contributing to the project.
Prerequisites
- Go: Version 1.24 or later
- Git: For cloning the repository
- OpenWeatherMap API Key: Required for weather tools (free)
Local Setup
1. Clone the Repository
git clone https://github.com/Riddlerrr/lazymcp.git
cd lazymcp
2. Install Dependencies
go mod download
3. Configure Weather Tools
Weather tools require an OpenWeatherMap API key for local development:
- Get a free API key from OpenWeatherMap
- Copy the environment file:
cp .env.example .env
- Edit
.env
and add your API key:OPENWEATHER_API_KEY=your_api_key_here
For detailed configuration, see the Configuration Guide.
Building LazyMCP
Development Build
bin/build
Production Build
For optimized builds with stripped symbols:
bin/build_release
Running Locally
Start the Development Server
bin/run
The server will start on http://localhost:3000/mcp
using streamable HTTP transport.
Verify Installation
You should see output similar to:
LazyMCP server starting on :3000
Available tools: calculate, get_ip, get_ip_data, get_weather, get_weather_forecast
Development Mode
For hot reloading during development:
go run main.go
This provides:
- Detailed error messages and stack traces
- Debug logging information
- No need to rebuild for code changes
Testing
Run All Tests
bin/test
Run Specific Tool Tests
go test ./tools
Test Individual Components
# Calculator tests
go test ./tools -run TestCalculator
# Weather tests
go test ./tools -run TestWeather
# IP tools tests
go test ./tools -run TestIP
Project Structure
lazymcp/
├── main.go # Server entry point
├── tools/ # Tool implementations
│ ├── calculator.go # Mathematical expression evaluator
│ ├── calculator_test.go # Calculator tests
│ ├── ip.go # IP lookup and geolocation
│ ├── ip_test.go # IP tools tests
│ ├── weather.go # Weather and forecast tools
│ └── weather_test.go # Weather tests
├── test/
│ └── fixtures/ # Test data fixtures
├── bin/ # Build scripts
├── go.mod # Go module definition
├── go.sum # Dependency checksums
├── .env.example # Environment variables template
└── README.md # Project documentation
Adding New Tools
Tools are implemented in the tools/
package and registered in main.go
. Each tool should:
1. Implement the Tool Interface
type Tool struct {
Tool mcp.Tool
Handler mcp.ToolHandler
}
2. Follow the Naming Convention
- Tool file:
tools/newtool.go
- Test file:
tools/newtool_test.go
- Constructor:
NewNewToolTool()
3. Include Error Handling
All tools should handle:
- Invalid parameters
- Network errors (for API calls)
- Service unavailability
- Rate limiting
4. Write Comprehensive Tests
- Unit tests for all functionality
- Error condition testing
- Mock external API calls
- Use fixtures for large test data
5. Register in Main
Add your tool to main.go
:
newTool := tools.NewNewToolTool()
mcpServer.AddTool(newTool.Tool, newTool.Handler)
Code Style
Go Conventions
- Follow standard Go formatting (
gofmt
) - Use descriptive variable names
- Include package documentation
- Handle all errors appropriately
Error Messages
- Provide clear, actionable error messages
- Include context about what failed
- Suggest solutions when possible
Testing Best Practices
- Test both success and failure cases
- Use table-driven tests for multiple scenarios
- Mock external dependencies
- Keep test fixtures in
test/fixtures/
Contributing
Before Submitting
- Run all tests:
bin/test
- Format code:
go fmt ./...
- Check for issues:
go vet ./...
- Update documentation: Update relevant docs if needed
Pull Request Guidelines
- Clear description: Explain what changes and why
- Single purpose: One feature or fix per PR
- Tests included: Add tests for new functionality
- Documentation updated: Update relevant documentation
Commit Message Format
type: brief description
Longer explanation if needed, wrapped at 72 characters.
Include motivation for the change and contrast with previous behavior.
Types:
feat:
- New featuresfix:
- Bug fixesdocs:
- Documentation changestest:
- Test additions or changesrefactor:
- Code refactoringperf:
- Performance improvements
Deployment
Local Development
For local development and testing:
# Development server
bin/run
# With debug logging
DEBUG=true bin/run
Production Deployment
For production deployments:
- Build optimized binary:
bin/build_release
- Set environment variables: Configure
OPENWEATHER_API_KEY
- Configure networking: Set up reverse proxy with HTTPS
- Monitor health: Implement health checks and logging
See the Configuration Guide for detailed deployment instructions.
Debugging
Common Development Issues
Build failures: Ensure Go version 1.24+ and all dependencies installed
Test failures: Check API keys are set in .env
file
Port conflicts: Change port if 3000 is in use: PORT=8080 bin/run
Debug Logging
Enable detailed logging:
# Set debug environment variable
export DEBUG=true
go run main.go
# Or use with build script
DEBUG=true bin/run
Testing with cURL
Test MCP endpoints directly:
# Health check (if implemented)
curl http://localhost:3000/health
# Test MCP protocol (requires MCP client)
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"method":"tools/list"}'
Resources
- Go Documentation: golang.org
- MCP Protocol: Model Context Protocol Specification
- OpenWeatherMap API: API Documentation
- Project Issues: GitHub Issues
Support
For development questions and contributions:
- GitHub Discussions: General questions and ideas
- GitHub Issues: Bug reports and feature requests
- Pull Requests: Code contributions and improvements