Harmony 2.0 Master Agent - Gemini MCP Server
A powerful Gemini-powered agent that serves as the master guide for Harmony 2.0 development, accessible via Model Context Protocol (MCP) for Cursor and other MCP-compatible tools.
🌟 Features
- Harmony 2.0 Expert: Deep knowledge of Harmony 2.0 architecture, patterns, and best practices
- MCP Integration: Full Model Context Protocol support for Cursor and other tools
- Free Tier Compatible: Designed to run on free-tier hosting services
- Multiple Interfaces:
- MCP server for Cursor integration
- REST API for external access
- Direct programmatic access
📋 Prerequisites
- Node.js 18+
- Gemini API key (free tier available at Google AI Studio)
🚀 Quick Start
1. Install Dependencies
npm install
2. Configure Environment
Copy .env.example to .env and add your Gemini API key:
cp .env.example .env
Edit .env:
GEMINI_API_KEY=your_gemini_api_key_here
PORT=3000
3. Local Development
Run the REST API Server:
npm start
The API will be available at http://localhost:3000
Run the MCP Server (for Cursor):
npm run mcp
🔧 Cursor Integration
Option 1: Local MCP Server
- Add to your Cursor MCP configuration (usually in
~/.cursor/mcp.jsonor Cursor settings):
{
"mcpServers": {
"harmony2-master": {
"command": "node",
"args": ["/absolute/path/to/harmony2-gemini-mcp/src/mcp-server.js"],
"env": {
"GEMINI_API_KEY": "your_gemini_api_key_here"
}
}
}
}
- Restart Cursor
- The Harmony 2.0 tools will appear in Cursor's MCP tools section
Option 2: External MCP Server (Recommended for Sharing)
Deploy the server (see Deployment section) and configure Cursor to connect to it.
🌐 Deployment (Free Tier Options)
Option 1: Vercel (Recommended)
- Install Vercel CLI:
npm i -g vercel
- Deploy:
vercel
- Set environment variable:
vercel env add GEMINI_API_KEY
- Your API will be available at
https://your-project.vercel.app
Option 2: Render
- Create a new Web Service on Render
- Connect your GitHub repository
- Use these settings:
- Build Command:
npm install - Start Command:
npm start
- Build Command:
- Add
GEMINI_API_KEYin Environment Variables - Deploy!
Option 3: Railway
- Create a new project on Railway
- Connect your GitHub repository
- Add
GEMINI_API_KEYenvironment variable - Deploy!
Option 4: Fly.io
- Install Fly CLI:
curl -L https://fly.io/install.sh | sh
- Initialize:
fly launch
- Set secrets:
fly secrets set GEMINI_API_KEY=your_key_here
- Deploy:
fly deploy
📡 API Endpoints
Health Check
GET /health
Chat with Harmony Agent
POST /api/chat
Body: {
"message": "How do I set up a new Harmony 2.0 project?",
"context": {} // optional
}
Analyze Code
POST /api/analyze
Body: {
"code": "your code here",
"language": "javascript" // optional
}
Generate Code
POST /api/generate
Body: {
"description": "Create a React component for user authentication",
"componentType": "component" // optional
}
Get Guidance
POST /api/guidance
Body: {
"topic": "state management"
}
🛠️ MCP Tools
The MCP server exposes these tools:
- harmony_chat - Chat with the Harmony 2.0 Master Agent
- harmony_analyze_code - Analyze code for Harmony 2.0 compliance
- harmony_generate_code - Generate code following Harmony 2.0 patterns
- harmony_get_guidance - Get comprehensive guidance on Harmony 2.0 topics
📚 Harmony 2.0 Resources
🔐 Security Notes
- Never commit your
.envfile - Keep your Gemini API key secure
- For production, use environment variables provided by your hosting platform
- Consider rate limiting for public APIs
🆓 Free Tier Limits
- Gemini API: Free tier includes generous usage limits
- Vercel: 100GB bandwidth/month, unlimited requests
- Render: 750 hours/month, 512MB RAM
- Railway: $5 free credit/month
- Fly.io: 3 shared VMs, 3GB storage
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📝 License
MIT
🆘 Support
For issues or questions:
- Check the Harmony 2.0 documentation
- Open an issue on GitHub
- Contact the Harmony 2.0 community
Built with ❤️ for the Harmony 2.0 community