documentation.html•28.3 kB
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Documentation - Worksona Agents</title>
<meta name="description" content="Complete documentation for Worksona Agents MCP server - installation, configuration, usage, and API reference.">
<link rel="stylesheet" href="css/styles.css">
<style>
.doc-content {
max-width: 900px;
margin: 0 auto;
}
.doc-nav {
position: sticky;
top: 80px;
background: white;
padding: 1rem 0;
border-bottom: 1px solid var(--border-color);
margin-bottom: 2rem;
}
.doc-nav ul {
display: flex;
list-style: none;
gap: 2rem;
flex-wrap: wrap;
justify-content: center;
}
.doc-nav a {
color: var(--text-light);
text-decoration: none;
font-weight: 600;
transition: color 0.2s;
}
.doc-nav a:hover {
color: var(--primary-color);
}
.doc-section {
margin-bottom: 4rem;
}
.doc-section h2 {
font-size: 2rem;
font-weight: 800;
margin-bottom: 1.5rem;
color: var(--text-dark);
border-bottom: 2px solid var(--border-color);
padding-bottom: 0.5rem;
}
.doc-section h3 {
font-size: 1.5rem;
font-weight: 700;
margin: 2rem 0 1rem;
color: var(--text-dark);
}
.doc-section h4 {
font-size: 1.25rem;
font-weight: 600;
margin: 1.5rem 0 0.75rem;
color: var(--text-dark);
}
.doc-section p {
color: var(--text-light);
line-height: 1.8;
margin-bottom: 1rem;
}
.doc-section ul, .doc-section ol {
color: var(--text-light);
line-height: 1.8;
margin: 1rem 0 1rem 1.5rem;
}
.doc-section li {
margin-bottom: 0.5rem;
}
.doc-section code {
background: var(--bg-gray);
padding: 0.25rem 0.5rem;
border-radius: var(--radius-sm);
font-family: 'Courier New', monospace;
font-size: 0.875rem;
color: var(--primary-color);
}
.doc-section pre {
background: var(--bg-dark);
color: #10b981;
padding: 1.5rem;
border-radius: var(--radius-md);
overflow-x: auto;
margin: 1rem 0;
}
.doc-section pre code {
background: none;
padding: 0;
color: inherit;
}
.info-box {
background: rgba(99, 102, 241, 0.1);
border-left: 4px solid var(--primary-color);
padding: 1rem 1.5rem;
border-radius: var(--radius-md);
margin: 1.5rem 0;
}
.warning-box {
background: rgba(245, 158, 11, 0.1);
border-left: 4px solid var(--warning-color);
padding: 1rem 1.5rem;
border-radius: var(--radius-md);
margin: 1.5rem 0;
}
.success-box {
background: rgba(16, 185, 129, 0.1);
border-left: 4px solid var(--success-color);
padding: 1rem 1.5rem;
border-radius: var(--radius-md);
margin: 1.5rem 0;
}
.feature-list {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 1rem;
margin: 1.5rem 0;
}
.feature-item {
background: var(--bg-gray);
padding: 1rem;
border-radius: var(--radius-md);
}
.feature-item strong {
color: var(--text-dark);
}
.code-block-wrapper {
position: relative;
margin: 1rem 0;
}
.copy-btn {
position: absolute;
top: 0.75rem;
right: 0.75rem;
background: var(--text-dark);
color: white;
border: 2px solid var(--text-dark);
padding: 0.5rem 0.875rem;
font-size: 0.75rem;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.05em;
cursor: pointer;
display: flex;
align-items: center;
gap: 0.5rem;
transition: all 0.15s;
}
.copy-btn:hover {
background: var(--primary-color);
border-color: var(--primary-color);
}
.copy-btn.copied {
background: var(--success-color);
border-color: var(--success-color);
}
.copy-btn svg {
width: 14px;
height: 14px;
}
</style>
</head>
<body>
<!-- Navigation -->
<nav class="nav">
<div class="nav-container">
<div class="nav-brand">
<svg class="logo" width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<rect x="2" y="7" width="20" height="14" rx="2" ry="2"/>
<path d="M16 21V5a2 2 0 0 0-2-2h-4a2 2 0 0 0-2 2v16"/>
</svg>
<span class="brand-name">Worksona Agents</span>
</div>
<ul class="nav-links">
<li><a href="index.html">Home</a></li>
<li><a href="agents.html">Agent Directory</a></li>
<li><a href="documentation.html" class="active">Documentation</a></li>
<li><a href="examples.html">Examples</a></li>
<li><a href="https://github.com/worksona/worksona-mcp-server" target="_blank" class="btn-github">
<svg width="20" height="20" fill="currentColor" viewBox="0 0 16 16">
<path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.012 8.012 0 0 0 16 8c0-4.42-3.58-8-8-8z"/>
</svg>
GitHub
</a></li>
</ul>
<button class="mobile-menu-btn" aria-label="Toggle menu">
<span></span>
<span></span>
<span></span>
</button>
</div>
</nav>
<!-- Page Header -->
<section class="page-header">
<div class="container">
<h1>Documentation</h1>
<p>Everything you need to know about Worksona Agents MCP Server</p>
</div>
</section>
<!-- Documentation Navigation -->
<div class="doc-nav">
<div class="container">
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#quick-start">Quick Start</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#tools">MCP Tools</a></li>
<li><a href="#configuration">Configuration</a></li>
<li><a href="#troubleshooting">Troubleshooting</a></li>
</ul>
</div>
</div>
<!-- Documentation Content -->
<section style="padding: 3rem 0 5rem;">
<div class="container">
<div class="doc-content">
<!-- Overview -->
<div id="overview" class="doc-section">
<h2>Overview</h2>
<p>Worksona Agents is a comprehensive MCP (Model Context Protocol) server that transforms Claude Desktop into a powerful multi-agent platform. With 100+ specialized AI agents across 20+ categories, you can tackle any development, research, security, or business challenge.</p>
<h3>Key Features</h3>
<div class="feature-list">
<div class="feature-item">
<strong>🎯 Multi-Agent Coordination</strong>
<p style="margin: 0; color: var(--text-light); font-size: 0.875rem;">Four coordination modes for complex tasks</p>
</div>
<div class="feature-item">
<strong>🚀 Automatic Discovery</strong>
<p style="margin: 0; color: var(--text-light); font-size: 0.875rem;">Agents load automatically, no manual setup</p>
</div>
<div class="feature-item">
<strong>🧠 Intelligent Matching</strong>
<p style="margin: 0; color: var(--text-light); font-size: 0.875rem;">AI-powered agent suggestions</p>
</div>
<div class="feature-item">
<strong>💼 Enterprise-Grade</strong>
<p style="margin: 0; color: var(--text-light); font-size: 0.875rem;">Production-ready architecture</p>
</div>
</div>
</div>
<!-- Quick Start -->
<div id="quick-start" class="doc-section">
<h2>Quick Start</h2>
<h3>Prerequisites</h3>
<h4>1. Node.js 18 or Higher</h4>
<p>Download and install Node.js from <a href="https://nodejs.org/" target="_blank" style="color: var(--primary-color); text-decoration: underline;">nodejs.org</a></p>
<p>Verify your installation:</p>
<div class="code-block-wrapper">
<pre><code>node --version</code></pre>
<button class="copy-btn" data-code="node --version">
<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>
<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>
</svg>
Copy
</button>
</div>
<p>Expected output: <code>v18.0.0</code> or higher</p>
<h4>2. Claude Desktop with MCP Support</h4>
<p>Download Claude Desktop from <a href="https://claude.ai/download" target="_blank" style="color: var(--primary-color); text-decoration: underline;">claude.ai/download</a></p>
<p>Ensure you have version 0.7.0 or later (MCP support was added in v0.7.0)</p>
<div class="info-box">
<strong>System Requirements:</strong>
<ul style="margin: 0.5rem 0 0 1.5rem;">
<li><strong>macOS:</strong> 10.15 (Catalina) or later</li>
<li><strong>Windows:</strong> Windows 10 or later</li>
<li><strong>Linux:</strong> Ubuntu 20.04+ or equivalent</li>
</ul>
</div>
<h3>Installation</h3>
<h4>Step 1: Install the MCP Server</h4>
<p>Install the server globally using npm:</p>
<div class="code-block-wrapper">
<pre><code>npm install -g worksona-mcp-server</code></pre>
<button class="copy-btn" data-code="npm install -g worksona-mcp-server">
<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>
<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>
</svg>
Copy
</button>
</div>
<h4>Step 2: Configure Claude Desktop</h4>
<p>Add the following configuration to your Claude Desktop config file:</p>
<ul>
<li><strong>macOS:</strong> <code>~/.claude-desktop/config.json</code></li>
<li><strong>Windows:</strong> <code>%APPDATA%/Claude/config.json</code></li>
<li><strong>Linux:</strong> <code>~/.config/Claude/config.json</code></li>
</ul>
<div class="code-block-wrapper">
<pre><code>{
"mcpServers": {
"worksona-agents": {
"command": "/usr/local/bin/worksona-mcp-server"
}
}
}</code></pre>
<button class="copy-btn" data-code='{
"mcpServers": {
"worksona-agents": {
"command": "/usr/local/bin/worksona-mcp-server"
}
}
}'>
<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>
<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>
</svg>
Copy
</button>
</div>
<div class="warning-box">
<strong>⚠️ Windows Users:</strong>
<p style="margin: 0.5rem 0 0;">On Windows, the command path might be different. Find your npm global path with:</p>
<div class="code-block-wrapper" style="margin-top: 0.5rem;">
<pre style="margin: 0;"><code>npm config get prefix</code></pre>
<button class="copy-btn" data-code="npm config get prefix">
<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>
<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>
</svg>
Copy
</button>
</div>
</div>
<div class="info-box">
<strong>💡 No API Key Needed!</strong>
<p style="margin: 0.5rem 0 0; color: var(--text-light);">The MCP server automatically detects it's running inside Claude Desktop and uses Claude's built-in AI processing.</p>
</div>
<h4>Step 3: Restart Claude Desktop</h4>
<p>Close and reopen Claude Desktop to load the MCP server.</p>
<div class="success-box">
<strong>✓ Success!</strong>
<p style="margin: 0.5rem 0 0; color: var(--text-light);">You're ready to use Worksona Agents. Try: "I need help creating API documentation for my REST service"</p>
</div>
</div>
<!-- Usage -->
<div id="usage" class="doc-section">
<h2>Usage</h2>
<h3>Basic Agent Activation</h3>
<p>The simplest way to use agents is to just ask Claude for help naturally:</p>
<pre><code>I need help creating API documentation for my REST service</code></pre>
<p>Claude will automatically activate the appropriate agent (<code>doc-writer</code> in this case) and provide expert assistance.</p>
<h3>Multi-Agent Coordination</h3>
<p>For complex tasks, request multiple agents to work together:</p>
<pre><code>Build a complete user authentication system with security review</code></pre>
<p>Claude will coordinate <code>backend-architect</code>, <code>security-auditor</code>, and other relevant agents.</p>
<h3>Browse Available Agents</h3>
<p>Ask Claude to show you available agents for a specific domain:</p>
<pre><code>What agents do you have available for database optimization?</code></pre>
<h3>Direct Tool Usage</h3>
<p>You can also explicitly request specific tools:</p>
<pre><code>// Activate a specific agent
Use the activate_agent tool with agent "frontend-developer"
// Coordinate multiple agents
Use coordinate_team with agents ["backend-architect", "frontend-developer", "test-automator"]
// Get agent suggestions
Use suggest_agents to find the best agents for "API security"</code></pre>
</div>
<!-- MCP Tools -->
<div id="tools" class="doc-section">
<h2>MCP Tools</h2>
<p>The Worksona Agents MCP server provides these tools to Claude Desktop:</p>
<h3>1. activate_agent</h3>
<p><strong>Purpose:</strong> Activate a single specialized agent for focused expertise</p>
<p><strong>Parameters:</strong></p>
<ul>
<li><code>agent_name</code> (string, required) - Name of the agent to activate</li>
<li><code>request</code> (string, required) - Your specific task or question</li>
<li><code>project_context</code> (object, optional) - Additional context about your project</li>
</ul>
<p><strong>Example:</strong></p>
<pre><code>activate_agent({
"agent_name": "doc-writer",
"request": "Create comprehensive API documentation",
"project_context": { "framework": "Express.js", "auth": "JWT" }
})</code></pre>
<h3>2. coordinate_team</h3>
<p><strong>Purpose:</strong> Coordinate multiple agents for complex, multi-faceted tasks</p>
<p><strong>Parameters:</strong></p>
<ul>
<li><code>agents</code> (array, required) - List of agent names to coordinate</li>
<li><code>task</code> (string, required) - Description of the overall task</li>
<li><code>coordination_type</code> (string, required) - One of: "sequential", "parallel", "review", "executive"</li>
</ul>
<p><strong>Coordination Types:</strong></p>
<ul>
<li><strong>sequential</strong> - Agents work in order, each building on previous work</li>
<li><strong>parallel</strong> - Agents work simultaneously on different aspects</li>
<li><strong>review</strong> - Primary agent works, others review and provide feedback</li>
<li><strong>executive</strong> - C-suite agents provide strategic oversight</li>
</ul>
<h3>3. suggest_agents</h3>
<p><strong>Purpose:</strong> Get AI-powered suggestions for which agents to use</p>
<p><strong>Parameters:</strong></p>
<ul>
<li><code>request</code> (string, required) - Your task or question</li>
<li><code>max_suggestions</code> (number, optional) - Maximum suggestions to return (default: 5)</li>
</ul>
<h3>4. list_agents</h3>
<p><strong>Purpose:</strong> Browse all available agents</p>
<p><strong>Parameters:</strong></p>
<ul>
<li><code>category</code> (string, optional) - Filter by category</li>
<li><code>capability</code> (string, optional) - Filter by capability</li>
</ul>
</div>
<!-- Configuration -->
<div id="configuration" class="doc-section">
<h2>Configuration</h2>
<h3>Environment Variables</h3>
<ul>
<li><code>WORKSONA_AGENTS_PATH</code> - Path to agents directory (optional, defaults to bundled agents)</li>
<li><code>NODE_ENV</code> - Environment: development/production</li>
<li><code>LOG_LEVEL</code> - Logging level: debug/info/warn/error</li>
</ul>
<h3>Custom Agents</h3>
<p>You can add custom agents by:</p>
<ol>
<li>Creating an agent directory with the standard structure</li>
<li>Adding <code>metadata.json</code> and <code>agent.md</code> files</li>
<li>Setting <code>WORKSONA_AGENTS_PATH</code> to your agents directory</li>
<li>Restarting Claude Desktop</li>
</ol>
<h3>Agent Structure</h3>
<pre><code>agents/
category-name/
agent-name/
metadata.json # Agent configuration
agent.md # Agent prompt and instructions</code></pre>
</div>
<!-- Troubleshooting -->
<div id="troubleshooting" class="doc-section">
<h2>Troubleshooting</h2>
<h3>Server Won't Start</h3>
<ul>
<li>Check Node.js version (must be 18+): <code>node --version</code></li>
<li>Verify the agents directory exists</li>
<li>Check console for error messages</li>
<li>Try reinstalling: <code>npm install -g worksona-mcp-server --force</code></li>
</ul>
<h3>Agents Not Loading</h3>
<ul>
<li>Ensure <code>WORKSONA_AGENTS_PATH</code> is set correctly (if using custom path)</li>
<li>Verify agent <code>metadata.json</code> files are valid JSON</li>
<li>Check file permissions</li>
<li>Look for errors in the console when starting</li>
</ul>
<h3>Claude Desktop Not Connecting</h3>
<ul>
<li>Verify config.json syntax is valid (use a JSON validator)</li>
<li>Check the command path is correct for your system</li>
<li>Restart Claude Desktop after configuration changes</li>
<li>Check Claude Desktop logs for connection errors</li>
</ul>
<h3>Tools Not Appearing</h3>
<ul>
<li>Restart Claude Desktop completely (quit and reopen)</li>
<li>Verify the MCP server is running</li>
<li>Check if other MCP servers are working</li>
<li>Try removing and re-adding the configuration</li>
</ul>
<div class="warning-box">
<strong>⚠️ Still Having Issues?</strong>
<p style="margin: 0.5rem 0 0; color: var(--text-light);">Check the <a href="https://github.com/worksona/worksona-mcp-server/issues" target="_blank" style="color: var(--warning-color);">GitHub Issues</a> or create a new issue with details about your problem.</p>
</div>
</div>
<!-- Next Steps -->
<div class="doc-section" style="background: var(--bg-gray); padding: 2rem; border-radius: var(--radius-lg); text-align: center;">
<h3 style="margin-top: 0;">Ready to Explore More?</h3>
<p>Browse our agent directory or check out example use cases</p>
<div style="display: flex; gap: 1rem; justify-content: center; margin-top: 1.5rem;">
<a href="agents.html" class="btn btn-primary">Browse Agents</a>
<a href="examples.html" class="btn btn-secondary">See Examples</a>
</div>
</div>
</div>
</div>
</section>
<!-- Footer -->
<footer class="footer">
<div class="container">
<div class="footer-content">
<div class="footer-section">
<h4>Worksona Agents</h4>
<p>Multi-agent platform for Claude Desktop</p>
</div>
<div class="footer-section">
<h4>Resources</h4>
<ul>
<li><a href="documentation.html">Documentation</a></li>
<li><a href="agents.html">Agent Directory</a></li>
<li><a href="examples.html">Examples</a></li>
</ul>
</div>
<div class="footer-section">
<h4>Community</h4>
<ul>
<li><a href="https://github.com/worksona/worksona-mcp-server" target="_blank">GitHub</a></li>
<li><a href="https://worksona.io" target="_blank">Worksona.io</a></li>
<li><a href="https://atomic47.co" target="_blank">Atomic 47 Labs</a></li>
</ul>
</div>
</div>
<div class="footer-bottom">
<p>All Rights Reserved: Atomic 47 Labs Inc [<a href="https://atomic47.co" target="_blank" style="color: inherit;">atomic47.co</a>]. 2025. A <a href="https://worksona.io" target="_blank" style="color: inherit;">worksona.io</a> project. Contact: <a href="mailto:david@atomic47.co" style="color: inherit;">david@atomic47.co</a></p>
</div>
</div>
</footer>
<script src="js/main.js"></script>
<script>
// Copy button functionality
document.addEventListener('DOMContentLoaded', () => {
const copyButtons = document.querySelectorAll('.copy-btn');
copyButtons.forEach(button => {
button.addEventListener('click', async () => {
const code = button.getAttribute('data-code');
try {
await navigator.clipboard.writeText(code);
// Show success state
button.classList.add('copied');
const originalText = button.innerHTML;
button.innerHTML = `
<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<polyline points="20 6 9 17 4 12"/>
</svg>
Copied!
`;
// Reset after 2 seconds
setTimeout(() => {
button.classList.remove('copied');
button.innerHTML = originalText;
}, 2000);
} catch (err) {
console.error('Failed to copy:', err);
button.textContent = 'Failed!';
setTimeout(() => {
button.innerHTML = originalText;
}, 2000);
}
});
});
});
</script>
</body>
</html>