# 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](https://makersuite.google.com/app/apikey))
## 🚀 Quick Start
### 1. Install Dependencies
```bash
npm install
```
### 2. Configure Environment
Copy `.env.example` to `.env` and add your Gemini API key:
```bash
cp .env.example .env
```
Edit `.env`:
```
GEMINI_API_KEY=your_gemini_api_key_here
PORT=3000
```
### 3. Local Development
#### Run the REST API Server:
```bash
npm start
```
The API will be available at `http://localhost:3000`
#### Run the MCP Server (for Cursor):
```bash
npm run mcp
```
## 🔧 Cursor Integration
### Option 1: Local MCP Server
1. Add to your Cursor MCP configuration (usually in `~/.cursor/mcp.json` or Cursor settings):
```json
{
"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"
}
}
}
}
```
2. Restart Cursor
3. 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)
1. Install Vercel CLI:
```bash
npm i -g vercel
```
2. Deploy:
```bash
vercel
```
3. Set environment variable:
```bash
vercel env add GEMINI_API_KEY
```
4. Your API will be available at `https://your-project.vercel.app`
### Option 2: Render
1. Create a new Web Service on [Render](https://render.com)
2. Connect your GitHub repository
3. Use these settings:
- Build Command: `npm install`
- Start Command: `npm start`
4. Add `GEMINI_API_KEY` in Environment Variables
5. Deploy!
### Option 3: Railway
1. Create a new project on [Railway](https://railway.app)
2. Connect your GitHub repository
3. Add `GEMINI_API_KEY` environment variable
4. Deploy!
### Option 4: Fly.io
1. Install Fly CLI:
```bash
curl -L https://fly.io/install.sh | sh
```
2. Initialize:
```bash
fly launch
```
3. Set secrets:
```bash
fly secrets set GEMINI_API_KEY=your_key_here
```
4. Deploy:
```bash
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:
1. **harmony_chat** - Chat with the Harmony 2.0 Master Agent
2. **harmony_analyze_code** - Analyze code for Harmony 2.0 compliance
3. **harmony_generate_code** - Generate code following Harmony 2.0 patterns
4. **harmony_get_guidance** - Get comprehensive guidance on Harmony 2.0 topics
## 📚 Harmony 2.0 Resources
- [Official Documentation](https://amdocs-studio.github.io/harmony-2.0/develop-with-harmony)
- [GitHub Repository](https://github.com/Amdocs-Studio/harmony-2.0)
## 🔐 Security Notes
- Never commit your `.env` file
- 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:
1. Check the [Harmony 2.0 documentation](https://amdocs-studio.github.io/harmony-2.0/develop-with-harmony)
2. Open an issue on GitHub
3. Contact the Harmony 2.0 community
---
**Built with ❤️ for the Harmony 2.0 community**
