MCP Task Management Simple Client

A standalone client/middleware package that acts as a bridge between MCP clients (like Cursor/Claude) and the task management server. This package provides a simplified interface for task management operations and can be easily integrated with any MCP-compatible client.

Features

• 🔗 MCP Protocol Bridge: Seamlessly connects MCP clients to your task management server
• 🎯 Smart Task Creation: Automatically extracts task details from natural language
• 🛠️ Full Task Management: Create, update, list, and manage tasks
• 🔧 Easy Configuration: Environment variables or configuration objects
• 🚀 Zero Setup: Works out of the box with default configurations
• 📝 TypeScript Support: Full type definitions included
• 🔄 Auto-retry Logic: Built-in error handling and retry mechanisms
• 🐛 Debug Mode: Detailed logging for troubleshooting

Installation

npm install @mcp-tasked/simple-client

Quick Start

1. Environment Setup

Create a .env file or set environment variables:

MCP_SERVER_URL=http://localhost:4000
DIRECTUS_TOKEN=your-directus-token-here
MCP_DEFAULT_USER_ID=your-user-id

2. MCP Client Configuration

For Cursor IDE

Add to your Cursor MCP settings (~/.cursor/mcp-settings.json):

{
  "mcpServers": {
    "task-management": {
      "command": "npx",
      "args": ["@mcp-tasked/simple-client"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:4000",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

For Claude Desktop

Add to your Claude MCP configuration:

{
  "mcpServers": {
    "task-management": {
      "command": "node",
      "args": ["/path/to/node_modules/@mcp-tasked/simple-client/dist/index.js"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:4000",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

3. Start Using

Once configured, you can use natural language in Cursor or Claude to manage tasks:

• "Create a task to fix the login bug"
• "List all my pending tasks"
• "Mark task XYZ as completed"
• "Update the documentation task priority to high"

Programmatic Usage

You can also use the client programmatically in your own applications:

import { createClientFromConfig } from '@mcp-tasked/simple-client';

const client = createClientFromConfig({
  serverUrl: 'http://localhost:4000',
  token: 'your-directus-token-here'
}, {
  debug: true,
  defaultUserId: 'your-user-id'
});

// Smart task creation from natural language
const result = await client.createSmartTask({
  text: 'I need to implement user authentication',
  context: 'auth module',
  userId: 'user-123'
});

// Create specific task
const task = await client.createTask({
  title: 'Implement OAuth login',
  description: 'Add Google and GitHub OAuth integration',
  userId: 'user-123',
  priority: 'high',
  estimated_hours: 6
});

// List tasks
const tasks = await client.listTasks({
  status: 'to_do',
  limit: 10
});

Available Tools

When used as an MCP server, the following tools are available:

smart_create_task

Automatically creates tasks from natural language descriptions.

Parameters:

• text (required): Natural language description
• context (optional): Additional context (file name, location, etc.)
• userId (optional): User ID creating the task

create_task

Creates a task with specific details.

Parameters:

• title (required): Task title
• description (optional): Task description
• userId (required): User ID of creator
• status (optional): Task status (to_do, in_progress, in_review, done, in_production)
• priority (optional): Priority level (low, medium, high, urgent)
• estimated_hours (optional): Estimated completion time

list_tasks

Lists tasks with optional filtering.

Parameters:

• status (optional): Filter by status
• assignee (optional): Filter by assignee
• limit (optional): Maximum number of results

get_task

Retrieves details of a specific task.

Parameters:

• taskId (required): Task ID to retrieve

update_task

Updates an existing task.

Parameters:

• taskId (required): Task ID to update
• title (optional): New title
• description (optional): New description
• status (optional): New status
• priority (optional): New priority

start_task

Starts working on a task (sets status to in_progress).

Parameters:

• taskId (required): Task ID to start
• userId (optional): User starting the task

complete_task

Marks a task as completed (sets status to done).

Parameters:

• taskId (required): Task ID to complete
• userId (optional): User completing the task

test_connection

Tests the connection to the task management server.

Configuration

Environment Variables

Configuration Object

interface McpClientConfig {
  serverUrl: string;
  token: string;
  timeout?: number;
  headers?: Record<string, string>;
}

interface McpClientBridgeOptions {
  debug?: boolean;
  defaultUserId?: string;
  retryOnFailure?: boolean;
  maxRetries?: number;
}

Error Handling

The client includes built-in error handling:

• Automatic Retries: Failed requests are automatically retried with exponential backoff
• Detailed Error Messages: Clear error messages with HTTP status codes
• Connection Testing: Built-in connection validation
• Type Safety: Full TypeScript support prevents runtime errors

Examples

Check the examples/ directory for complete usage examples:

• basic-usage.js: Basic programmatic usage
• cursor-integration/: Cursor IDE integration examples
• claude-integration/: Claude Desktop integration examples

Development

Building

npm run build

Development Mode

npm run dev

Testing

# Test connection to server
node examples/basic-usage.js

Compatibility

• Node.js: >= 18.0.0
• MCP Clients: Cursor IDE, Claude Desktop, and any MCP-compatible client
• Task Server: Compatible with the MCP Task Management Server

License

MIT

Support

For issues and questions:

1. Check the examples in the examples/ directory
2. Review the configuration templates in config/
3. Enable debug mode for detailed logging
4. Open an issue on GitHub

Note: This package requires a running instance of the MCP Task Management Server. Make sure your server is accessible at the configured URL before using the client.