YARD MCP Server#

A Model Context Protocol (MCP) server that provides AI agents with real-time access to YARD documentation for Ruby projects and their dependencies. Built specifically for integration with Claude Code and other MCP-compatible tools.

Features#

📚 Comprehensive Documentation Access: Browse documentation for your project, Ruby standard library, and 400+ gem dependencies
🎯 Library-Scoped Search: Target specific libraries for precise documentation lookup
⚡ On-Demand Building: Documentation is built only when needed for optimal performance
🔍 Smart Gem Filtering: Distinguish between bundler dependencies and all installed gems
🤖 MCP Integration: Seamlessly works with Claude Code and other MCP-compatible tools

Quick Start#

Prerequisites#

Ruby 3.0+
Bundler
Claude Code (for MCP integration)

Installation#

Add to your project's Gemfile in the development group:

group :development do
  gem 'yard-mcp'
end

Then run:

bundle install
bundle exec yard-mcp

Claude Code Integration#

The repository includes MCP configuration for Claude Code. Simply open this project in Claude Code and the MCP server will be automatically available.

To add it to any Ruby project with yard-mcp in the Gemfile:

claude mcp add --scope project yard-mcp bundle exec yard-mcp

Example Claude Session#

> I'm having trouble with a call; what're the arguments to secure random base36?

⏺ I'll help you find the arguments for SecureRandom.base36. Let me look up the Ruby documentation for this method.

⏺ yard-mcp - lookup_object (MCP)(object_path: "SecureRandom.base36", library: "#stdlib")
  ⎿ {error: "object_not_found", message: "Object 'SecureRandom.base36' not found in documentation", suggestions: ["Try searching in library 'activesupport' - it may extend core classes", "Try searching
     in library 'rails' - it may extend core classes"]}


⏺ Let me check if it's in the Rails ActiveSupport library:

⏺ yard-mcp - lookup_object (MCP)(object_path: "SecureRandom.base36", library: "activesupport")
  ⎿ {object_path: "SecureRandom.base36", name: "base36", type: "method", namespace: "SecureRandom", docstring: "", source_location: {file: "lib/active_support/core_ext/securerandom.rb", line: 45}, visi
    bility: "public", signature: "def base36(n = 16)", scope: "class", parameters: [{name: "n", default: "16", types: [], description: nil}], return_type: nil, examples: [], tags: {}, related_objects:
    ["SecureRandom.base58"]}


⏺ SecureRandom.base36(n = 16) takes one optional parameter:
  - n (default: 16) - the number of random characters to generate

  Example: SecureRandom.base36 returns 16 characters, SecureRandom.base36(8) returns 8 characters.

> sweet, thank you -- now can you tell me what methods are available on a redlock client?

⏺ I'll help you find the methods available on a Redlock client. Let me search for Redlock documentation.

⏺ yard-mcp - lookup_object (MCP)(object_path: "Redlock")
  ⎿  {error: "object_not_found", message: "Object 'Redlock' not found in documentation", suggestions: []}

⏺ Let me check what gems are available in your project to see if we have Redlock:
  ⎿ {libraries: [{name: "#project", version: "0.1.0", type: "project", status: "loaded", ready: true, description: "Current project documentation"}, {name: "#stdlib", version: "3.4.4", type: "stdlib",
    status: "available", ready: true, description: "Ruby standard library documentation"}, {name: "StreetAddress", version: "1.0.6", type: "bundler_gem", status: "available", ready: true, description:
    "StreetAddress gem documentation"}, {name: "actioncable", version: "8.0.2", type: "bundler_gem", status: "available", ready: true, description: "actioncable gem documentation"}, {name: "actionmailb
    … +225 lines (ctrl+r to expand)


⏺ I can see you have the redlock gem in your project. Let me look up the Redlock client methods:

⏺ yard-mcp - lookup_object (MCP)(object_path: "Redlock::Client", library: "redlock")
  ⎿ {object_path: "Redlock::Client", name: "Client", type: "class", namespace: "Redlock", docstring: "", source_location: {file: "lib/redlock/client.rb", line: 17}, visibility: "public", superclass: "O
    bject", mixins: [], constants: ["Redlock::Client::DEFAULT_REDIS_HOST", "Redlock::Client::DEFAULT_REDIS_PORT", "Redlock::Client::DEFAULT_REDIS_URLS", "Redlock::Client::DEFAULT_REDIS_TIMEOUT", "Redlo
    ck::Client::DEFAULT_RETRY_COUNT", "Redlock::Client::DEFAULT_RETRY_DELAY", "Redlock::Client::DEFAULT_RETRY_JITTER", "Redlock::Client::CLOCK_DRIFT_FACTOR"], instance_methods: ["Redlock::Client#initia
    … +4 lines (ctrl+r to expand)




⏺ The main methods available on a Redlock client are:

  Primary methods:
  - lock(resource, ttl, options = {}) - Acquire a lock
  - unlock(lock_info) - Release a lock
  - lock!(resource, ttl, options = {}) - Acquire a lock, raise on failure

  Lock status methods:
  - locked?(resource) - Check if a resource is locked
  - valid_lock?(lock_info) - Check if lock info is valid
  - get_remaining_ttl_for_lock(lock_info) - Get remaining TTL for a lock
  - get_remaining_ttl_for_resource(resource) - Get remaining TTL for a resource

  Testing:
  - testing_mode= - Enable/disable testing mode

  The most commonly used are lock, unlock, and lock!.

Usage#

Available MCP Tools#

1. `lookup_object` - Look up Ruby object documentation#

Find detailed documentation for any Ruby class, module, method, or constant:

{
  "object_path": "ActiveRecord::Base",
  "library": "activerecord",
  "include_source": false,
  "format": "structured"
}

Parameters:

object_path (required): Full path to the Ruby object (e.g., String#gsub, ActiveRecord::Base)
library (optional): Specific library to search in (#project, #stdlib, or gem name)
include_source (optional): Include source code in response
format (optional): Output format (structured, markdown, or text)

Library-Scoped Search:

#project - Search only in your current project code
#stdlib - Search only in Ruby standard library
gem_name - Search only in specific gem (e.g., rails, rspec)

2. `list_libraries` - List available documentation libraries#

See all available documentation libraries with their status:

{
  "include_gems": true
}

Parameters:

include_gems (optional):
- false - Show only Gemfile dependencies
- true - Show all installed gems + Gemfile dependencies (default)

3. `health_check` - Check server status#

Get server health information and registry statistics.

Example Usage in Claude Code#

Once connected, you can use the MCP tools directly in Claude Code:

Can you look up the documentation for ActiveRecord::Base?

Show me all the available gem libraries I can search.

What methods are available in the String class from stdlib?

Architecture#

Single Registry with Library-Scoped Search#

The server uses YARD's global registry with intelligent library management:

Library Sources: Tracks gem sources (bundler vs installed vs project)
On-Demand Building: Builds documentation only when needed using YARD CLI tools
Thread-Safe Operations: Uses concurrent-ruby for serialized gem building
Build Status Tracking: Monitors ready/building/failed states for each library

Performance#

413+ Libraries Available: Supports Rails ecosystem and beyond
Selective Loading: Only loads documentation when requested
Efficient Caching: YARD handles caching of built documentation
Fast Startup: Registry initialization in ~100ms

Development#

Project Structure#

├── bin/yard-mcp              # Executable server script
├── lib/
│   ├── yard_mcp.rb           # Main module
│   ├── yard_mcp/
│   │   ├── config.rb         # Configuration management
│   │   ├── registry.rb       # Documentation registry
│   │   ├── server.rb         # MCP server implementation
│   │   └── tools/            # MCP tools
│   │       ├── lookup_tool.rb
│   │       ├── list_libraries_tool.rb
│   │       └── health_check_tool.rb
├── .mcp.json                 # Claude Code MCP configuration
└── plan.md                   # Implementation roadmap

Running Tests#

Currently tested manually with MCP inspector and direct JSON-RPC calls. Future automated testing is planned.

Contributing#

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -am 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Configuration#

Environment Variables#

YARD_MCP_LOG_LEVEL - Set logging level (debug, info, warn, error)
YARD_MCP_PROJECT_ROOT - Override project root directory

Customization#

The server automatically detects:

Project source files in lib/, app/, etc.
Bundler dependencies from Gemfile.lock
All installed gems via RubyGems

Troubleshooting#

Common Issues#

Server won't start:

Ensure Ruby 3.0+ and all dependencies are installed
Check that the project has a valid Gemfile.lock

Documentation not found:

Some gems may need documentation built on-demand
Check the library status with list_libraries
Complex gems like RuboCop may fail to build - this is expected

Performance issues:

Documentation building happens on first access and may take time
Subsequent access to the same gems will be fast
Use library-scoped search to avoid unnecessary loading

Debug Mode#

Start the server with debug logging:

YARD_MCP_LOG_LEVEL=debug bin/yard-mcp

Roadmap#

Completed ✅#

Core MCP server with STDIO transport
Library-scoped search with on-demand building
Comprehensive gem documentation access
Claude Code integration
Build status tracking

Next Phase 🔄#

Ruby standard library (#stdlib) documentation support
Full-text search across documentation
Live file watching for project changes
Advanced navigation tools (browse_namespace, get_examples)

Future 📋#

Performance optimizations and caching
Automated testing suite
Configuration file support
HTTP transport option
VS Code extension

License#

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments#

Built with fast-mcp for MCP protocol support
Uses YARD for Ruby documentation parsing
Designed for Claude Code integration

🤖 This project was developed with assistance from Claude Code

Clone this repository