worksona/-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:

   npm install -g worksona-mcp-server
   

2. Configure Claude Desktop: Add to ~/.claude-desktop/config.json (macOS) or %APPDATA%/Claude/config.json (Windows):

   {
     "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

📁 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

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