MCP工具

Requirements

• Ruby: 3.4.8+ or 4.0.0+
• Rails: 8.1.1+
• Database: PostgreSQL, MySQL, or SQLite3

ActionMCP is tested against Ruby 3.4.8 and 4.0.0 with Rails 8.1.1+.

Install dependencies

bundle install

IMPORTANT: Use ActionMCP.server — it initializes required subsystems.

Installation

To start using ActionMCP, add it to your project:

```bash

Getting Started & Setup

• Installation & Configuration - Initial setup, database migrations, and basic configuration
• Authentication with Gateway - User authentication and authorization patterns

Installing ActionMCP

ActionMCP includes generators to help you set up your project quickly. The install generator creates all necessary base classes and configuration files:

```bash

Install ActionMCP with base classes and configuration

bin/rails generate action_mcp:install ```

This will create: - app/mcp/prompts/application_mcp_prompt.rb - Base prompt class - app/mcp/tools/application_mcp_tool.rb - Base tool class - app/mcp/resource_templates/application_mcp_res_template.rb - Base resource template class - app/mcp/application_gateway.rb - Gateway for authentication - config/mcp.yml - Configuration file with example settings for all environments - mcp/config.ru - Standalone Rack server configuration - bin/mcp - Server binstub (prefers Falcon, falls back to Puma)

Note: Authentication and authorization are not included. You are responsible for securing the endpoint.

Production Deployment of MCPS0

In production, MCPS0 (the MCP server) is a standard Rack application. You can run it using any Rack-compatible server (such as Puma, Unicorn, or Passenger).

For best performance and concurrency, it is highly recommended to use a modern, synchronous server like Falcon. Falcon is optimized for streaming and concurrent workloads, making it ideal for MCP servers. You can still use Puma, Unicorn, or Passenger, but Falcon will generally provide superior throughput and responsiveness for real-time and streaming use cases.

You have several main options for exposing the server:

Deployment

• Use Falcon for optimal performance with streaming workloads
• Deploy on dedicated ports or Unix sockets
• Use reverse proxies (Nginx, Apache) for SSL termination
• Implement health checks for your MCP endpoints
• Use mcp_vanilla.ru to avoid middleware conflicts

Use Cases

Profiles are particularly useful for:

1. Multi-tenant applications: Use different profiles for different customer tiers with Dorp or other gems
2. Access control: Create profiles for different user roles (admin, staff, public)
3. Performance optimization: Use a minimal profile for high-traffic endpoints
4. Testing environments: Use specific test profiles in your test environment
5. Progressive enhancement: Start with a minimal profile and gradually add capabilities

By leveraging profiles, you can maintain a single ActionMCP codebase while providing tailored MCP capabilities for different contexts.

Client Usage

ActionMCP includes a client for connecting to remote MCP servers. The client handles session management, protocol negotiation, and provides a simple API for interacting with MCP servers.

For comprehensive client documentation, including examples, session management, transport configuration, and API usage, see CLIENTUSAGE.md.

Generate base classes and configuration

bin/rails generate action_mcp:install

Advanced Configuration

• Session Storage - Volatile vs ActiveRecord vs custom session stores
• Thread Pool Management - Performance tuning and graceful shutdown
• Profiles System - Multi-tenant capability filtering
• Production Deployment - Falcon, Unix sockets, and reverse proxy setup

Configuration

ActionMCP is configured via config.action_mcp in your Rails application.

By default, the name is set to your application's name and the version defaults to "0.0.1" unless your app has a version file.

You can override these settings in your configuration (e.g., in config/application.rb):

module Tron
  class Application < Rails::Application
    config.action_mcp.name = "Friendly MCP (Master Control Program)"  # defaults to Rails.application.name
    config.action_mcp.version = "1.2.3"                               # defaults to "0.0.1"
    config.action_mcp.logging_enabled = true                          # defaults to true
    config.action_mcp.logging_level = :info                           # defaults to :info, can be :debug, :info, :warn, :error, :fatal

    # Server instructions - helps LLMs understand the server's purpose
    config.action_mcp.server_instructions = [
      "Use this server to access and control Tron system programs",
      "Helpful for managing system processes and user data"
    ]
  end
end

For dynamic versioning, consider adding the rails_app_version gem.

Configuration

You can configure the session store type in your Rails configuration or config/mcp.yml:

```ruby

config/application.rb or environment files

Rails.application.configure do config.action_mcp.session_store_type = :active_record # or :volatile end

Or in `config/mcp.yml`:

The session store is automatically selected based on configuration

Thread Pool Configuration

You can configure the thread pool in your config/mcp.yml:

production:
  # Thread pool configuration
  min_threads: 10    # Minimum number of threads to keep in the pool
  max_threads: 20    # Maximum number of threads the pool can grow to
  max_queue: 500     # Maximum number of tasks that can be queued

The thread pool will automatically: - Start with min_threads threads - Scale up to max_threads as needed - Queue tasks up to max_queue limit - Use caller's thread if queue is full (fallback policy)

1. Create `mcp/config.ru`

The install generator (rails generate action_mcp:install) creates this automatically. If you need to create it manually:

```ruby

Load the full Rails environment to access models, DB, Redis, etc.

require_relative "../config/environment"

$stdout.sync = true

Show configuration and statistics

bundle exec rails action_mcp:info bundle exec rails action_mcp:stats

Show profile configuration

bundle exec rails action_mcp:show_profile[profile_name] ```

Configuring Profiles

Profiles are configured via a config/mcp.yml file in your Rails application. If this file doesn't exist, ActionMCP will use default settings from the gem.

Example configuration:

default:
  tools:
    - all  # Include all tools
  prompts:
    - all  # Include all prompts
  resources:
    - all  # Include all resources
  options:
    list_changed: false
    logging_enabled: true
    logging_level: info
    resources_subscribe: false

api_only:
  tools:
    - calculator
    - weather
  prompts: []  # No prompts for API
  resources:
    - user_profile
  options:
    list_changed: false
    logging_level: warn

admin:
  tools:
    - all
  options:
    logging_level: debug
    list_changed: true
    resources_subscribe: true

Each profile can specify: - tools: Array of tool names to include (use all to include all tools) - prompts: Array of prompt names to include (use all to include all prompts) - resources: Array of resource names to include (use all to include all resources) - options: Additional configuration options: - list_changed: Whether to send change notifications - logging_enabled: Whether to enable logging - logging_level: The logging level to use - resources_subscribe: Whether to enable resource subscriptions

List all available profiles with their configurations

bin/rails action_mcp:list_profiles

Core Components

ActionMCP provides three core abstractions to streamline MCP server development:

Component Development

• 📋 TOOLS.MD - Complete guide to developing MCP tools
• Generator usage and best practices
• Property definitions, validation, and consent management
• Output schemas for structured responses
• Error handling, testing, and security considerations
• Advanced features like additional properties and authentication context

• 📝 PROMPTS.MD - Prompt template development guide
• Creating reusable prompt templates
• Multi-step conversations and mixed content types
• Argument validation and prompt chaining

• 🔗 RESOURCE_TEMPLATES.md - Resource template implementation
• URI template patterns and parameter extraction
• Dynamic resource resolution and collections
• Callbacks and validation patterns

Client & Integration

• 🔌 CLIENTUSAGE.MD - Complete client implementation guide
• Session management and resumability
• Transport configuration and connection handling
• Tool, prompt, and resource collections
• Production deployment patterns
• 🔐 GATEWAY.md - Authentication gateway guide
• Implementing ApplicationGateway
• Identifier handling via ActionMCP::Current
• Auth patterns, error handling, and hardening tips

Accessing Current User in Components

Once authenticated, the current user (and other identifiers) are available in your tools, prompts, and resource templates:

class MyTool < ApplicationMCPTool
  def perform
    # Access the authenticated user
    if current_user
      render text: "Hello, #{current_user.name}!"
    else
      render text: "Hi Stranger! It's been a while "
    end
  end
end

List all MCP components

bundle exec rails action_mcp:list

List specific component types

bundle exec rails action_mcp:list_tools bundle exec rails action_mcp:list_prompts bundle exec rails action_mcp:list_resources bundle exec rails action_mcp:list_profiles

Troubleshooting & Production

• Error Handling - JSON-RPC error codes and debugging
• Production Considerations - Security, performance, and monitoring
• Middleware Conflicts - Using mcp_vanilla.ru for production

💡 Pro Tip: Start with the component-specific guides (TOOLS.MD, PROMPTS.MD, RESOURCE_TEMPLATES.md) for hands-on development, then reference the Hitchhiker's Guide for protocol details and CLIENTUSAGE.MD for integration patterns.

Error Handling and Troubleshooting

ActionMCP provides comprehensive error handling following the JSON-RPC 2.0 specification: