@robinson_ai_systems/free-agent-mcp/README.md

Free Agent MCP - Portable, workspace-agnostic code generation using FREE models (Ollama)

# 🤖 Autonomous AI Agent MCP Server

**Offload heavy AI work from Augment Code to FREE local LLMs!**

Save 90%+ on Augment Code credits by delegating code generation, analysis, and refactoring to local LLMs running on your machine.

---

## 🎯 What It Does

The Autonomous AI Agent is an MCP server that runs local LLMs (via Ollama) to handle heavy AI tasks **without using Augment Code credits**.

### **Before (Without Autonomous Agent):**
```
You: "Generate a notifications feature"
Augment: *generates code using 13,000 credits*
Cost: $2.00 in add-on packs
```

### **After (With Autonomous Agent):**
```
You: "Generate a notifications feature"
Augment: *calls delegate_code_generation*
Autonomous Agent: *generates code using local LLM*
Augment: *saves result using 500 credits*
Cost: $0.00 (runs locally!)
Savings: 96% credits + $2.00 cash
```

---

## 💰 Credit Savings

| Task | Augment Credits | With Agent | Savings |
|------|----------------|------------|---------|
| Code Generation | 13,000 | 500 | **96%** |
| Code Analysis | 5,000 | 300 | **94%** |
| Refactoring | 7,000 | 400 | **94%** |
| Test Generation | 8,000 | 400 | **95%** |
| Documentation | 3,000 | 200 | **93%** |

**Average savings: 90%+ per task!**

---

## 🚀 Quick Start

### **1. Install Ollama**

```bash
# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# Download from https://ollama.com/download
```

### **2. Pull Models**

```bash
# Best for complex code (slower, highest quality)
ollama pull deepseek-coder:33b

# Fastest (good for simple tasks)
ollama pull qwen2.5-coder:32b

# Balanced (good for most tasks)
ollama pull codellama:34b
```

### **3. Install MCP Server**

```bash
cd packages/autonomous-agent-mcp
npm install
npm run build
```

### **4. Configure Augment Code**

Add to your Augment Code MCP settings:

```json
{
  "mcpServers": {
    "autonomous-agent": {
      "command": "node",
      "args": ["c:/Users/chris/Git Local/robinsonai-mcp-servers/packages/autonomous-agent-mcp/dist/index.js"]
    }
  }
}
```

### **5. Start Using!**

In Augment Code:
```
You: "Use the autonomous agent to generate a user profile component"

Augment: *calls delegate_code_generation*
Agent: *generates code using local LLM*
Augment: "Done! Here's your component. Used 500 credits instead of 13,000!"
```

---

## 🛠️ Available Tools

### **1. delegate_code_generation**
Generate code using local LLM (0 Augment credits!)

```typescript
delegate_code_generation({
  task: "notifications feature",
  context: "Next.js, TypeScript, Supabase",
  complexity: "medium"
})
```

### **2. delegate_code_analysis**
Analyze code for issues (0 Augment credits!)

```typescript
delegate_code_analysis({
  code: "...",
  question: "find performance issues"
})
```

### **3. delegate_code_refactoring**
Refactor code (0 Augment credits!)

```typescript
delegate_code_refactoring({
  code: "...",
  instructions: "extract into components"
})
```

### **4. delegate_test_generation**
Generate tests (0 Augment credits!)

```typescript
delegate_test_generation({
  code: "...",
  framework: "jest",
  coverage: "comprehensive"
})
```

### **5. delegate_documentation**
Generate documentation (0 Augment credits!)

```typescript
delegate_documentation({
  code: "...",
  style: "tsdoc",
  detail: "detailed"
})
```

### **6. get_agent_stats**
See how many credits you've saved!

```typescript
get_agent_stats({
  period: "month"
})
```

---

## 🧠 Model Selection

The agent automatically selects the best model for each task:

| Complexity | Model | Speed | Quality | Use Case |
|------------|-------|-------|---------|----------|
| Simple | Qwen 2.5 Coder 32B | ⚡ Fast (10-20s) | ✅ Good | CRUD, boilerplate |
| Medium | CodeLlama 34B | ⚡ Medium (20-40s) | ✅✅ Better | General tasks, tests |
| Complex | DeepSeek Coder 33B | ⚡ Slow (30-60s) | ✅✅✅ Best | Algorithms, architecture |

You can also specify a model explicitly:
```typescript
delegate_code_generation({
  task: "...",
  model: "deepseek-coder" // or "qwen-coder" or "codellama"
})
```

---

## 📊 Real-World Example

**Scenario:** Building a notifications feature for Cortiware

**Without Autonomous Agent:**
- Augment generates code: 13,000 credits
- Augment generates tests: 8,000 credits
- Augment generates docs: 3,000 credits
- **Total: 24,000 credits**
- **Cost: $3.60 in add-on packs**

**With Autonomous Agent:**
- Augment plans: 500 credits
- Agent generates code: 0 credits (local!)
- Agent generates tests: 0 credits (local!)
- Agent generates docs: 0 credits (local!)
- Augment saves results: 500 credits
- **Total: 1,000 credits**
- **Cost: $0.00**
- **Savings: 96% credits + $3.60 cash**

---

## 🎯 Tips for Best Results

### **1. Be Specific**
```typescript
// ❌ Vague
delegate_code_generation({
  task: "make a form",
  context: "React"
})

// ✅ Specific
delegate_code_generation({
  task: "user registration form with email, password, and name fields",
  context: "Next.js 14, TypeScript, React Hook Form, Zod validation, Tailwind CSS"
})
```

### **2. Use the Right Complexity**
```typescript
// Simple CRUD → use "simple" (fastest)
delegate_code_generation({
  task: "basic user list component",
  complexity: "simple"
})

// Complex algorithm → use "complex" (best quality)
delegate_code_generation({
  task: "implement A* pathfinding algorithm",
  complexity: "complex"
})
```

### **3. Iterate**
```typescript
// First pass
const result1 = await delegate_code_generation({
  task: "notifications feature",
  context: "Next.js, TypeScript"
})

// Refine
const result2 = await delegate_code_refactoring({
  code: result1.code,
  instructions: "extract into smaller components"
})

// Add tests
const result3 = await delegate_test_generation({
  code: result2.refactoredCode,
  framework: "jest"
})
```

---

## 🔧 Troubleshooting

### **"Model not found" error**
```bash
# Pull the missing model
ollama pull deepseek-coder:33b
ollama pull qwen2.5-coder:32b
ollama pull codellama:34b
```

### **"Ollama not running" error**
```bash
# Start Ollama
ollama serve
```

### **Slow generation**
- Use `complexity: "simple"` for faster results
- Use `model: "qwen-coder"` for fastest model
- Reduce `maxTokens` if generating too much code

### **Low quality results**
- Use `complexity: "complex"` for better quality
- Use `model: "deepseek-coder"` for best model
- Provide more context in the request
- Be more specific in your task description

---

## 📈 Stats & Monitoring

Check your savings anytime:

```typescript
const stats = await get_agent_stats({ period: "month" })

console.log(`Total requests: ${stats.totalRequests}`)
console.log(`Credits saved: ${stats.augmentCreditsSaved}`)
console.log(`Average time: ${stats.averageTimeMs}ms`)
```

---

## 🚀 What's Next?

Once Ollama finishes installing, you can:

1. **Test the agent** - Generate some code and see the savings!
2. **Build Cortiware faster** - Use the agent for all heavy AI work
3. **Track your savings** - Watch the credits saved add up
4. **Share your results** - Help others save money too!

---

## 💡 Pro Tips

- **Use for ALL code generation** - Let the agent do the heavy lifting
- **Combine with Credit Optimizer** - Use templates + agent for maximum savings
- **Run overnight** - Let the agent generate code while you sleep
- **Batch tasks** - Generate multiple features at once

---

**Ready to save 90%+ on Augment Code credits?** 🚀

**Cost: $0.00 (completely FREE!)**