worksona-mcp-server/README.md

MCP server for Worksona agent integration with Claude Desktop

# 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

- **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
- **Research Workflows**: Specialized research teams with standard and deep modes
- **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
- Access to the `worksona-teams` repository
- **Anthropic API Key** (for AI-powered agent responses)

### Installation

1. **Set up your Anthropic API Key**:
   ```bash
   export ANTHROPIC_API_KEY=your_api_key_here
   ```
   Get your API key from: https://console.anthropic.com/

2. **Build the server**:
   ```bash
   chmod +x build.sh
   ./build.sh
   ```

3. **Configure Claude Desktop**:
   Add to `~/.claude-desktop/config.json` (macOS) or `%APPDATA%/Claude/config.json` (Windows):
   ```json
   {
     "mcpServers": {
       "worksona-agents": {
         "command": "node",
         "args": ["/path/to/worksona-mcp-server/dist/index.js"],
         "cwd": "/path/to/worksona-mcp-server",
         "env": {
           "ANTHROPIC_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   ```

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

## 🎮 Usage Examples

### Single Agent Activation
```
I need to create API documentation for my REST service
```
Claude will use the `activate_agent` tool with `doc-writer` to create comprehensive API documentation.

### Multi-Agent Team Coordination
```
Build a complete user authentication system with security review
```
Claude will use the `coordinate_team` tool to coordinate `backend-architect`, `security-auditor`, and `frontend-developer` in sequence.

### Agent Suggestions
```
I need help optimizing database performance
```
Claude will use the `suggest_agents` tool to recommend specialists like `database-optimizer`, `performance-engineer`, and `sql-pro`.

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

## 🔧 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 |
| `research_workflow` | Execute specialized research workflows | Market research, competitive analysis |
| `list_agents` | Browse available agents by category | Discovering capabilities |
| `agent_info` | Get detailed agent information | Understanding agent 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 `worksona-teams` directory exists
- Check console for error messages

### Agents Not Loading
- Ensure `WORKSONA_TEAMS_PATH` environment variable is set
- 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_TEAMS_PATH`: Path to worksona-teams repository
- `NODE_ENV`: Environment (development/production)
- `LOG_LEVEL`: Logging level (debug/info/warn/error)

### Adding Custom Agents
1. Place agent files in `worksona-teams` 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