Action MCP Example 🚀

A simple Ruby on Rails application demonstrating how to integrate and use the ActionMCP gem. The gem source code can be found on GitHub at https://github.com/seuros/mcp.

This application showcases how to define and use MCP components within a Rails project.

---

Requirements

• Ruby (see .ruby-version for recommended version)
• PostgreSQL (or Docker)

---

Getting Started

1. Clone and Setup

git clone https://github.com/seuros/mcp_rails_template.git
cd mcp_rails_template
bin/setup

2. Environment Configuration

Copy the provided .env.example file:

cp .env.example .env

Edit .env and fill in necessary values according to your setup (especially any required API keys for tools like fetch_weather_by_location_tool).

3. Database Setup

You can quickly spin up a temporary PostgreSQL instance using Docker:

make up

This will start PostgreSQL on port 5466.

Alternatively, configure your own PostgreSQL database by editing config/database.yml.

4. Run the Application

Launch the Rails server:

bin/rails s

The app will be available at http://localhost:3002.

---

ActionMCP Server

ActionMCP runs as a standalone server on port 62770 (via mcp.ru). Nginx proxies /mcp requests to this server.

Client → nginx:8080/mcp → ActionMCP:62770

---

Authentication

This application uses JWT-based authentication via the ApplicationGateway class.

Test Users (from fixtures)

Email	Password	Role
test@example.com	password123	Test User
admin@example.com	password123	Admin User

Loading Fixtures

bin/rails db:fixtures:load FIXTURES=users

Generating a JWT Token

# In Rails console
user = User.find_by(email: 'test@example.com')
token = user.generate_jwt(expires_in: 10.years)  # Long-lived for demo

MCP Client Configuration

A .mcp.json file is provided with a pre-configured long-lived token:

{
  "mcpServers": {
    "mcp_rails_template": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Or test manually with curl:

curl -H "Authorization: Bearer <token>" http://localhost:8080/mcp

Gateway Configuration

The gateway is configured in config/mcp.yml:

development:
  authentication: ["jwt"]
  gateway_class: "ApplicationGateway"

Accessing User in Tools

class MyTool < ApplicationMCPTool
  def perform
    render text: "Hello #{current_user.name}!"
  end
end

---

MCP Components (app/mcp/)

This application includes several examples of ActionMCP components:

Prompts (app/mcp/prompts/)

• epic_adventure_prompt.rb: Generates a short, narrative adventure story based on a provided hero name and adventure type (fantasy, sci-fi, mystery). It can optionally include a placeholder image data string.

Resource Templates (app/mcp/resource_templates/)

• gemfile_template.rb: Provides access to the project's Gemfile dependencies as a JSON resource. It uses Bundler to fetch gems based on the specified environment (production, test, development, or default). The resource URI follows the pattern gemfile://{environment}.

Tools (app/mcp/tools/)

Tools define specific actions that a language model can request to be executed.

• dependency_info_tool.rb: Retrieves dependency information using Bundler from the Gemfile and Gemfile.lock. It also checks for a .gemspec file for runtime dependencies. It outputs separate JSON resources for production, test, and runtime dependencies.
• fetch_weather_by_location_tool.rb: Fetches weather forecast data from the Open-Meteo API (https://api.open-meteo.com) based on provided latitude and longitude coordinates. It returns the raw JSON response from the API.
• rubocop_tool.rb: Analyzes a provided Ruby code snippet using the RuboCop gem's API. It reports any detected style or code quality offenses, including the rule name, message, line, and column number.
• ruby_code_analyzer_tool.rb: Performs basic static analysis of Ruby code within the project directory. It indexes classes, modules, and methods by parsing .rb files. It can be queried to list all found classes, modules, or methods, or to get details (including source snippets) for a specific class/module (constant) or method (method_details).

---

Usage

To test and inspect MCP functionality interactively, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector --url http://localhost:8080/mcp

Make sure Docker is running (docker compose up) before executing the inspector command.

---

Contributing

Feel free to contribute! Open issues or submit pull requests to help improve this example.

---

Happy Coding! ✨🚀