JSPM

��# MCP Task Management Simple Client Bridge A lightweight Model Context Protocol (MCP) client bridge that provides seamless integration between MCP clients (like Cursor IDE/Claude) and the MCP Task Management Server. This bridge acts as middleware, translating MCP protocol calls into HTTP requests and providing a simplified interface for task management operations. ## =؀� What is this? The Simple Client Bridge is a standalone NPM package that: - =�� Bridges Communication - Translates MCP protocol calls to HTTP API requests - =��� Standalone Package - Can be installed via NPM and used independently - <د� Simplified Interface** - Provides easy-to-use methods for common task operations - **=�� Auto-Retry Logic** - Built-in retry mechanisms for robust communication - **=���� Authentication Handling** - Manages Directus token authentication automatically - **=��� Debug Support** - Comprehensive logging for troubleshooting - **�& TypeScript Ready** - Full TypeScript support with complete type definitions ## <���� Architecture %%%%%%%%%%%%%%%%%%% MCP Protocol %%%%%%%%%%%%%%%%%%%% HTTP/REST %%%%%%%%%%%%%%%%%%% % Cursor IDE % �%%%%%%%%%%%%%%%%�% % Client Bridge % �%%%%%%%%%%%%%%%�% % MCP Server % % (MCP Client) % (stdio/http) % (Middleware) % (API Calls) % (Task Mgmt) % %%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%% ### Core Components - **src/index.ts** - Main entry point and CLI interface - **src/client.ts** - HTTP client bridge implementation - **src/mcp-server.ts** - MCP protocol server wrapper - **src/config.ts** - Configuration and environment utilities - **src/types.ts** - TypeScript type definitions ## =��� Installation ### Via NPM (Recommended) bash # Install globally for CLI usage npm install -g mcp-task-simple-client # Or install locally in your project npm install mcp-task-simple-client ### Via NPX (No Installation) bash # Run directly without installation npx mcp-task-simple-client ### From Source bash git clone <repository-url> cd simple-client npm install npm run build ## =�'� Configuration ### Environment Variables Create a .env file or set environment variables: env # Required: MCP Task Management Server URL MCP_SERVER_URL=https://your-mcp-server.com/mcp-rpc # Required: Directus authentication token DIRECTUS_TOKEN=your-directus-token # Optional: Request timeout in milliseconds MCP_TIMEOUT=30000 # Optional: Enable debug logging MCP_DEBUG=true # Optional: Custom headers (JSON format) MCP_HEADERS={"Custom-Header": "value"} ### Configuration Options | Variable | Description | Default | Required | |----------|-------------|---------|----------| | MCP_SERVER_URL | URL of the MCP Task Management Server | http://localhost:4000 | ' | | DIRECTUS_TOKEN | Authentication token for Directus | - | ' | | MCP_TIMEOUT | HTTP request timeout (ms) | 30000 | L' | | MCP_DEBUG | Enable debug logging | false | L' | | MCP_HEADERS | Additional HTTP headers (JSON) | {} | L' | ## =�� Integration Methods ### 1. Cursor IDE Integration (MCP Protocol) Add to your Cursor MCP configuration: json { "mcpServers": { "tasked-dot-work": { "command": "npx", "args": ["mcp-task-simple-client"], "env": { "MCP_SERVER_URL": "https://your-mcp-server.com/mcp-rpc", "DIRECTUS_TOKEN": "your-token", "MCP_DEBUG": "true" } } } } ### 2. Programmatic Usage (Node.js) typescript import { McpTaskClientBridge, createClientFromEnv } from 'mcp-task-simple-client'; // Create client from environment variables const client = createClientFromEnv({ debug: true }); // Or create with explicit configuration const client = new McpTaskClientBridge({ serverUrl: 'https://your-mcp-server.com', token: 'your-directus-token', timeout: 30000 }, { debug: true, retryOnFailure: true, maxRetries: 3 }); // Test connection const connectionTest = await client.testConnection(); console.log('Connection:', connectionTest.success ? 'OK' : 'Failed'); ### 3. CLI Usage bash # Start MCP server directly mcp-task-simple-client # With environment file MCP_DEBUG=true mcp-task-simple-client # Using npx npx mcp-task-simple-client ## =���� Available Methods ### Core Task Operations #### Smart Task Creation typescript await client.createSmartTask({ text: "I need to fix the authentication bug in the login component", context: "src/auth/login.ts", userId: "user-123" }); #### Standard Task Management typescript // Create task await client.createTask({ title: "Fix login bug", description: "Authentication fails on invalid credentials", priority: "high", status: "to_do", userId: "user-123" }); // Update task await client.updateTask({ taskId: "task-456", status: "in_progress", priority: "urgent" }); // Get task details await client.getTask("task-456"); // List tasks with filters await client.listTasks({ status: "in_progress", priority: "high", assignee: "user-123", limit: 10 }); #### Task Workflow typescript // Start working on task await client.startTask("task-456", "user-123"); // Complete task await client.completeTask("task-456", "user-123"); #### Advanced Query typescript // Context-aware task querying await client.cursorTaskQuery({ query: "show me all high priority bugs", status: "to_do", priority: "high", contextAware: true, currentFile: "src/components/Login.tsx", limit: 5 }); ### Utility Methods typescript // Test server connection const result = await client.testConnection(); // Get server information const info = await client.getServerInfo(); ## =��� Usage Examples ### Example 1: Basic Task Creation typescript import { createClientFromEnv } from 'mcp-task-simple-client'; async function createTaskExample() { const client = createClientFromEnv({ debug: true }); // Test connection first const connection = await client.testConnection(); if (!connection.success) { console.error('Connection failed:', connection.error); return; } // Create a new task const result = await client.createTask({ title: "Implement user authentication", description: "Add JWT-based authentication system", priority: "medium", status: "to_do", userId: "developer-123" }); console.log('Task created:', result); } ### Example 2: Smart Task Detection typescript async function smartTaskExample() { const client = createClientFromEnv(); // Smart task creation from natural language const result = await client.createSmartTask({ text: "TODO: refactor this function to use async/await", context: "src/utils/dataFetcher.js:45", userId: "developer-123" }); console.log('Smart task result:', result); } ### Example 3: Task Workflow Management typescript async function workflowExample() { const client = createClientFromEnv(); // List pending tasks const tasks = await client.listTasks({ status: "to_do", assignee: "developer-123", limit: 5 }); console.log('Pending tasks:', tasks); // Start working on first task if (tasks.content?.[0]?.text) { const taskData = JSON.parse(tasks.content[0].text); if (taskData.data?.length > 0) { const taskId = taskData.data[0].id; await client.startTask(taskId, "developer-123"); console.log(Started working on task: ${taskId}); } } } ## =� � Error Handling The client includes comprehensive error handling and retry logic: typescript // The client automatically retries failed requests const client = new McpTaskClientBridge(config, { retryOnFailure: true, // Enable auto-retry maxRetries: 3, // Maximum retry attempts debug: true // Log detailed error information }); // Handle errors in your code try { const result = await client.createTask(taskData); if (result.isError) { console.error('Task creation failed:', result.content[0].text); } else { console.log('Task created successfully:', result.content[0].text); } } catch (error) { console.error('Network error:', error.message); } ## =؀� Building and Development ### Build Commands bash # Install dependencies npm install # Build TypeScript to JavaScript npm run build # Development with watch mode npm run dev # Clean build artifacts npm run clean # Prepare for publishing npm run prepublishOnly ### Project Structure simple-client/ %%% src/ % %%% index.ts # Main entry point & CLI % %%% client.ts # HTTP client bridge % %%% mcp-server.ts # MCP protocol wrapper % %%% config.ts # Configuration utilities % %%% types.ts # TypeScript definitions %%% dist/ # Compiled JavaScript output %%% package.json # NPM package configuration %%% tsconfig.json # TypeScript configuration %%% example-mcp.json # Example MCP configuration ## =��� Available Tools (MCP Protocol) When used as an MCP server, the bridge exposes all task management tools: ### Task Management Tools - smart_task_creator - AI-powered task detection from natural language - create_task - Create new tasks with full details - update_task - Update existing task properties - get_task - Retrieve task details by ID - list_tasks - List tasks with filtering options - start_task - Mark task as in-progress - complete_task - Mark task as completed ### Project Management Tools - create_project - Create new projects - get_project - Get project details - list_projects - List all projects - update_project - Update project information ### Time Tracking Tools - log_time - Log time spent on tasks - get_task_time - Get total time for a task - get_user_time - Get user's time entries - get_project_time - Get project time summary ### AI Assistant Tools - ai_analyze_code - Comprehensive code analysis - ai_code_review - Intelligent code review - ai_suggest_tests - Generate test suggestions - ai_generate_commit_message - Smart commit messages ### Cursor Integration Tools - cursor_quick_task - Quick task creation from context - cursor_code_task - Create tasks from code analysis - cursor_feature_task - Comprehensive feature planning - cursor_fix_task - Bug fix task creation - cursor_task_query - Context-aware task querying - cursor_daily_standup - Generate standup reports ### Workflow Automation Tools - workflow_start_task - Intelligent task startup - workflow_update_progress - Track task progress - workflow_complete_task - Complete with validation - workflow_smart_transition - AI-guided state transitions ## =�'� Troubleshooting ### Common Issues #### 1. Connection Failed bash # Check server URL and token curl -H "x-directus-token: YOUR_TOKEN" https://your-server.com/ # Verify environment variables echo $MCP_SERVER_URL echo $DIRECTUS_TOKEN #### 2. Authentication Errors bash # Test token validity curl -H "x-directus-token: YOUR_TOKEN" https://your-server.com/test-directus #### 3. MCP Protocol Issues bash # Enable debug logging MCP_DEBUG=true npx mcp-task-simple-client # Check Cursor MCP logs # Look in Cursor IDE Developer Tools Console ### Debug Mode Enable comprehensive logging: typescript const client = new McpTaskClientBridge(config, { debug: true // Enables detailed request/response logging }); Or via environment: bash MCP_DEBUG=true npx mcp-task-simple-client ## =��� Performance & Reliability ### Features - **Auto-Retry Logic** - Automatic retry for failed network requests - **Exponential Backoff** - Intelligent retry timing to avoid overwhelming server - **Connection Pooling** - Efficient HTTP connection management - **Timeout Handling** - Configurable request timeouts - **Error Recovery** - Graceful handling of network and server errors ### Best Practices - Set appropriate timeout values for your network - Use debug mode during development - Monitor server logs for authentication issues - Test connection before performing operations ## =��� License MIT License - see LICENSE file for details ## <ؘ� Support For issues and questions: 1. Check debug logs with MCP_DEBUG=true 2. Verify server connectivity with testConnection() 3. Ensure environment variables are properly set 4. Check server-side logs for authentication issues ## =�.� Roadmap - [ ] WebSocket support for real-time updates - [ ] Caching layer for improved performance - [ ] Plugin system for custom tools - [ ] Enhanced error recovery mechanisms - [ ] Metrics and monitoring capabilities - [ ] CLI commands for direct task management