@task-shepherd/mcp

Task Shepherd MCP Server

Model Context Protocol server providing Claude Code with direct access to Task Shepherd's project management capabilities. Perfect for AI-powered development workflows and automated project management.

Installation

Option 1: Using npx (Recommended)

# No installation needed - always uses latest version
npx @task-shepherd/mcp

Option 2: Global Install

# Install globally for permanent CLI access
npm install -g @task-shepherd/mcp

# Then use directly
task-shepherd-mcp

Note: npx is recommended as it ensures you're always using the latest version without managing global installations.

Quick Start

1. Get API Key

Get your Task Shepherd API key from your instance dashboard: Your Dashboard → Settings → API Keys → Create New Key

2. Configure Environment

export TASK_SHEPHERD_GRAPHQL_ENDPOINT="https://your-instance.taskshepherd.com/graphql"
export TASK_SHEPHERD_API_KEY="tks_your_api_key_here"

3. Start MCP Server

task-shepherd-mcp

4. Add to Claude Code

Add to your Claude Code MCP configuration (~/.claude/config.json):

Using npx (recommended):

{
  "mcpServers": {
    "task-shepherd": {
      "command": "npx",
      "args": ["@task-shepherd/mcp"],
      "env": {
        "TASK_SHEPHERD_GRAPHQL_ENDPOINT": "https://your-instance.taskshepherd.com/graphql",
        "TASK_SHEPHERD_API_KEY": "tks_your_api_key"
      }
    }
  }
}

Using global install:

{
  "mcpServers": {
    "task-shepherd": {
      "command": "task-shepherd-mcp",
      "env": {
        "TASK_SHEPHERD_GRAPHQL_ENDPOINT": "https://your-instance.taskshepherd.com/graphql",
        "TASK_SHEPHERD_API_KEY": "tks_your_api_key"
      }
    }
  }
}

5. Use in Claude Code

claude --mcp task-shepherd
# Now Claude has access to all Task Shepherd tools!

Multi-Organization Support

The MCP server supports multiple Task Shepherd organizations automatically. When you use the Task Shepherd agent (@task-shepherd/agent), the MCP server will:

🏢 Automatic Organization Detection

• Reads configuration from ~/.task-shepherd-agent/config.json (customizable via AGENT_CONFIG_DIR)
• Initializes GraphQL clients for each enabled organization
• Uses organization-specific API URLs and authentication

📁 Custom Configuration Directory

{
  "mcpServers": {
    "task-shepherd": {
      "command": "npx",
      "args": ["@task-shepherd/mcp"],
      "env": {
        "AGENT_CONFIG_DIR": "/custom/path"
      }
    }
  }
}

🔄 Organization Management Tools

# List available organizations
list_organizations

# Set default organization for operations
set_default_organization --organizationId "production"

🎯 Organization-Scoped Operations

All tools now accept an optional organizationId parameter:

# List projects from specific organization
list_projects --organizationId "production" --limit 10

# Create project in specific organization
create_project --organizationId "staging" --name "Test Project"

📁 Configuration Example

The agent creates a multi-org config like this:

{
  "defaultOrganization": "default",
  "organizations": {
    "default": {
      "name": "Default Organization",
      "apiUrl": "http://default.dev.taskshepherd.local/api/graphql",
      "apiKey": "tks_user_xxx",
      "enabled": true
    },
    "production": {
      "name": "Production Environment", 
      "apiUrl": "https://prod.taskshepherd.com/api/graphql",
      "apiKey": "tks_prod_xxx",
      "enabled": true
    }
  }
}

Features

🚀 Direct API Access

Claude can directly interact with your Task Shepherd instance - no intermediate services or complexity.

📋 Complete Project Management

Full access to projects, stories, tasks, and work assignment capabilities across multiple organizations.

🔄 Pure Passthrough

No caching, state management, or data transformation - everything goes directly to the Task Shepherd API.

🛡️ Secure Authentication

Uses your Task Shepherd API keys with proper scoping and permissions per organization.

⚡ Real-time Operations

All operations happen in real-time against your live Task Shepherd data.

Available Tools

Project Management

# List all projects
list_projects

# Get specific project with stories  
get_project --id "project-123"

# Create new project
create_project --name "New Project" --description "Project description"

# Update project details
update_project --id "project-123" --stage "DEVELOPMENT"

Story Management

# List stories for a project
list_stories --projectId "project-123"

# Get story with tasks
get_story --id "story-456"

# Create new story
create_story --projectId "project-123" --title "User Authentication"

# Claim story for implementation
claim_story --id "story-456"

# Mark story complete
complete_story --id "story-456" --implementationSummary "Added JWT authentication..."

Task Management

# List tasks for a story
list_tasks --storyId "story-456"

# Get task details
get_task --id "task-789"

# Create new task
create_task --storyId "story-456" --title "Create login form" --areas "frontend,react"

# Claim task
claim_task --id "task-789"

# Complete task
complete_task --id "task-789" --implementationSummary "Created login form component"

Work Discovery

# Find available work to claim
get_available_work --projectId "project-123" --areas "frontend,backend"

Example Workflows

Claude Code Project Analysis

# Claude can analyze a codebase and create tasks
claude "Analyze this React project and create appropriate stories and tasks in Task Shepherd"

# Claude will:
# 1. Use get_project to understand the project structure
# 2. Use create_story to break down features
# 3. Use create_task to define implementation steps
# 4. Use update_project to reflect current status

Automated Development Workflow

# Claude can manage development workflow
claude "Find available frontend tasks and provide implementation guidance"

# Claude will:
# 1. Use get_available_work to find unclaimed tasks
# 2. Use claim_task to assign work
# 3. Provide implementation guidance
# 4. Use complete_task when implementation is done

Project Planning

# Claude can help with project planning
claude "Review project requirements and suggest a development plan"

# Claude will:
# 1. Use get_project to understand current state
# 2. Use list_stories to review planned features
# 3. Use create_story for missing requirements
# 4. Use update_project to reflect planning decisions

Configuration

Environment Variables

# Required: Task Shepherd API endpoint
TASK_SHEPHERD_GRAPHQL_ENDPOINT="https://api.taskshepherd.com/graphql"

# Required: API key for authentication  
TASK_SHEPHERD_API_KEY="tks_your_api_key"

# Optional: Enable debug logging
DEBUG=mcp:*

Claude Desktop Configuration

For Claude Desktop, add to your MCP configuration:

Using npx (recommended):

{
  "mcpServers": {
    "task-shepherd": {
      "command": "npx",
      "args": ["@task-shepherd/mcp"],
      "env": {
        "TASK_SHEPHERD_GRAPHQL_ENDPOINT": "https://your-instance.taskshepherd.com/graphql",
        "TASK_SHEPHERD_API_KEY": "tks_your_api_key"
      }
    }
  }
}

Using global install:

{
  "mcpServers": {
    "task-shepherd": {
      "command": "task-shepherd-mcp",
      "env": {
        "TASK_SHEPHERD_GRAPHQL_ENDPOINT": "https://your-instance.taskshepherd.com/graphql",
        "TASK_SHEPHERD_API_KEY": "tks_your_api_key"
      }
    }
  }
}

Claude Code CLI Configuration

For Claude Code CLI, add to ~/.claude/config.json:

Using npx (recommended):

{
  "mcpServers": {
    "task-shepherd": {
      "command": "npx",
      "args": ["@task-shepherd/mcp"],
      "env": {
        "TASK_SHEPHERD_GRAPHQL_ENDPOINT": "https://your-instance.taskshepherd.com/graphql",
        "TASK_SHEPHERD_API_KEY": "tks_your_api_key"
      }
    }
  }
}

Using global install:

{
  "mcpServers": {
    "task-shepherd": {
      "command": "task-shepherd-mcp",
      "env": {
        "TASK_SHEPHERD_GRAPHQL_ENDPOINT": "https://your-instance.taskshepherd.com/graphql",
        "TASK_SHEPHERD_API_KEY": "tks_your_api_key"
      }
    }
  }
}

API Integration

GraphQL Endpoint

The MCP server connects directly to your Task Shepherd GraphQL API:

# Test your connection
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TASK_SHEPHERD_API_KEY" \
  -d '{"query": "query { __typename }"}' \
  $TASK_SHEPHERD_GRAPHQL_ENDPOINT

Authentication

All requests use your API key for authentication:

• API keys are created in your Task Shepherd dashboard
• Keys can be scoped with specific permissions
• No additional authentication setup required

Data Flow

Claude Code → MCP Server → Task Shepherd GraphQL API → Database

All operations are real-time and directly modify your Task Shepherd data.

Use Cases

🤖 AI-Powered Development

• Claude analyzes codebases and creates structured project plans
• Automatic story and task generation from requirements
• Code review integration with project tracking

📊 Project Management Automation

• Automated status updates based on code changes
• AI-generated project timelines and estimates
• Smart work assignment based on developer skills

🔄 Development Workflow Integration

• Claude manages development lifecycle in Task Shepherd
• Automatic task claiming and completion
• Integration with existing development tools

📈 Planning and Analysis

• AI-powered project analysis and recommendations
• Automated requirement breakdown and estimation
• Risk assessment and mitigation planning

Supported Operations

Project Operations

• ✅ List projects with filtering and pagination
• ✅ Get project details with stories and tasks
• ✅ Create and update projects
• ✅ Project status and progress tracking

Story Operations

• ✅ List stories with status filtering
• ✅ Get story details with acceptance criteria
• ✅ Create stories with priorities and tags
• ✅ Claim and complete stories
• ✅ Submit stories for review

Task Operations

• ✅ List tasks with area and status filtering
• ✅ Get task details with implementation notes
• ✅ Create tasks with technical areas
• ✅ Claim and complete tasks
• ✅ Track implementation progress

Work Management

• ✅ Discover available work by skills/areas
• ✅ Smart work assignment
• ✅ Progress tracking and reporting

Troubleshooting

Connection Issues

# Test GraphQL endpoint
curl -X POST -H "Content-Type: application/json" \
  -H "X-API-Key: $TASK_SHEPHERD_API_KEY" \
  -d '{"query": "query { __typename }"}' \
  $TASK_SHEPHERD_GRAPHQL_ENDPOINT

# Should return: {"data": {"__typename": "Query"}}

Authentication Problems

# Verify API key format
echo $TASK_SHEPHERD_API_KEY
# Should start with "tks_"

# Check API key permissions in Task Shepherd dashboard
# Ensure key has required scopes for your operations

MCP Server Issues

# Test MCP server directly
npx @task-shepherd/mcp
# or if globally installed: task-shepherd-mcp

# Enable debug logging
DEBUG=mcp:* npx @task-shepherd/mcp

# Check Claude Code can see the tools
claude --mcp task-shepherd --list-tools

Common Solutions

• Invalid API Key: Regenerate key in Task Shepherd dashboard
• Connection Timeout: Check firewall and network connectivity
• Permission Denied: Verify API key has required permissions
• GraphQL Errors: Check Task Shepherd backend logs for details

Development

# Install dependencies
npm install

# Build with bundling (ESM + esbuild)
npm run build

# Run in development mode
npm run dev

# Run tests
npm run test

# Type checking
npm run type-check

Build Architecture

• ESM Package: Pure ES modules ("type": "module")
• Bundling: Uses esbuild to bundle @task-shepherd/shared and zod inline
• External Dependencies: Only @modelcontextprotocol/sdk, graphql, and graphql-request remain external
• Publishing: Version via git tags (@task-shepherd/mcp@x.y.z), CI handles npm publishing

Security

API Key Management

• Store API keys securely using environment variables
• Never commit API keys to version control
• Rotate API keys regularly
• Use scoped permissions (principle of least privilege)

Network Security

• Use HTTPS endpoints for production
• Consider IP whitelisting for sensitive environments
• Monitor API usage for unusual patterns

Data Access

• API keys inherit user permissions from Task Shepherd
• All operations are logged in Task Shepherd audit trail
• Respect data privacy and access controls

Performance

Caching Strategy

• No caching: All requests go directly to API for real-time data
• Stateless design: Each tool call is independent
• Efficient queries: Uses GraphQL for precise data fetching

Rate Limiting

• Respects Task Shepherd API rate limits
• Implements exponential backoff for retries
• Monitors usage to prevent quota exhaustion

Optimization Tips

• Use specific field selection in GraphQL queries
• Batch operations when possible
• Monitor token usage in Claude Code

Integration Examples

Git Workflow Integration

# After code changes, update Task Shepherd
claude "I just implemented user authentication. Update the relevant tasks in Task Shepherd as complete."

Code Review Workflow

# Review code and create improvement tasks
claude "Review this pull request and create tasks for any issues found."

Project Planning

# Plan new features
claude "Analyze these requirements and create a complete project plan in Task Shepherd."

License

Proprietary software - see LICENSE.md for usage terms.

Support

• Connection issues: Test GraphQL endpoint with curl
• Authentication: Verify API key in Task Shepherd dashboard
• Debug mode: Use DEBUG=mcp:* npx @task-shepherd/mcp
• Tool listing: Use claude --mcp task-shepherd --list-tools