# Worksona MCP Server

A comprehensive MCP (Model Context Protocol) server that integrates all Worksona agents with Claude Desktop, providing automated agent discovery, multi-agent coordination, and enterprise-level AI capabilities.

## 🎯 Features

- **Actionable Resources**: Ready-to-use task templates, workflows, examples, and quick actions
- **Automatic Agent Discovery**: Loads 100+ Worksona agents from the repository automatically
- **Multi-Agent Coordination**: Four coordination patterns (sequential, parallel, review, executive)
- **Intelligent Agent Suggestions**: AI-powered agent matching for requests
- **Task Templates**: Pre-configured prompts for common development tasks
- **Workflow Orchestration**: Multi-agent workflows for complex projects
- **Example Prompts**: Real-world scenarios with detailed implementation guides
- **Quick Actions**: Fast solutions for immediate needs
- **Memory Management**: Persistent context and cross-agent memory
- **Enterprise Integration**: Full tool access and production-ready architecture

## 🚀 Quick Start

### Prerequisites
- Node.js 18+
- Claude Desktop with MCP support

### Installation

1. **Install the MCP server globally**:
   ```bash
   npm install -g worksona-mcp-server
   ```

2. **Configure Claude Desktop**:
   Add to `~/.claude-desktop/config.json` (macOS) or `%APPDATA%/Claude/config.json` (Windows):
   ```json
   {
     "mcpServers": {
       "worksona-agents": {
         "command": "/usr/local/bin/worksona-mcp-server"
       }
     }
   }
   ```

   > **Note**: No API key needed! The MCP server automatically detects it's running inside Claude Desktop and uses Claude's built-in AI processing.

3. **Restart Claude Desktop** to load the MCP server

## 🎮 Usage Examples

### Attach Task Templates
Instead of writing prompts from scratch, **attach task template resources** for instant, professional prompts:

1. **Browse Resources** in Claude Desktop's attachment panel
2. **Attach "📚 API Documentation"** task template
3. **Customize the provided prompt** with your API details
4. **Submit** - Claude automatically activates the `doc-writer` agent

### Attach Workflow Resources
For complex projects, **attach workflow resources** that coordinate multiple agents:

1. **Attach "🚀 Full-Stack Application"** workflow
2. **Customize the workflow prompt** with your project requirements  
3. **Submit** - Claude automatically uses `coordinate_team` with 4 specialists

### Attach Example Prompts
Get detailed guidance for common scenarios:

1. **Attach "💡 Startup MVP Development"** example
2. **Follow the comprehensive prompt template**
3. **Get coordinated help** from product, technical, and marketing specialists

### Attach Quick Actions
For immediate needs:

1. **Attach "🐛 Quick Bug Fix"** action
2. **Fill in the bug details**
3. **Get rapid debugging** from the `error-detective` agent

### Traditional Tool Usage
You can still use tools directly:
```
I need to create API documentation for my REST service
```
Claude will use the `activate_agent` tool with `doc-writer` automatically.

### Research Workflows
```
Research the competitive landscape for AI coding assistants
```
Claude will use the `research_workflow` tool to deploy a team of research specialists.

## 📎 Attachable Resources

The MCP server provides **21 actionable resources** organized into 4 categories:

### 🎯 Task Templates (6 resources)
Ready-to-use prompts for common development tasks:
- **📚 API Documentation** - Comprehensive API docs with examples
- **🔍 Code Review** - Security, performance, and best practices analysis  
- **⚡ Database Optimization** - Query and schema optimization
- **🔒 Security Audit** - Vulnerability assessment and compliance
- **🎨 Frontend Component** - Modern React/Vue components with TypeScript
- **🔧 Backend API** - Scalable REST/GraphQL API design

### 🔄 Workflows (5 resources)
Multi-agent coordination for complex projects:
- **🚀 Full-Stack Application** - Complete app development pipeline
- **🛡️ Security Review Workflow** - Multi-stage security assessment
- **⚡ Performance Optimization** - Systematic performance improvement
- **📊 Market Research** - Comprehensive market analysis
- **🔄 DevOps Pipeline** - End-to-end CI/CD setup

### 💡 Example Prompts (5 resources)
Real-world scenarios with detailed guidance:
- **💡 Startup MVP Development** - From idea to launch
- **🔄 Legacy System Modernization** - Migration strategies
- **🤖 AI Feature Integration** - Adding AI to existing apps
- **📱 Mobile App Development** - Cross-platform mobile apps
- **📈 Data Pipeline & Analytics** - Data processing systems

### ⚡ Quick Actions (5 resources)
Fast solutions for immediate needs:
- **🐛 Quick Bug Fix** - Rapid debugging (15-30 min)
- **⚡ Performance Check** - Fast performance analysis (20-45 min)
- **🔍 Security Scan** - Quick vulnerability assessment (25-40 min)
- **📖 Code Explanation** - Understand existing code (15-25 min)
- **🤔 Technology Decision** - Expert tech advice (20-35 min)

## 🔧 Available MCP Tools

| Tool | Description | Use Case |
|------|-------------|-----------|
| `activate_agent` | Activate a single agent with expertise | Specific tasks requiring domain expertise |
| `coordinate_team` | Coordinate multiple agents | Complex multi-faceted projects |
| `suggest_agents` | Get AI-powered agent recommendations | When unsure which agent to use |
| `list_agents` | Browse available agents by category | Discovering capabilities |

## 📁 Architecture

```
src/
├── agents/           # Agent system core
│   ├── types.ts     # Type definitions
│   ├── registry.ts  # Agent discovery and management
│   └── executor.ts  # Agent execution engine
├── orchestration/   # Multi-agent coordination
│   ├── coordinator.ts  # Workflow orchestration
│   └── memory.ts      # Cross-agent memory
├── utils/           # Utilities
│   ├── context.ts   # Project context management
│   └── logger.ts    # Structured logging
└── index.ts         # Main MCP server
```

## 🔍 Troubleshooting

### Server Won't Start
- Check Node.js version (18+ required)
- Verify `agents` directory exists
- Check console for error messages

### Agents Not Loading
- Ensure `WORKSONA_AGENTS_PATH` environment variable is set (if using custom path)
- Verify agent metadata.json files are valid
- Check file permissions

### Claude Desktop Not Connecting
- Verify MCP server configuration in Claude Desktop
- Restart Claude Desktop after configuration changes
- Check Claude Desktop logs for connection errors

## 🛠️ Development

### Building from Source
```bash
npm install
npm run build
npm start
```

### Environment Variables
- `WORKSONA_AGENTS_PATH`: Path to agents directory (optional, defaults to bundled agents)
- `NODE_ENV`: Environment (development/production)
- `LOG_LEVEL`: Logging level (debug/info/warn/error)

### Adding Custom Agents
1. Place agent files in `agents` directory structure
2. Follow the standard agent format (metadata.json + agent.md)
3. Restart the MCP server to reload agents

## 📊 Performance

- **Agent Discovery**: ~2-3 seconds for 100+ agents
- **Single Agent Execution**: ~500-2000ms average
- **Multi-Agent Coordination**: ~2-10 seconds depending on complexity
- **Memory Usage**: ~50-100MB typical operation

## 🔒 Security

- Agent prompts are executed in isolated contexts
- No direct file system access outside designated paths
- Memory is automatically cleaned to prevent data leaks
- All inputs are validated before processing

## 📝 License

MIT License - see LICENSE file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `npm test`
5. Submit a pull request

## 📞 Support

- Check the troubleshooting section above
- Review Claude Desktop MCP documentation
- Open an issue for bugs or feature requests