# YARD MCP Server Implementation Plan

This document outlines the implementation plan for building the YARD MCP server, based on the pragmatic engineering review in `notes/brainstorm.md`.

## 1. Project Goal

To create a Model Context Protocol (MCP) server that provides AI agents with real-time access to YARD documentation for a local Ruby project and its dependencies. The key feature is library-scoped search with on-demand documentation building.

## 2. Core Architecture: Single Registry with Library-Scoped Search

The architecture is based on a single YARD registry with library-scoped search capabilities, similar to `yard server -g -G`.

*   **Single Registry:** Uses YARD's global registry with on-demand loading of specific libraries
*   **Library Sources:** Tracks gem sources (bundler vs installed vs project) for intelligent filtering
*   **On-Demand Building:** Builds documentation only when needed using YARD's CLI tools
*   **Library-Scoped Search:** Allows agents to specify which library to search (#project, #stdlib, gem_name)

This simplified approach provides better performance and easier maintenance while supporting comprehensive gem documentation access.

## 3. Implementation Status

### Phase 1: Core MCP Server (✅ COMPLETED)

**Objective:** Establish the basic server infrastructure and MCP protocol integration.

*   **Completed Tasks:**
    1.  Set up the main application structure (`lib`, `bin`) with `bundler`, `fast-mcp` and `yard` dependencies.
    2.  Implement the basic MCP server using `fast-mcp 1.5.0` with proper transport handling.
    3.  Create the unified `Registry` using YARD's LibraryVersion system to manage all libraries.
    4.  Implement library source tracking (bundler vs installed vs project gems).
    5.  Create the `bin/yard-mcp` executable to start the server.
    6.  Set up comprehensive logging with structured information.

*   **Outcome:** A functional MCP server that can manage documentation for 400+ libraries including Rails, RSpec, etc.

### Phase 2: Library-Scoped Search (✅ COMPLETED)

**Objective:** Implement library-specific documentation access with on-demand building.

*   **Completed Tasks:**
    1.  Create library-scoped search with special namespaces (`#project`, `#stdlib`).
    2.  Implement on-demand documentation building using YARD CLI tools.
    3.  Add build status tracking (ready/building/failed) for gem libraries.
    4.  Integrate thread-safe operations using `concurrent-ruby` for serialized gem building.
    5.  Update `lookup_object` tool to support library parameter for scoped searches.

*   **Outcome:** The server provides targeted documentation access with intelligent library filtering.

### Phase 3: Core MCP Tools (✅ COMPLETED)

**Objective:** Implement essential MCP tools for effective documentation access.

*   **Completed Tasks:**
    1.  Enhanced `lookup_object` with detailed, LLM-friendly formatted output (JSON with docstrings, signatures, examples, etc.).
    2.  Implemented `list_libraries` tool to show available documentation libraries with filtering options.
    3.  Added `health_check` tool for server status monitoring.
    4.  Fixed MCP tool API consistency for fast-mcp 1.5.0 compatibility.
    5.  Implemented comprehensive error handling for failed builds and missing objects.

*   **Outcome:** A highly useful tool for AI agents to look up, search, and explore project documentation with library-specific targeting.

### Phase 4: Advanced Tools & Hardening (🔄 NEXT)

**Objective:** Add more powerful tools and make the server more robust.

*   **Planned Tasks:**
    1.  Implement advanced navigation tools like `browse_namespace` and `get_examples`.
    2.  Add full-text search capabilities across documentation.
    3.  Implement Ruby standard library (`#stdlib`) documentation support.
    4.  Add live file watching for project changes with incremental rebuilds.
    5.  Improve error handling and add more specific error types.
    6.  Add command-line options for configuration and different run modes.

*   **Outcome:** A feature-rich and configurable server that is reliable in daily use.

### Phase 5: Performance & Usability (📋 FUTURE)

**Objective:** Optimize performance and improve the overall user experience.

*   **Planned Tasks:**
    1.  Implement a caching layer for frequently accessed objects to improve lookup performance.
    2.  Profile and optimize the documentation rebuild process.
    3.  Add metrics to monitor performance (e.g., request latency, rebuild times).
    4.  Improve logging with structured, actionable information.
    5.  Write clear user documentation on how to set up and use the server.
    6.  Add configuration file support for customizing behavior.

*   **Outcome:** A fast, reliable, and easy-to-use development tool.

## 4. Current Usage

### Available MCP Tools

1. **`lookup_object`** - Look up Ruby object documentation by path
   - Parameters: `object_path` (required), `library` (optional), `include_source`, `format`
   - Supports library-scoped searches: `#project`, `#stdlib`, or gem name
   - Returns structured documentation with docstrings, signatures, examples

2. **`list_libraries`** - List available documentation libraries
   - Parameters: `include_gems` (default: true)
   - When `false`: shows only Gemfile libraries
   - When `true`: shows all installed + Gemfile libraries
   - Returns library names, versions, types, and build status

3. **`health_check`** - Check server health and status
   - Returns registry statistics, object counts, and system status

### Example Usage

```bash
# Start the server
bin/yard-mcp

# Test with MCP inspector
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "lookup_object", "arguments": {"object_path": "String#gsub", "library": "#project"}}}' | bin/yard-mcp
```

## 5. Testing Strategy

*   **Manual Testing:** Currently tested manually using MCP inspector and direct JSON-RPC calls.
*   **Integration Testing:** Full server lifecycle testing with real gem documentation.
*   **Performance Testing:** Benchmarked with 400+ libraries including Rails ecosystem.
*   **Future:** Automated unit tests for individual tools and registry components.

## 6. Future Enhancements

*   HTTP transport for web-based integrations.
*   Integration with code editors (VS Code, etc.).
*   Support for custom documentation formatters.
*   Documentation quality analysis and coverage reports.
*   A web UI for browsing documentation.
*   Automated testing suite with CI/CD integration.