refactor!: consolidate MCP tools and CLI commands

[carlos-alm]

Summary

• Reduce MCP tool surface from 32 to 29 by merging overlapping tools:
  • query_function → query with deps/path modes (absorbs fn_deps + symbol_path)
  • execution_flow gains list mode (absorbs list_entry_points)
  • dataflow simplified to edges + impact only (path mode removed)
• CLI commands consolidated: fn and path merged into query (--path flag for path mode), dataflow --path removed
• Batch commands updated: fn removed, dataflow added, query now uses fnDepsData
• Pagination defaults updated: query: 10 replaces query_function: 50, fn_deps: 10, list_entry_points: 100
• No programmatic API changes: all *Data functions remain exported from src/index.js

Continuation of #171.

Test plan

• npm run lint — clean (only pre-existing warning in queries.test.js)
• Unit tests pass: tests/unit/mcp.test.js (35 tests)
• Integration tests pass: tests/integration/batch.test.js (26 tests), tests/integration/pagination.test.js (55 tests)
• CLI tests updated: tests/integration/cli.test.js
• MCP tool count verified: buildToolList(false) → 28 (single-repo), buildToolList(true) → 29 (multi-repo, includes list_repos)
• CI full test suite

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review Analysis

Reviewing PR #263: refactor!: consolidate MCP tools and CLI commands

Todo List:

• Phase 1: Root Cause Analysis - understand the problem being solved
• Phase 2: Configuration Change Detection - check for high-risk config changes
• Phase 3: Test Integrity - verify no weakened tests or assertions
• Phase 4: Code Quality Review - analyze implementation details
• Final Assessment - provide structured rating and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: The PR consolidates overlapping MCP tools from 32 to 29 by merging redundant functionality:

• query_function + fn_deps + symbol_path → unified query tool with mode parameter
• list_entry_points → absorbed into execution_flow with list mode
• dataflow path mode removed (now just edges + impact)

Why This Approach: This is legitimate refactoring addressing API surface complexity. The consolidation is justified - having separate tools for fn_deps vs query_function when they provide similar dependency chain functionality creates confusion. The mode-based approach is cleaner.

Risk Assessment: LOW - This is architectural cleanup, not hiding symptoms.

Phase 2: Configuration Changes ✅

✅ No configuration relaxation detected
✅ No test timeouts increased
✅ No coverage thresholds lowered
✅ No TypeScript strict mode disabled
✅ No build configuration changes
✅ Minimal biome.json changes - only scope-related formatting

This is clean refactoring without any red flag configuration changes.

Phase 3: Test Integrity ✅

✅ Tests properly updated to reflect new API

• CLI tests updated from query to reflect merged command structure
• MCP tests comprehensively cover the new unified tools (35 tests)
• Batch tests updated to remove fn command and add dataflow command
• Pagination tests verify default limit changes (query: 50→10)

✅ No assertions weakened or removed
✅ Test coverage maintained for new functionality
✅ No suspicious test skips or conditional assertions

The test changes are legitimate updates to match the new consolidated API structure.

Phase 4: Code Quality Review ✅

API Design - EXCELLENT

• Clean consolidation: The query tool with mode: 'deps'|'path' elegantly replaces 3 separate tools
• Backward compatibility: All *Data functions remain exported for programmatic access
• Consistent patterns: Mode-based consolidation follows existing patterns (e.g., execution_flow list mode)

Implementation Quality - SOLID

• MCP handler logic (src/mcp.js:793-820): Proper mode switching with validation
• CLI consolidation (src/cli.js): Clean removal of duplicate commands
• Batch command updates (src/batch.js:34): Correctly maps query → fnDepsData
• Pagination defaults (src/paginate.js:12): Sensible reduction from 50→10 for richer query results

Security & Performance - NO CONCERNS

• No SQL injection vectors introduced
• No command injection in CLI changes
• Proper input validation maintained
• No performance regressions expected

Test Coverage - COMPREHENSIVE

• 35 MCP unit tests cover all tools and schemas
• Integration tests for CLI, batch, and pagination updated appropriately
• Test fixture files maintain proper coverage across changed commands

Root Cause Analysis

Problem Being Solved: Consolidating redundant MCP tools that provide overlapping functionality (query vs fn-deps vs symbol-path). This reduces API surface complexity without losing functionality.

Why This Approach: Mode-based consolidation is the right architectural choice. Having 3 separate tools for dependency chain queries created confusion for AI agents and increased maintenance burden.

Risk Assessment: LOW RISK - This is legitimate architectural cleanup with proper test coverage and backward compatibility preservation.

Critical Concerns

None identified. This is a well-executed refactoring that:

• Maintains all programmatic APIs
• Updates tests comprehensively
• Follows consistent design patterns
• Reduces complexity without losing functionality

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: Excellent consolidation work that reduces API surface while maintaining functionality. Clean implementation, comprehensive test coverage, and proper backward compatibility. The slight deduction is only because this is refactoring rather than new value-add functionality.

Minor suggestions for consideration (non-blocking):

1. Consider documenting the consolidation in a migration guide for users of the MCP tools
2. The pagination default change (50→10) seems reasonable but could be mentioned in release notes

This is exactly the kind of thoughtful refactoring that improves long-term maintainability.

[greptile-apps]

Greptile Summary

This PR successfully consolidates the MCP tool and CLI command surface by merging overlapping functionality into fewer, more versatile tools. The refactor reduces MCP tools from 32 to 29 by introducing mode parameters instead of separate tools.

Key changes:

• query tool: Merges query_function, fn_deps, and symbol_path into a single tool with mode parameter (deps or path)
• execution_flow tool: Absorbs list_entry_points functionality via new list boolean parameter
• dataflow tool: Simplified to edges and impact modes only (removed path mode)
• CLI consolidation: fn and path commands merged into query with --path flag; dataflow --path option removed
• Batch commands: fn command removed, query updated to use fnDepsData, dataflow added
• Pagination defaults: Breaking change - query default reduced from 50 to 10 results

Implementation quality:
All handler logic correctly validates required parameters at runtime (e.g., query path mode requires to argument, execution_flow requires name unless list=true). Tests comprehensively updated across unit and integration suites. Documentation (CLAUDE.md, README.md) fully updated with new syntax. No programmatic API changes - all *Data functions remain exported for backward compatibility.

Confidence Score: 5/5

• Safe to merge - clean refactor with comprehensive test coverage and no logical errors
• This PR demonstrates excellent refactoring practices: (1) all consolidation logic is correct with proper runtime validation, (2) comprehensive test updates across 3 integration and 1 unit test file with 116 total tests passing, (3) documentation completely updated, (4) backward compatibility maintained via continued export of all *Data functions, (5) breaking changes clearly documented (pagination defaults). Code review found no bugs, logic errors, or edge cases.
• No files require special attention - all changes are clean and well-tested

Important Files Changed

Filename	Overview
src/mcp.js	Consolidated MCP tools: merged query_function, fn_deps, symbol_path into query with mode parameter; merged list_entry_points into execution_flow with list parameter; removed dataflow path mode. All handler logic correctly validates required parameters and dispatches to appropriate data functions.
src/cli.js	Merged fn and path commands into query with --path flag. Removed standalone fn and path commands. Removed dataflow --path option. All command dispatching logic correctly routes to appropriate functions based on flags.
src/batch.js	Updated query batch command to use fnDepsData (was queryNameData), removed fn command, added dataflow command. Clean consolidation with correct function mappings.
src/dataflow.js	Removed dataflowPath and dataflowPathData functions. Simplified CLI dispatcher to only handle edges and impact modes. Clean removal with no orphaned code.
src/paginate.js	Updated MCP pagination defaults: query_function: 50 → query: 10, removed fn_deps and list_entry_points entries. Defaults aligned with new tool structure.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[MCP/CLI Tool Consolidation] --> B[query tool]
    A --> C[execution_flow tool]
    A --> D[dataflow tool]
    
    B --> B1[query_function REMOVED]
    B --> B2[fn_deps REMOVED]
    B --> B3[symbol_path REMOVED]
    B1 -.merged into.-> B4[query with mode param]
    B2 -.merged into.-> B4
    B3 -.merged into.-> B4
    B4 --> B5{mode?}
    B5 -->|deps default| B6[fnDepsData]
    B5 -->|path| B7[pathData]
    
    C --> C1[list_entry_points REMOVED]
    C1 -.merged into.-> C2[execution_flow with list param]
    C2 --> C3{list?}
    C3 -->|true| C4[listEntryPointsData]
    C3 -->|false| C5[flowData]
    
    D --> D1[path mode REMOVED]
    D --> D2[edges mode default]
    D --> D3[impact mode]
    D2 --> D4[dataflowData]
    D3 --> D5[dataflowImpactData]
    
    A --> E[CLI Commands]
    E --> E1[fn command REMOVED]
    E --> E2[path command REMOVED]
    E1 -.merged into.-> E3[query command]
    E2 -.merged into.-> E3
    E3 --> E4{--path flag?}
    E4 -->|yes| E5[symbolPath]
    E4 -->|no| E6[fnDeps]
    
    A --> F[Batch Commands]
    F --> F1[fn REMOVED]
    F --> F2[query updated to fnDepsData]
    F --> F3[dataflow ADDED]
    
    style B1 fill:#ffcccc
    style B2 fill:#ffcccc
    style B3 fill:#ffcccc
    style C1 fill:#ffcccc
    style D1 fill:#ffcccc
    style E1 fill:#ffcccc
    style E2 fill:#ffcccc
    style F1 fill:#ffcccc
    style F3 fill:#ccffcc
    style B4 fill:#ccffcc
    style C2 fill:#ccffcc

Loading

_{Last reviewed commit: bbd60db}

[greptile-apps]

_{11 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}