feat: Implement hybrid tool consolidation strategy (Task 1.1) by devondragon · Pull Request #10 · devondragon/MotionMCP

devondragon · 2025-08-11T16:14:27Z

Summary

This PR implements Task 1.1: Hybrid Tool Consolidation Strategy to address MCP client tool limits (~100 tools across all servers).

Key Changes

✅ Created consolidated motion_projects and motion_tasks tools that combine CRUD operations
✅ Added MOTION_MCP_TOOLS environment variable for configurable tool sets
✅ Reduced tool count from fixed 18 to configurable 3/6/20 tools
✅ Maintained backward compatibility with legacy tools

Implementation Details

Consolidated Tools

motion_projects: Single tool for all project operations (create, list, get, update, delete)
motion_tasks: Single tool for all task operations (create, list, get, update, delete, move, unassign)

Configuration Options

minimal: 3 tools (consolidated + workspaces)
essential: 6 tools (default - adds search, context, users)
all: 20 tools (includes all legacy tools)
custom:tool1,tool2: Custom tool selection

Testing

Verified all configurations work correctly:

MOTION_MCP_TOOLS=minimal # Returns 3 tools
MOTION_MCP_TOOLS=essential # Returns 6 tools (default)
MOTION_MCP_TOOLS=all # Returns 20 tools
MOTION_MCP_TOOLS=custom:motion_tasks,motion_projects # Returns 2 tools

Documentation

Updated README with comprehensive tool configuration guide
Updated CLAUDE.md with consolidated tools documentation
Updated .env.example with MOTION_MCP_TOOLS configuration

Files Changed

src/mcp-server.ts - Added consolidated handlers and configuration logic
src/types/mcp-tool-args.ts - Added TypeScript interfaces for consolidated tools
.env.example - Added MOTION_MCP_TOOLS configuration
CLAUDE.md - Updated with tool configuration docs
README.md - Added comprehensive configuration documentation

🤖 Generated with Claude Code

- Add consolidated motion_projects and motion_tasks tools - Implement MOTION_MCP_TOOLS configuration (minimal, essential, all, custom) - Reduce tool count from 18 to configurable sets (3-20 tools) - Keep legacy tools for backward compatibility - Update documentation and .env.example The consolidated tools combine CRUD operations by resource type: - motion_projects: create, list, get, update, delete - motion_tasks: create, list, get, update, delete, move, unassign Default configuration is 'essential' with 6 tools total.

- Document all configuration options (minimal, essential, all, custom) - List available tools for each configuration - Add examples for consolidated tools usage - Update LLM integration examples with tool configuration

Copilot

Pull Request Overview

This PR implements a hybrid tool consolidation strategy to address MCP client tool limits by reducing the tool count from a fixed 18 to configurable sets ranging from 3-20 tools. The implementation introduces consolidated tools that combine multiple CRUD operations into single tools while maintaining backward compatibility.

Created consolidated motion_projects and motion_tasks tools that handle multiple operations via an operation parameter
Added MOTION_MCP_TOOLS environment variable for flexible tool configuration (minimal/essential/all/custom)
Maintained all existing individual tools for backward compatibility when using the "all" configuration

Reviewed Changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/types/mcp-tool-args.ts	Added TypeScript interfaces for consolidated tools with operation-based parameters
src/mcp-server.ts	Implemented consolidated tool handlers and configuration logic with tool filtering
README.md	Added comprehensive tool configuration documentation with examples
CLAUDE.md	Updated with consolidated tools documentation and configuration options
.env.example	Added MOTION_MCP_TOOLS configuration examples
context/working-state.md	Updated working state to reflect completed task
.claude/settings.local.json	Added test command to allowed bash commands

Copilot · 2025-08-11T16:16:38Z

src/mcp-server.ts

+          return formatMcpError(new Error("Task ID and target project ID are required for move operation"));
+        }
+        // TODO: Implement move task handler
+        return formatMcpSuccess(`Moving task ${params.taskId} to project ${params.targetProjectId}`);


The move task operation returns a placeholder success message without actually implementing the functionality. This could mislead users into thinking the operation succeeded when it didn't perform any actual work.

Suggested change

return formatMcpSuccess(`Moving task ${params.taskId} to project ${params.targetProjectId}`);

try {

await this.motionApi.moveTask(params.taskId, params.targetProjectId);

return formatMcpSuccess(`Task ${params.taskId} moved to project ${params.targetProjectId}`);

} catch (err) {

return formatMcpError(err);

}

Copilot · 2025-08-11T16:16:39Z

src/mcp-server.ts

+        return formatMcpError(new Error(`Unknown operation: ${operation}`));
+    }
+  }
+


The unassign task operation returns a placeholder success message without actually implementing the functionality. This could mislead users into thinking the operation succeeded when it didn't perform any actual work.

Suggested change

return this.handleUnassignTask({ taskId: params.taskId });

default:

return formatMcpError(new Error(`Unknown operation: ${operation}`));

}

}

private async handleUnassignTask(args: { taskId: string }): Promise<McpToolResponse> {

if (!this.motionService) {

return formatMcpError(new Error("Service not initialized"));

}

try {

const result = await this.motionService.unassignTask(args.taskId);

return formatMcpSuccess(`Successfully unassigned task ${args.taskId}`);

} catch (error) {

return formatMcpError(error);

}

}

Copilot · 2025-08-11T16:16:39Z

src/mcp-server.ts

+            .filter(Boolean) as McpToolDefinition[];
+        }
+        // Default to essential if invalid config
+        mcpLog(LOG_LEVELS.WARN, `Invalid MOTION_MCP_TOOLS config: ${this.toolsConfig}, defaulting to essential`);


The warning message for invalid configuration is logged but the function continues to return the essential tools. Consider adding validation at initialization time to fail fast with clear error messages rather than silently falling back to defaults.

- Change move and unassign operations to return error instead of fake success - Change get single project/task to return error with workaround suggestion - Add TODO references to corresponding implementation tasks - Addresses GitHub Copilot PR review feedback These operations are intentionally not implemented yet as they are separate tasks (task-1.3 and task-2.4) to be completed later.

- Validate MOTION_MCP_TOOLS at initialization time - Check custom tool names exist before starting server - Log clear error messages for invalid configurations - Still default to 'essential' for invalid presets (with warning) - Fail fast for invalid custom tool names - Addresses GitHub Copilot PR review feedback This ensures configuration errors are caught early with helpful error messages rather than silently falling back to defaults.

devondragon added 4 commits August 11, 2025 09:53

docs: Update task tracking for completed task-1.1

ae82e9c

docs: Add comprehensive tool configuration documentation to README

cc11124

- Document all configuration options (minimal, essential, all, custom) - List available tools for each configuration - Add examples for consolidated tools usage - Update LLM integration examples with tool configuration

feat: Add permission for version check command in settings

8d42849

devondragon requested a review from Copilot August 11, 2025 16:15

devondragon self-assigned this Aug 11, 2025

devondragon added the enhancement New feature or request label Aug 11, 2025

Copilot AI reviewed Aug 11, 2025

View reviewed changes

devondragon added 2 commits August 11, 2025 10:20

devondragon merged commit d8f7dc0 into main Aug 11, 2025

devondragon deleted the feature/task-1.1-hybrid-tool-consolidation branch August 11, 2025 16:25

claude bot mentioned this pull request Feb 19, 2026

fix(pagination): surface truncation notices to MCP clients #62

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Implement hybrid tool consolidation strategy (Task 1.1)#10

feat: Implement hybrid tool consolidation strategy (Task 1.1)#10
devondragon merged 6 commits intomainfrom
feature/task-1.1-hybrid-tool-consolidation

devondragon commented Aug 11, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Aug 11, 2025

Uh oh!

Copilot AI Aug 11, 2025

Uh oh!

Copilot AI Aug 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

-        return formatMcpSuccess(`Moving task ${params.taskId} to project ${params.targetProjectId}`);
+        try {
+          await this.motionApi.moveTask(params.taskId, params.targetProjectId);
+          return formatMcpSuccess(`Task ${params.taskId} moved to project ${params.targetProjectId}`);
+        } catch (err) {
+          return formatMcpError(err);
+        }

+        return this.handleUnassignTask({ taskId: params.taskId });
+      default:
+        return formatMcpError(new Error(`Unknown operation: ${operation}`));
+    }
+  }
+  private async handleUnassignTask(args: { taskId: string }): Promise<McpToolResponse> {
+    if (!this.motionService) {
+      return formatMcpError(new Error("Service not initialized"));
+    }
+    try {
+      const result = await this.motionService.unassignTask(args.taskId);
+      return formatMcpSuccess(`Successfully unassigned task ${args.taskId}`);
+    } catch (error) {
+      return formatMcpError(error);
+    }
+  }

Conversation

devondragon commented Aug 11, 2025

Summary

Key Changes

Implementation Details

Consolidated Tools

Configuration Options

Testing

Documentation

Files Changed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments