Summary

Consolidate 18 core tools into 10 CQRS-aligned tools for better MCP client compatibility. Core tools require more careful consolidation due to diverse functionality.

Current State (18 tools)

READ Operations (15 tools)

WRITE Operations (3 tools)

Target State (10 tools)

browse_projects (Query)

Consolidates project discovery:

{
  action: "search" | "list" | "get",
  
  // For "search" action
  search?: string,
  visibility?: "public" | "internal" | "private",
  with_programming_language?: string,
  topics?: string[],
  order_by?: "id" | "name" | "path" | "created_at" | "updated_at" | "last_activity_at" | "similarity",
  sort?: "asc" | "desc",
  
  // For "get" action
  projectId?: string,
  
  // For "list" action
  owned?: boolean,
  membership?: boolean,
  starred?: boolean,
  
  // Pagination
  per_page?: number,
  page?: number
}

browse_namespaces (Query)

Consolidates namespace operations:

{
  action: "list" | "get" | "verify",
  
  // For "list" action
  search?: string,
  owned_only?: boolean,
  
  // For "get" and "verify"
  namespaceId?: string,       // ID or URL-encoded path
  
  // Pagination
  per_page?: number,
  page?: number
}

browse_commits (Query)

Consolidates commit history:

{
  action: "list" | "get" | "diff",
  
  projectId: string,
  
  // For "list" action
  ref_name?: string,
  since?: string,
  until?: string,
  path?: string,
  author?: string,
  all?: boolean,
  first_parent?: boolean,
  
  // For "get" and "diff"
  sha?: string,
  
  // For "get" action
  stats?: boolean,
  
  // Pagination
  per_page?: number,
  page?: number
}

browse_events (Query)

Consolidates activity events:

{
  action: "user" | "project",
  
  // For "project" action
  projectId?: string,
  
  // Common filters
  target_type?: "issue" | "milestone" | "merge_request" | "note" | "project" | "snippet" | "user",
  before?: string,            // YYYY-MM-DD
  after?: string,             // YYYY-MM-DD
  
  // Pagination
  per_page?: number,
  page?: number
}

get_users (Query - Keep as-is)

Already well-designed with smart search capabilities. No consolidation needed.

list_project_members (Query - Keep as-is)

Different scope than namespaces/projects. Keep separate for clarity.

list_group_iterations (Query - Keep as-is)

Premium feature with specific use case. Keep separate.

download_attachment (Query - Keep as-is)

Unique binary download operation. Keep separate.

manage_repository (Command)

Consolidates repository creation:

{
  action: "create" | "fork",
  
  // For "create" action
  name?: string,
  path?: string,
  namespace_id?: number,
  description?: string,
  visibility?: "public" | "internal" | "private",
  initialize_with_readme?: boolean,
  default_branch?: string,
  
  // For "fork" action
  projectId?: string,         // Project to fork
  namespace_path?: string,    // Target namespace
  name?: string,              // New name (optional)
  path?: string               // New path (optional)
}

create_branch (Command - Keep as-is)

Git operation with distinct purpose. Keep separate.

Consolidation Summary

Implementation Tasks

• Create new browse_projects handler
• Create new browse_namespaces handler
• Create new browse_commits handler
• Create new browse_events handler
• Create new manage_repository handler
• Update Zod schemas with discriminated unions
• Update registry to export new tool names
• Update read-only tools list
• Remove old handlers after migration
• Update unit tests
• Update integration tests

Breaking Changes

Read-Only Mode

Why Keep Some Tools Separate?

1. get_users - Complex smart search with transliteration, multi-phase fallback
2. list_project_members - Different scope (team vs organizational)
3. list_group_iterations - Premium tier, specific agile use case
4. download_attachment - Binary operation, different response type
5. create_branch - Distinct git operation, different from repo management

Testing Requirements

• Unit tests for all discriminated union schemas
• Test project search/list/get
• Test namespace operations
• Test commit history and diffs
• Test event listing for user and project
• Test repository create/fork
• Test read-only mode
• Integration tests for all operations

Acceptance Criteria

• Total tools reduced from 18 to 10
• All existing functionality preserved
• Kept tools unchanged (backward compatible)
• Read-only mode correctly gates write operations
• Clear error messages for invalid combinations