feat: Allow a base path to be set (#179) (#180)

Author: dark-panda

README.md

@@ -763,7 +763,7 @@ This ensures all thread pools are properly terminated and tasks are completed.
 
 ## Engine and Mounting
 
-**ActionMCP** runs as a standalone Rack application. **Do not attempt to mount it in your application's `routes.rb`**—it is not designed to be mounted as an engine at a custom path. When you use `run ActionMCP::Engine` in your `mcp.ru`, the MCP endpoint is always available at the root path (`/`).
+**ActionMCP** runs as a standalone Rack application. **Do not attempt to mount it in your application's `routes.rb`**—it is not designed to be mounted as an engine at a custom path. When you use `run ActionMCP::Engine` in your `mcp.ru`, the MCP endpoint is available at the root path (`/`) by default and can be configured via `config.action_mcp.base_path`.
 
 ### Installing ActionMCP
 
@@ -916,7 +916,7 @@ In production, **MCPS0** (the MCP server) is a standard Rack application. You ca
 
 > **For best performance and concurrency, it is highly recommended to use a modern, synchronous server like [Falcon](https://github.com/socketry/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 two main options for exposing the server:
+You have several main options for exposing the server:
 
 ### 1. Dedicated Port
 
@@ -932,6 +932,11 @@ bundle exec falcon serve --bind http://0.0.0.0:62770 --config mcp.ru
 bundle exec rails s -c mcp.ru -p 62770
 ```
 
+**With Passenger:**
+```bash
+passenger start --rackup mcp.ru --port 62770
+```
+
 Then, use your web server (Nginx, Apache, etc.) to reverse proxy requests to this port.
 
 ### 2. Unix Socket
@@ -948,6 +953,11 @@ bundle exec falcon serve --bind unix:/tmp/mcps0.sock mcp.ru
 bundle exec puma -C config/puma.rb -b unix:///tmp/mcps0.sock -c mcp.ru
 ```
 
+**With Passenger:**
+```bash
+passenger start --rackup mcp.ru --socket /tmp/mcps0.sock
+```
+
 And configure your web server to proxy to the socket:
 
 ```nginx
@@ -958,6 +968,30 @@ location /mcp/ {
 }
 ```
 
+### 3. Nginx With Passenger
+
+You can run both the main app and the MCP app using Passenger processes within Nginx.
+
+```nginx
+location / {
+  root /path/to/current/public;
+  passenger_app_root /path/to/current;
+  passenger_enabled on;
+
+   # ... additional configuration for the main Rails app
+}
+
+location ~* ^/mcp {
+  root /path/to/current/public;
+  passenger_app_root /path/to/current;
+  passenger_enabled on;
+  passenger_startup_file mcp.ru;
+  passenger_app_group_name mcp;
+}
+```
+
+You must set the `config.action_mcp.base_path` to match the above Nginx configuration, i.e. `config.action_mcp.base_path = '/mcp'`.
+
 **Key Points:**
 - MCPS0 is a standalone Rack app—run it separately from your main Rails server.
 - You can expose it via a TCP port (e.g., 62770) or a Unix socket.

config/routes.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 ActionMCP::Engine.routes.draw do
-  get "/up", to: "/rails/health#show", as: :action_mcp_health_check
+  get "#{ActionMCP.configuration.base_path}}/up", to: "/rails/health#show", as: :action_mcp_health_check
 
   # MCP 2025-03-26 Spec routes
-  get "/", to: "application#show", as: :mcp_get
-  post "/", to: "application#create", as: :mcp_post
-  delete "/", to: "application#destroy", as: :mcp_delete
+  get ActionMCP.configuration.base_path, to: "application#show", as: :mcp_get
+  post ActionMCP.configuration.base_path, to: "application#create", as: :mcp_post
+  delete ActionMCP.configuration.base_path, to: "application#destroy", as: :mcp_delete
 end

lib/action_mcp/configuration.rb

@@ -51,7 +51,9 @@ class Configuration
                   # --- Schema Validation Options ---
                   :validate_structured_content,
                   # --- Allowed identity keys for gateway ---
-                  :allowed_identity_keys
+                  :allowed_identity_keys,
+                  # --- JSON-RPC Path ---
+                  :base_path
 
     def initialize
       @logging_enabled = false
@@ -91,6 +93,9 @@ def initialize
       # and unauthorized attribute assignment. Extend this list if you use custom
       # identifier names in your GatewayIdentifier implementations.
       @allowed_identity_keys = %w[user api_key jwt bearer token account session].freeze
+
+      # Path for JSON-RPC endpoint
+      @base_path = "/"
     end
 
     def name

lib/action_mcp/engine.rb

@@ -45,7 +45,9 @@ class Engine < ::Rails::Engine
       ActionMCP.configuration.eager_load_if_needed
     end
 
-    config.middleware.use JSONRPC_Rails::Middleware::Validator, [ "/" ]
+    initializer "action_mcp.insert_middleware" do |app|
+      config.middleware.use JSONRPC_Rails::Middleware::Validator, [ ActionMCP.configuration.base_path ].compact.freeze
+    end
 
     # Load MCP profiles during initialization
     initializer "action_mcp.load_profiles" do

test/configuration_test.rb

@@ -13,6 +13,7 @@ class ConfigurationTest < ActiveSupport::TestCase
     assert_equal :warning, @config.logging_level
     assert_equal false, @config.resources_subscribe
     assert_equal :primary, @config.active_profile
+    assert_equal "/", @config.base_path
   end
 
   test "default profiles are loaded" do
@@ -227,4 +228,10 @@ class ConfigurationTest < ActiveSupport::TestCase
 
     assert_nil @config.instructions
   end
+
+  test "base_path can be set and retrieved" do
+    @config.base_path = "/mcp"
+
+    assert_equal "/mcp", @config.base_path
+  end
 end