[STORY] MCP Health Tool

[jsbattig]

Part of: #53

Story: MCP Health Tool

Feature: Server API Integration

Priority: P0

Overview

As an AI assistant using CIDX via MCP
I want an MCP tool to check HNSW index health
So that I can verify index integrity and provide health status to users

Context

MCP (Model Context Protocol) tools allow AI assistants to interact with CIDX. The health check tool reuses the REST implementation logic, providing consistent behavior across interfaces.

Acceptance Criteria

Feature: MCP Health Tool

  Scenario: Health check via MCP on healthy index
    Given an MCP session is established
    And a repository with healthy HNSW index is accessible
    When the check_hnsw_health tool is called with repository_alias
    Then a successful result is returned
    And result contains HealthCheckResult with valid=true
    And all integrity metrics are included

  Scenario: Health check via MCP on unhealthy index
    Given an MCP session is established
    And a repository with corrupted HNSW index is accessible
    When the check_hnsw_health tool is called
    Then a successful result is returned (tool works, index unhealthy)
    And result contains HealthCheckResult with valid=false
    And errors array contains specific issues

  Scenario: Health check via MCP on unknown repository
    Given an MCP session is established
    When check_hnsw_health is called with unknown repository_alias
    Then an error result is returned
    And error indicates repository not found

  Scenario: Health check via MCP with force refresh
    Given a cached health check result exists
    When check_hnsw_health is called with force_refresh=true
    Then cache is bypassed
    And fresh integrity check is performed
    And from_cache=false in result

  Scenario: Health check tool appears in MCP tool listing
    Given an MCP session is established
    When tools/list is called
    Then check_hnsw_health appears in the tool list
    And tool description explains its purpose
    And input schema documents parameters

  Scenario: Health check tool permissions
    Given an MCP session with limited permissions
    When check_hnsw_health is called
    Then appropriate permission check is performed
    And access denied if user lacks repository read permission

Technical Requirements

Tool Definition

name: check_hnsw_health
description: Check HNSW index health and integrity for a repository
category: system
required_permission: query_repos

inputSchema:
  type: object
  required:
    - repository_alias
  properties:
    repository_alias:
      type: string
      description: Repository alias to check health for
    force_refresh:
      type: boolean
      description: Bypass cache and perform fresh check
      default: false

Handler Implementation

Pseudocode:

async def handle_check_hnsw_health(
    params: CheckHNSWHealthParams,
    context: MCPContext
) -> MCPToolResult:
    # Validate permissions
    if not context.user.has_permission('query_repos'):
        return MCPToolResult.error("Permission denied")

    # Reuse REST logic
    try:
        result = await get_repository_health(
            repo_alias=params.repository_alias,
            force_refresh=params.force_refresh,
            health_service=context.health_service,
            repo_service=context.repo_service,
            executor=context.executor
        )

        return MCPToolResult.success(result.model_dump())

    except RepositoryNotFound:
        return MCPToolResult.error(f"Repository '{params.repository_alias}' not found")

    except Exception as e:
        return MCPToolResult.error(f"Health check failed: {str(e)}")

Tool Registry Entry

Pseudocode:

TOOL_REGISTRY['check_hnsw_health'] = ToolDefinition(
    name='check_hnsw_health',
    description='Check HNSW index health and integrity for a repository',
    category='system',
    required_permission='query_repos',
    handler=handle_check_hnsw_health,
    input_schema=CheckHNSWHealthInputSchema,
    output_schema=HealthCheckResult
)

Tool Documentation

Create markdown file at src/code_indexer/server/mcp/tool_docs/system/check_hnsw_health.md:

---
name: check_hnsw_health
category: system
required_permission: query_repos
tl_dr: Check HNSW index health and integrity for a repository.
quick_reference: true
---

TL;DR: Verify HNSW index integrity after crashes, restores, or migrations.

WHEN TO USE: After system crashes, index restores, or migrations.
Verify index health before performing queries on potentially corrupted data.

WHEN NOT TO USE: Regular status checks (use get_repository_status instead).

PARAMETERS:
- repository_alias (required): Repository to check
- force_refresh (optional): Bypass cache, default false

RETURNS: HealthCheckResult with valid flag, integrity metrics, and any errors.

EXAMPLE: check_hnsw_health(repository_alias='my-repo-global')
Returns: {valid: true, element_count: 46000, connections_checked: 1200000, ...}

Integration with REST Layer

The MCP handler should reuse the REST endpoint's core logic to ensure consistency:

MCP Tool Handler
       │
       ▼
REST Endpoint Logic (reused)
       │
       ▼
HNSWHealthService
       │
       ▼
Custom hnswlib check_integrity()

Implementation Status

Task	Status	Notes
Tool definition	❌	Input/output schemas
Handler implementation	❌	Reuse REST logic
Tool registry entry	❌	Add to TOOL_REGISTRY
Permission check	❌	query_repos permission
Tool documentation	❌	Markdown in tool_docs/
Error handling	❌	MCP error responses

Testing Requirements

Unit Tests

• Tool handler returns correct result for healthy index
• Tool handler returns correct result for unhealthy index
• Unknown repository returns error
• Permission denied for unauthorized user
• force_refresh parameter works
• Tool appears in tools/list

Integration Tests

• Full MCP session with health check tool
• Permission enforcement
• Concurrent tool calls
• Error propagation

MCP Protocol Tests

• Request/response format compliance
• Schema validation
• Error response format

Definition of Done

• MCP tool registered in TOOL_REGISTRY
• Handler reuses REST endpoint logic
• Input/output schemas defined
• Permission check implemented
• Tool documentation markdown created
• Unit tests for handler
• Integration tests with MCP session
• Tool appears correctly in tools/list

Conversation References

• Interface requirement: "MCP: Health check tool (reusing REST implementation)"
• Permission model: Implied from existing MCP tool patterns (query_repos for read operations)
• Tool documentation: Following existing src/code_indexer/server/mcp/tool_docs/ convention