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

Install the MCP server globally:
```
npm install -g worksona-mcp-server
```
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.
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:

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

Attach Workflow Resources

For complex projects, attach workflow resources that coordinate multiple agents:

Attach "🚀 Full-Stack Application" workflow
Customize the workflow prompt with your project requirements
Submit - Claude automatically uses coordinate_team with 4 specialists

Attach Example Prompts

Get detailed guidance for common scenarios:

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

Attach Quick Actions

For immediate needs:

Attach "🐛 Quick Bug Fix" action
Fill in the bug details
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

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

Place agent files in agents directory structure
Follow the standard agent format (metadata.json + agent.md)
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

Fork the repository
Create a feature branch
Make your changes
Run tests: npm test
Submit a pull request

📞 Support

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