Worksona MCP Server

# 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