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