# Task-Agents MCP Server
A Model Context Protocol (MCP) server that enables specialized AI agents by delegating tasks to Claude Code CLI with custom configurations. This creates a team of specialized AI assistants accessible through any MCP-compatible client.
## Features
- 🤖 **Multiple Specialized Agents**: Code reviewer, debugger, test runner, documentation writer, and more
- 🔧 **Easy Configuration**: Simple markdown files define agent behavior
- 🚀 **Flexible Integration**: Works with Claude Desktop, Claude Code CLI, or any MCP client
- 📝 **Custom System Prompts**: Each agent has tailored instructions for specific tasks
- 🛠️ **Tool Restrictions**: Control which tools each agent can access
- 🎯 **Simple API**: Single tool interface where LLM selects the appropriate agent
- 📁 **Smart Working Directory**: Agents default to saving files in their configured directory
## Architecture
```
MCP Client → Task-Agents MCP Server → Claude Code CLI → Response
```
The server reads agent configurations from markdown files and constructs Claude Code CLI commands:
```bash
claude -p "task description" --system-prompt "agent prompt" --model opus --allowedTools Read Write Edit --output-format text
```
## Installation
### Prerequisites
1. **Python 3.11+** installed
2. **Claude Code CLI** installed and working:
```bash
claude --version
```
### Installation Methods
#### Method 1: PyPI Package with uvx (Recommended)
```bash
# Install and run with uvx (no installation needed)
uvx task-agents-mcp
# Or install with pip
pip install task-agents-mcp
python -m task_agents_mcp
```
#### Method 2: Direct Python Execution (For Development)
1. **Clone the repository:**
```bash
git clone https://github.com/vredrick/task-agents.git
cd task-agents
```
2. **Install Python dependencies:**
```bash
pip install -r requirements.txt
```
3. **Run the server directly:**
```bash
python server.py
```
### Setup Steps
1. **Find your Claude executable path:**
```bash
which claude
# If using an alias, check the actual path
```
2. **Copy the task-agents folder to your project** (contains agent .md files):
```bash
cp -r /Volumes/vredrick2/Claude-Code-Projects/task-agents/task-agents ./
```
## Configuration for Claude Desktop
1. **Open your Claude Desktop configuration file:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
2. **Add the task-agents server to the `mcpServers` section:**
**Option A: Using uvx (Recommended for Python servers)**
```json
{
"mcpServers": {
"task-agents": {
"command": "uvx",
"args": ["task-agents-mcp"],
"env": {
"TASK_AGENTS_PATH": "/path/to/your/task-agents",
"CLAUDE_EXECUTABLE_PATH": "/Users/username/.claude/local/claude"
}
}
}
}
```
**Option B: Using Python directly**
```json
{
"mcpServers": {
"task-agents": {
"command": "python3.11",
"args": ["/Volumes/vredrick2/Claude-Code-Projects/task-agents/server.py"],
"env": {
"TASK_AGENTS_PATH": "/Volumes/vredrick2/Claude-Code-Projects/task-agents/task-agents",
"CLAUDE_EXECUTABLE_PATH": "/Users/vredrick/.claude/local/claude"
}
}
}
}
```
**Important environment variables:**
- `TASK_AGENTS_PATH`: Path to your task-agents directory (required for Claude Desktop to find agents)
- `CLAUDE_EXECUTABLE_PATH`: Full path to your Claude executable (required for Claude Desktop, not needed for Claude Code CLI)
3. **Restart Claude Desktop** (Quit completely and reopen)
## Configuration for Claude Code CLI
### Option 1: Using MCP Config File
1. **Using uvx (Recommended):**
```bash
claude mcp add task-agents -s project uvx task-agents-mcp
```
2. **Using Python directly:**
```bash
# From your project directory where you copied task-agents folder
# Note: Claude Code CLI doesn't need CLAUDE_EXECUTABLE_PATH - it finds Claude automatically
claude mcp add task-agents -s project python3.11 /Volumes/vredrick2/Claude-Code-Projects/task-agents/server.py
```
3. **Or use the provided `mcp_config.json`:**
```json
{
"mcpServers": {
"task-agents": {
"command": "python3.11",
"args": ["./server.py"],
"env": {}
}
}
}
```
Note: Claude Code CLI doesn't need `CLAUDE_EXECUTABLE_PATH` in the environment
2. **Start Claude with the MCP config:**
```bash
claude --mcp-config /path/to/task-agents/mcp_config.json
```
### Option 2: Using Environment Variables
1. **Set environment variables:**
```bash
export TASK_AGENTS_CONFIG_DIR="/path/to/task-agents/configs"
export CLAUDE_EXECUTABLE_PATH="/path/to/claude/executable"
```
2. **Run the server script:**
```bash
cd /path/to/task-agents
./run_server.sh
```
3. **In another terminal, connect with Claude:**
```bash
claude --mcp-config mcp_config.json
```
## Configuration
### Two Ways to Use Task-Agents
Task-agents supports two deployment modes depending on your workflow:
#### 1. Project-specific mode (Claude Code CLI)
Perfect for working on specific projects:
- Drop the `task-agents` folder into your project root directory
- Start Claude Code from that project directory
- Agents automatically work in your project context with `cwd: .`
**Example directory structure:**
```
my-awesome-project/ # ← Your project root
├── src/
├── tests/
├── package.json
└── task-agents/ # ← Drop task-agents folder here
├── code-reviewer.md
├── debugger.md
└── ...
```
**With `cwd: .` in agent configs**, agents will execute in `/path/to/my-awesome-project/` (the project root).
#### 2. Global mode (Claude Desktop or fixed location)
For system-wide usage across multiple projects:
- Keep `task-agents` folder in a fixed location (e.g., `~/task-agents`)
- Set `TASK_AGENTS_PATH` environment variable to point to it
- Configure individual agent working directories as needed
**Example setup:**
```bash
# task-agents folder at fixed location
~/task-agents/
├── code-reviewer.md
├── debugger.md
└── ...
# Environment variable
export TASK_AGENTS_PATH="/Users/username/task-agents"
```
### Working Directory Resolution
The `cwd` field in agent configurations is the **ONLY source** that controls where each agent executes:
#### `cwd: .` (Default - Recommended)
- **Always resolves to the parent directory of the task-agents folder**
- **Project-specific mode**: If task-agents is in `/project/task-agents/`, agents run in `/project/`
- **Global mode**: If TASK_AGENTS_PATH is `/home/user/task-agents`, agents run in `/home/user/`
- **Perfect for project-specific agents** that need to work within your codebase
- **Consistent across ALL clients** - Claude Desktop, Claude Code CLI, or any MCP client
#### Absolute paths
Use when you need agents to work in specific directories:
```yaml
cwd: /Users/username/my-specific-project
cwd: /opt/projects/production-app
```
#### Environment variables
For flexible, user-specific paths:
```yaml
cwd: ${HOME}/projects/current
cwd: ${WORKSPACE}/active-project
```
#### Default File Saving Behavior
- **Agents are automatically instructed to save files in their working directory**
- When creating files without an explicit path, agents will use relative paths (e.g., `./file.txt`)
- This instruction is appended to every agent's system prompt
- Users can still override by specifying absolute paths
### Agent Configuration Format
Agent configurations are stored as markdown files in the `task-agents` directory. Each file defines an agent with:
- **agent-name**: Display name for the agent (shown to LLM clients)
- **description**: Brief description of the agent's purpose
- **tools**: Comma-separated list of Claude Code tools the agent can use
- **model**: Claude model to use (opus/sonnet/haiku)
- **cwd**: Working directory where the agent executes (see examples above)
- **System-prompt**: Detailed instructions for the agent
### Example Agent Configurations
#### Project-specific agent (most common)
```markdown
---
agent-name: Code Reviewer
description: Expert code review specialist for quality, security, and maintainability analysis
tools: Read, Search, Glob, Bash, Grep
model: opus
cwd: . # ← Executes in project root
---
System-prompt:
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked, analyze the current project's codebase for issues and improvements.
```
#### Global agent for specific directory
```markdown
---
agent-name: Production Monitor
description: Monitor and analyze production systems
tools: Read, Bash, Search
model: sonnet
cwd: /opt/production/logs # ← Always works in this directory
---
System-prompt:
You monitor production systems and analyze logs for issues.
Focus on performance metrics and error patterns.
```
#### User-specific flexible agent
```markdown
---
agent-name: Personal Assistant
description: General-purpose assistant for personal projects
tools: Read, Write, Edit, Bash
model: sonnet
cwd: ${HOME}/current-project # ← Uses environment variable
---
System-prompt:
You are a helpful assistant for personal development projects.
Adapt to whatever project context you find yourself in.
```
## Available Agents
- **code-reviewer**: Comprehensive code analysis for quality and security
- **debugger**: Bug fixing and troubleshooting specialist
- **test-runner**: Test automation and coverage improvement
- **documentation-writer**: Technical documentation creation
- **performance-optimizer**: Performance analysis and optimization
## Usage
Once configured, the task-agents server provides a single tool:
### Available Tool
**`task_agents`** - Delegates tasks to specialized AI agents
- **Parameters**:
- `agent`: The name of the agent to use (e.g., "Code Reviewer", "Debugger")
- `prompt`: The task or question for the agent
### In Claude Desktop
After setup, you can use natural language:
- "Use the Code Reviewer agent to analyze my pull request"
- "Ask the Debugger agent to fix this error"
- "Have the Documentation Writer create API docs"
### In Claude Code CLI
```bash
# Start a session with task-agents
claude --mcp-config /path/to/task-agents/mcp_config.json
# Then use natural language as above
```
### How It Works
1. **Claude sees the request** and the `task_agents` tool with available agents
2. **Claude analyzes your request** and selects the appropriate agent
3. **Claude calls `task_agents`** with:
- `agent`: The selected agent name (e.g., "Code Reviewer", "Debugger")
- `prompt`: Your specific task or question
4. **The server executes** Claude Code CLI with the agent's configuration
5. **Results are returned** to your Claude session
## Creating Custom Agents
1. Create a new `.md` file in the `task-agents/` directory
2. Add YAML frontmatter with required fields
3. Write a detailed system prompt after the frontmatter
4. The agent will be automatically discovered on server restart
### Required Fields
- `agent-name`: Display name for the agent
- `description`: What the agent does
- `tools`: Available Claude Code tools
- `model`: Which Claude model to use
- `cwd`: Working directory path
## Environment Variables
- Agent configs support environment variable expansion in the `cwd` field
- Use `${HOME}`, `${USER}`, etc. in your configurations
## Error Handling
The server includes comprehensive error handling for:
- Missing or malformed agent configurations
- Claude CLI execution errors
- Invalid task descriptions
- Missing dependencies
## Logging
The server logs:
- Agent loading and discovery
- Task delegation decisions
- Claude CLI command execution
- Errors and warnings
Set logging level with standard Python logging configuration.
## Development
### Testing
Run the test script to verify all agents are working:
```bash
python test_server.py
```
### Adding New Features
1. Extend `AgentConfig` dataclass for new fields
2. Update `_parse_agent_config` method
3. Modify agent selection logic if needed
4. Update documentation
## Troubleshooting
### Common Issues
1. **"Claude CLI not found"**
- For Claude Desktop: Make sure `CLAUDE_EXECUTABLE_PATH` is set correctly in your config
- For Claude Code CLI: This error shouldn't occur as it finds Claude automatically
- Find your Claude path with: `which claude`
- If it's an alias, find the actual executable path
2. **"No agents are currently configured"**
- Verify a `task-agents` directory exists in your project root
- Check that `.md` files exist in the task-agents directory
- Ensure you're running Claude Code from the project directory
3. **"Error executing Claude CLI"**
- Check that the working directory (`cwd`) exists
- Verify Claude Code CLI works: `claude --version`
- Check agent configuration syntax in `.md` files
4. **Server not appearing in Claude Desktop**
- Completely quit Claude Desktop (Cmd+Q on Mac)
- Check JSON syntax in claude_desktop_config.json
- Verify all paths are absolute paths
- Restart Claude Desktop
### Testing Your Setup
1. **Test the server directly:**
```bash
cd /path/to/task-agents
python3.11 server.py
```
You should see: "Loaded X agents" with a list
2. **Test Claude CLI command:**
```bash
/path/to/claude --version
```
3. **Test with environment variables:**
```bash
export TASK_AGENTS_CONFIG_DIR="/path/to/task-agents/configs"
export CLAUDE_EXECUTABLE_PATH="/path/to/claude"
./run_server.sh
```
## Example Usage
### How the LLM Client Interacts
```
User: "Review this code for security issues"
LLM: Sees available agents → Selects "Code Reviewer" → Calls task_agents(agent="Code Reviewer", prompt="Review this code for security issues")
Server: Executes with Opus model and code review system prompt → Returns comprehensive review
```
### Another Example
```
User: "Fix the null pointer exception in my login function"
LLM: Analyzes request → Selects "Debugger" → Calls task_agents(agent="Debugger", prompt="Fix the null pointer exception in my login function")
Server: Executes with Sonnet model and debugging system prompt → Returns fix with explanation
```
## License
MIT License
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request
## Support
For issues and questions:
- Check existing issues
- Create a new issue with reproduction steps
- Include relevant logs and configurations
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/task-agents",
"name": "task-agents-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, ai, agents, claude, llm, fastmcp",
"author": "vredrick",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/58/15/cfabd525f9372fceb92442eced9a2a37f0c3694d33db92dc84f60a5432a4/task_agents_mcp-1.0.2.tar.gz",
"platform": null,
"description": "# Task-Agents MCP Server\n\nA Model Context Protocol (MCP) server that enables specialized AI agents by delegating tasks to Claude Code CLI with custom configurations. This creates a team of specialized AI assistants accessible through any MCP-compatible client.\n\n## Features\n\n- \ud83e\udd16 **Multiple Specialized Agents**: Code reviewer, debugger, test runner, documentation writer, and more\n- \ud83d\udd27 **Easy Configuration**: Simple markdown files define agent behavior\n- \ud83d\ude80 **Flexible Integration**: Works with Claude Desktop, Claude Code CLI, or any MCP client\n- \ud83d\udcdd **Custom System Prompts**: Each agent has tailored instructions for specific tasks\n- \ud83d\udee0\ufe0f **Tool Restrictions**: Control which tools each agent can access\n- \ud83c\udfaf **Simple API**: Single tool interface where LLM selects the appropriate agent\n- \ud83d\udcc1 **Smart Working Directory**: Agents default to saving files in their configured directory\n\n## Architecture\n\n```\nMCP Client \u2192 Task-Agents MCP Server \u2192 Claude Code CLI \u2192 Response\n```\n\nThe server reads agent configurations from markdown files and constructs Claude Code CLI commands:\n```bash\nclaude -p \"task description\" --system-prompt \"agent prompt\" --model opus --allowedTools Read Write Edit --output-format text\n```\n\n## Installation\n\n### Prerequisites\n\n1. **Python 3.11+** installed\n2. **Claude Code CLI** installed and working:\n ```bash\n claude --version\n ```\n\n### Installation Methods\n\n#### Method 1: PyPI Package with uvx (Recommended)\n\n```bash\n# Install and run with uvx (no installation needed)\nuvx task-agents-mcp\n\n# Or install with pip\npip install task-agents-mcp\npython -m task_agents_mcp\n```\n\n#### Method 2: Direct Python Execution (For Development)\n\n1. **Clone the repository:**\n ```bash\n git clone https://github.com/vredrick/task-agents.git\n cd task-agents\n ```\n\n2. **Install Python dependencies:**\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Run the server directly:**\n ```bash\n python server.py\n ```\n\n\n### Setup Steps\n\n1. **Find your Claude executable path:**\n ```bash\n which claude\n # If using an alias, check the actual path\n ```\n\n2. **Copy the task-agents folder to your project** (contains agent .md files):\n ```bash\n cp -r /Volumes/vredrick2/Claude-Code-Projects/task-agents/task-agents ./\n ```\n\n## Configuration for Claude Desktop\n\n1. **Open your Claude Desktop configuration file:**\n - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Linux: `~/.config/Claude/claude_desktop_config.json`\n\n2. **Add the task-agents server to the `mcpServers` section:**\n\n **Option A: Using uvx (Recommended for Python servers)**\n ```json\n {\n \"mcpServers\": {\n \"task-agents\": {\n \"command\": \"uvx\",\n \"args\": [\"task-agents-mcp\"],\n \"env\": {\n \"TASK_AGENTS_PATH\": \"/path/to/your/task-agents\",\n \"CLAUDE_EXECUTABLE_PATH\": \"/Users/username/.claude/local/claude\"\n }\n }\n }\n }\n ```\n\n **Option B: Using Python directly**\n ```json\n {\n \"mcpServers\": {\n \"task-agents\": {\n \"command\": \"python3.11\",\n \"args\": [\"/Volumes/vredrick2/Claude-Code-Projects/task-agents/server.py\"],\n \"env\": {\n \"TASK_AGENTS_PATH\": \"/Volumes/vredrick2/Claude-Code-Projects/task-agents/task-agents\",\n \"CLAUDE_EXECUTABLE_PATH\": \"/Users/vredrick/.claude/local/claude\"\n }\n }\n }\n }\n ```\n\n **Important environment variables:**\n - `TASK_AGENTS_PATH`: Path to your task-agents directory (required for Claude Desktop to find agents)\n - `CLAUDE_EXECUTABLE_PATH`: Full path to your Claude executable (required for Claude Desktop, not needed for Claude Code CLI)\n\n3. **Restart Claude Desktop** (Quit completely and reopen)\n\n## Configuration for Claude Code CLI\n\n### Option 1: Using MCP Config File \n\n1. **Using uvx (Recommended):**\n ```bash\n claude mcp add task-agents -s project uvx task-agents-mcp\n ```\n\n2. **Using Python directly:**\n ```bash\n # From your project directory where you copied task-agents folder\n # Note: Claude Code CLI doesn't need CLAUDE_EXECUTABLE_PATH - it finds Claude automatically\n claude mcp add task-agents -s project python3.11 /Volumes/vredrick2/Claude-Code-Projects/task-agents/server.py\n ```\n\n3. **Or use the provided `mcp_config.json`:**\n ```json\n {\n \"mcpServers\": {\n \"task-agents\": {\n \"command\": \"python3.11\",\n \"args\": [\"./server.py\"],\n \"env\": {}\n }\n }\n }\n ```\n Note: Claude Code CLI doesn't need `CLAUDE_EXECUTABLE_PATH` in the environment\n\n2. **Start Claude with the MCP config:**\n ```bash\n claude --mcp-config /path/to/task-agents/mcp_config.json\n ```\n\n### Option 2: Using Environment Variables\n\n1. **Set environment variables:**\n ```bash\n export TASK_AGENTS_CONFIG_DIR=\"/path/to/task-agents/configs\"\n export CLAUDE_EXECUTABLE_PATH=\"/path/to/claude/executable\"\n ```\n\n2. **Run the server script:**\n ```bash\n cd /path/to/task-agents\n ./run_server.sh\n ```\n\n3. **In another terminal, connect with Claude:**\n ```bash\n claude --mcp-config mcp_config.json\n ```\n\n## Configuration\n\n### Two Ways to Use Task-Agents\n\nTask-agents supports two deployment modes depending on your workflow:\n\n#### 1. Project-specific mode (Claude Code CLI)\nPerfect for working on specific projects:\n- Drop the `task-agents` folder into your project root directory\n- Start Claude Code from that project directory\n- Agents automatically work in your project context with `cwd: .`\n\n**Example directory structure:**\n```\nmy-awesome-project/ # \u2190 Your project root\n\u251c\u2500\u2500 src/\n\u251c\u2500\u2500 tests/\n\u251c\u2500\u2500 package.json\n\u2514\u2500\u2500 task-agents/ # \u2190 Drop task-agents folder here \n \u251c\u2500\u2500 code-reviewer.md\n \u251c\u2500\u2500 debugger.md\n \u2514\u2500\u2500 ...\n```\n\n**With `cwd: .` in agent configs**, agents will execute in `/path/to/my-awesome-project/` (the project root).\n\n#### 2. Global mode (Claude Desktop or fixed location)\nFor system-wide usage across multiple projects:\n- Keep `task-agents` folder in a fixed location (e.g., `~/task-agents`)\n- Set `TASK_AGENTS_PATH` environment variable to point to it\n- Configure individual agent working directories as needed\n\n**Example setup:**\n```bash\n# task-agents folder at fixed location\n~/task-agents/\n\u251c\u2500\u2500 code-reviewer.md\n\u251c\u2500\u2500 debugger.md\n\u2514\u2500\u2500 ...\n\n# Environment variable\nexport TASK_AGENTS_PATH=\"/Users/username/task-agents\"\n```\n\n### Working Directory Resolution\n\nThe `cwd` field in agent configurations is the **ONLY source** that controls where each agent executes:\n\n#### `cwd: .` (Default - Recommended)\n- **Always resolves to the parent directory of the task-agents folder**\n- **Project-specific mode**: If task-agents is in `/project/task-agents/`, agents run in `/project/`\n- **Global mode**: If TASK_AGENTS_PATH is `/home/user/task-agents`, agents run in `/home/user/`\n- **Perfect for project-specific agents** that need to work within your codebase\n- **Consistent across ALL clients** - Claude Desktop, Claude Code CLI, or any MCP client\n\n#### Absolute paths\nUse when you need agents to work in specific directories:\n```yaml\ncwd: /Users/username/my-specific-project\ncwd: /opt/projects/production-app\n```\n\n#### Environment variables\nFor flexible, user-specific paths:\n```yaml\ncwd: ${HOME}/projects/current\ncwd: ${WORKSPACE}/active-project\n```\n\n#### Default File Saving Behavior\n- **Agents are automatically instructed to save files in their working directory**\n- When creating files without an explicit path, agents will use relative paths (e.g., `./file.txt`)\n- This instruction is appended to every agent's system prompt\n- Users can still override by specifying absolute paths\n\n### Agent Configuration Format\n\nAgent configurations are stored as markdown files in the `task-agents` directory. Each file defines an agent with:\n\n- **agent-name**: Display name for the agent (shown to LLM clients)\n- **description**: Brief description of the agent's purpose\n- **tools**: Comma-separated list of Claude Code tools the agent can use\n- **model**: Claude model to use (opus/sonnet/haiku)\n- **cwd**: Working directory where the agent executes (see examples above)\n- **System-prompt**: Detailed instructions for the agent\n\n### Example Agent Configurations\n\n#### Project-specific agent (most common)\n```markdown\n---\nagent-name: Code Reviewer\ndescription: Expert code review specialist for quality, security, and maintainability analysis\ntools: Read, Search, Glob, Bash, Grep\nmodel: opus\ncwd: . # \u2190 Executes in project root\n---\n\nSystem-prompt:\nYou are a senior code reviewer ensuring high standards of code quality and security.\nWhen invoked, analyze the current project's codebase for issues and improvements.\n```\n\n#### Global agent for specific directory\n```markdown\n---\nagent-name: Production Monitor\ndescription: Monitor and analyze production systems\ntools: Read, Bash, Search\nmodel: sonnet\ncwd: /opt/production/logs # \u2190 Always works in this directory\n---\n\nSystem-prompt:\nYou monitor production systems and analyze logs for issues.\nFocus on performance metrics and error patterns.\n```\n\n#### User-specific flexible agent\n```markdown\n---\nagent-name: Personal Assistant\ndescription: General-purpose assistant for personal projects\ntools: Read, Write, Edit, Bash\nmodel: sonnet\ncwd: ${HOME}/current-project # \u2190 Uses environment variable\n---\n\nSystem-prompt:\nYou are a helpful assistant for personal development projects.\nAdapt to whatever project context you find yourself in.\n```\n\n\n## Available Agents\n\n- **code-reviewer**: Comprehensive code analysis for quality and security\n- **debugger**: Bug fixing and troubleshooting specialist\n- **test-runner**: Test automation and coverage improvement\n- **documentation-writer**: Technical documentation creation\n- **performance-optimizer**: Performance analysis and optimization\n\n## Usage\n\nOnce configured, the task-agents server provides a single tool:\n\n### Available Tool\n\n**`task_agents`** - Delegates tasks to specialized AI agents\n- **Parameters**:\n - `agent`: The name of the agent to use (e.g., \"Code Reviewer\", \"Debugger\")\n - `prompt`: The task or question for the agent\n\n### In Claude Desktop\n\nAfter setup, you can use natural language:\n- \"Use the Code Reviewer agent to analyze my pull request\"\n- \"Ask the Debugger agent to fix this error\"\n- \"Have the Documentation Writer create API docs\"\n\n### In Claude Code CLI\n\n```bash\n# Start a session with task-agents\nclaude --mcp-config /path/to/task-agents/mcp_config.json\n\n# Then use natural language as above\n```\n\n### How It Works\n\n1. **Claude sees the request** and the `task_agents` tool with available agents\n2. **Claude analyzes your request** and selects the appropriate agent\n3. **Claude calls `task_agents`** with:\n - `agent`: The selected agent name (e.g., \"Code Reviewer\", \"Debugger\")\n - `prompt`: Your specific task or question\n4. **The server executes** Claude Code CLI with the agent's configuration\n5. **Results are returned** to your Claude session\n\n## Creating Custom Agents\n\n1. Create a new `.md` file in the `task-agents/` directory\n2. Add YAML frontmatter with required fields\n3. Write a detailed system prompt after the frontmatter\n4. The agent will be automatically discovered on server restart\n\n### Required Fields\n\n- `agent-name`: Display name for the agent\n- `description`: What the agent does\n- `tools`: Available Claude Code tools\n- `model`: Which Claude model to use\n- `cwd`: Working directory path\n\n## Environment Variables\n\n- Agent configs support environment variable expansion in the `cwd` field\n- Use `${HOME}`, `${USER}`, etc. in your configurations\n\n## Error Handling\n\nThe server includes comprehensive error handling for:\n- Missing or malformed agent configurations\n- Claude CLI execution errors\n- Invalid task descriptions\n- Missing dependencies\n\n## Logging\n\nThe server logs:\n- Agent loading and discovery\n- Task delegation decisions\n- Claude CLI command execution\n- Errors and warnings\n\nSet logging level with standard Python logging configuration.\n\n## Development\n\n### Testing\n\nRun the test script to verify all agents are working:\n\n```bash\npython test_server.py\n```\n\n### Adding New Features\n\n1. Extend `AgentConfig` dataclass for new fields\n2. Update `_parse_agent_config` method\n3. Modify agent selection logic if needed\n4. Update documentation\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Claude CLI not found\"**\n - For Claude Desktop: Make sure `CLAUDE_EXECUTABLE_PATH` is set correctly in your config\n - For Claude Code CLI: This error shouldn't occur as it finds Claude automatically\n - Find your Claude path with: `which claude`\n - If it's an alias, find the actual executable path\n\n2. **\"No agents are currently configured\"**\n - Verify a `task-agents` directory exists in your project root\n - Check that `.md` files exist in the task-agents directory\n - Ensure you're running Claude Code from the project directory\n\n3. **\"Error executing Claude CLI\"**\n - Check that the working directory (`cwd`) exists\n - Verify Claude Code CLI works: `claude --version`\n - Check agent configuration syntax in `.md` files\n\n4. **Server not appearing in Claude Desktop**\n - Completely quit Claude Desktop (Cmd+Q on Mac)\n - Check JSON syntax in claude_desktop_config.json\n - Verify all paths are absolute paths\n - Restart Claude Desktop\n\n### Testing Your Setup\n\n1. **Test the server directly:**\n ```bash\n cd /path/to/task-agents\n python3.11 server.py\n ```\n You should see: \"Loaded X agents\" with a list\n\n2. **Test Claude CLI command:**\n ```bash\n /path/to/claude --version\n ```\n\n3. **Test with environment variables:**\n ```bash\n export TASK_AGENTS_CONFIG_DIR=\"/path/to/task-agents/configs\"\n export CLAUDE_EXECUTABLE_PATH=\"/path/to/claude\"\n ./run_server.sh\n ```\n\n## Example Usage\n\n### How the LLM Client Interacts\n```\nUser: \"Review this code for security issues\"\nLLM: Sees available agents \u2192 Selects \"Code Reviewer\" \u2192 Calls task_agents(agent=\"Code Reviewer\", prompt=\"Review this code for security issues\")\nServer: Executes with Opus model and code review system prompt \u2192 Returns comprehensive review\n```\n\n### Another Example\n```\nUser: \"Fix the null pointer exception in my login function\"\nLLM: Analyzes request \u2192 Selects \"Debugger\" \u2192 Calls task_agents(agent=\"Debugger\", prompt=\"Fix the null pointer exception in my login function\")\nServer: Executes with Sonnet model and debugging system prompt \u2192 Returns fix with explanation\n```\n\n## License\n\nMIT License\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Submit a pull request\n\n## Support\n\nFor issues and questions:\n- Check existing issues\n- Create a new issue with reproduction steps\n- Include relevant logs and configurations\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server that delegates tasks to specialized AI agents using FastMCP",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/vredrick/task-agents",
"Issues": "https://github.com/vredrick/task-agents/issues",
"Repository": "https://github.com/vredrick/task-agents.git"
},
"split_keywords": [
"mcp",
" ai",
" agents",
" claude",
" llm",
" fastmcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5c4c6478f7665d4b3f3fe63e28514ce41a1428d90ecf312c281055faaed35ff6",
"md5": "15d542352c854051befa0831e4ace7dd",
"sha256": "0fe15753886162149dd753973ed04b7c6b7021a382a8f046779f82e0541e7325"
},
"downloads": -1,
"filename": "task_agents_mcp-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15d542352c854051befa0831e4ace7dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19068,
"upload_time": "2025-08-02T05:31:17",
"upload_time_iso_8601": "2025-08-02T05:31:17.254373Z",
"url": "https://files.pythonhosted.org/packages/5c/4c/6478f7665d4b3f3fe63e28514ce41a1428d90ecf312c281055faaed35ff6/task_agents_mcp-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5815cfabd525f9372fceb92442eced9a2a37f0c3694d33db92dc84f60a5432a4",
"md5": "9ae879f26764dc959bbddb946d588e57",
"sha256": "34b8e3a0ef0299a6928674bc81bbfc52d1b44144d8c7c1391d5409f18ed3f32b"
},
"downloads": -1,
"filename": "task_agents_mcp-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "9ae879f26764dc959bbddb946d588e57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33348,
"upload_time": "2025-08-02T05:31:18",
"upload_time_iso_8601": "2025-08-02T05:31:18.427592Z",
"url": "https://files.pythonhosted.org/packages/58/15/cfabd525f9372fceb92442eced9a2a37f0c3694d33db92dc84f60a5432a4/task_agents_mcp-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 05:31:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "task-agents",
"github_not_found": true,
"lcname": "task-agents-mcp"
}
JSON
