mcp_logs 0.1.0

data/lib/generators/mcp_logs/templates/initializer.rb

@@ -0,0 +1,36 @@
+McpLogs.setup do |config|
+  # REQUIRED — replace CHANGE_ME before you deploy.
+  #
+  # These pages render every argument and every response your MCP server has
+  # logged. This gem ships no authentication of its own: its controllers descend
+  # from one of yours and inherit whatever that controller enforces. Name a
+  # controller that requires a signed-in operator, e.g. "Admin::BaseController".
+  #
+  # Left as-is, the first request to /mcp_logs raises. There is no default,
+  # because every default here is either broken or a security hole.
+  config.base_controller_class = "CHANGE_ME"
+
+  # Master switch. When false, nothing is recorded and calls run untouched.
+  # config.enabled = true
+
+  # A lambda returning your MCP::Server. Read by the docs page only.
+  # config.server = -> { Mcp::Registry.server }
+
+  # Group the docs page by tool name. Anything unlisted renders under "Ungrouped".
+  # config.tool_sections = { "Read" => %w[search_apps get_app], "Write" => %w[edit_app] }
+
+  # Payloads are filtered through Rails' filter_parameters, then this lambda,
+  # then capped at max_payload_bytes.
+  # config.record_payloads = true
+  # config.max_payload_bytes = 64_000
+  # config.payload_filter = ->(payload) { payload }
+
+  # Used by McpLogs::PurgeJob and `rake mcp_logs:purge`. Schedule one of them.
+  # config.retention_days = 30
+
+  # The same job settles rows stranded in "running" — a call whose process died
+  # before its completion was written. Set this above your slowest tool call.
+  # config.abandoned_after_hours = 24
+
+  # config.page_size = 50
+end

data/lib/mcp_logs/configuration.rb

@@ -0,0 +1,31 @@
+module McpLogs
+  # Raised when the engine is asked to do something the host has not told it how
+  # to do. Always fatal at boot or on the first request, never mid-capture.
+  class ConfigurationError < StandardError; end
+
+  class Configuration
+    # server:                a lambda returning the host's MCP::Server. Read by the
+    #                        docs page only — capture never builds a server.
+    # base_controller_class: a String, constantized on first autoload of the engine's
+    #                        ApplicationController, i.e. after host initializers have run.
+    #                        Has no default on purpose — see McpLogs.base_controller.
+    # tool_sections:         { "Section title" => ["tool_name", ...] }. Names, not classes,
+    #                        so the gem never references host constants.
+    attr_accessor :enabled, :server, :base_controller_class, :tool_sections,
+                  :record_payloads, :max_payload_bytes, :payload_filter,
+                  :retention_days, :abandoned_after_hours, :page_size
+
+    def initialize
+      @enabled               = true
+      @server                = nil
+      @base_controller_class = nil
+      @tool_sections         = {}
+      @record_payloads       = true
+      @max_payload_bytes     = 64_000
+      @payload_filter        = ->(payload) { payload }
+      @retention_days        = 30
+      @abandoned_after_hours = 24
+      @page_size             = 50
+    end
+  end
+end

data/lib/mcp_logs/context.rb

@@ -0,0 +1,42 @@
+module McpLogs
+  # HTTP-level facts about the request being served. The mcp gem's around_request
+  # hook sees none of this, so the host wraps its handler call in
+  # McpLogs.with_context(request) and the recorder reads it back here.
+  #
+  # Fiber storage rather than Thread.current: it follows into fibers the server
+  # may spawn, and it is restored on unwind, so a raising handler cannot strand a
+  # stale context on a pooled thread.
+  module Context
+    KEY = :mcp_logs_context
+
+    module_function
+
+    def current
+      Fiber[KEY] || {}
+    end
+
+    def with(request = nil, actor: nil, session_id: nil, protocol_version: nil)
+      previous = Fiber[KEY]
+      explicit = { actor: actor, session_id: session_id, protocol_version: protocol_version }.compact
+      Fiber[KEY] = from_request(request).merge(explicit)
+      yield
+    ensure
+      Fiber[KEY] = previous
+    end
+
+    def from_request(request)
+      return {} if request.nil?
+
+      {
+        ip: request.respond_to?(:remote_ip) ? request.remote_ip : request.ip,
+        user_agent: request.user_agent.presence,
+        session_id: header(request, "Mcp-Session-Id"),
+        protocol_version: header(request, "Mcp-Protocol-Version")
+      }.compact
+    end
+
+    def header(request, name)
+      request.get_header("HTTP_#{name.upcase.tr("-", "_")}").presence
+    end
+  end
+end

data/lib/mcp_logs/engine.rb

@@ -0,0 +1,9 @@
+module McpLogs
+  class Engine < ::Rails::Engine
+    isolate_namespace McpLogs
+
+    rake_tasks do
+      load File.expand_path("../tasks/mcp_logs.rake", __dir__)
+    end
+  end
+end

data/lib/mcp_logs/payload.rb

@@ -0,0 +1,43 @@
+module McpLogs
+  # Turns a tool's arguments or a handler's result into something safe to store:
+  # host-redacted, host-filtered, and bounded in size.
+  module Payload
+    module_function
+
+    # Returns [value_to_store, truncated?]. A nil value, or payload recording
+    # turned off, stores nothing at all.
+    def prepare(value)
+      return [nil, false] if value.nil?
+      return [nil, false] unless McpLogs.record_payloads?
+
+      filtered = McpLogs.payload_filter.call(parameter_filter.filter(normalize(value)))
+      cap(filtered)
+    end
+
+    # ActiveSupport::ParameterFilter only walks hashes, and the columns are jsonb,
+    # so a bare scalar result gets a wrapper rather than being dropped.
+    def normalize(value)
+      value.is_a?(Hash) ? value.deep_stringify_keys : { "value" => value }
+    end
+
+    def cap(value)
+      json = value.to_json
+      return [value, false] if json.bytesize <= McpLogs.max_payload_bytes
+
+      # byteslice can cut mid-character; scrub keeps the column valid UTF-8.
+      preview = json.byteslice(0, McpLogs.max_payload_bytes).scrub("")
+      [{ "truncated" => true, "bytes" => json.bytesize, "preview" => preview }, true]
+    end
+
+    # Rebuilt only when reset! is called: compiling the filter's regexps on every
+    # logged call would be pure overhead on the request path.
+    def parameter_filter
+      @parameter_filter ||=
+        ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+    end
+
+    def reset!
+      @parameter_filter = nil
+    end
+  end
+end

data/lib/mcp_logs/version.rb

@@ -0,0 +1,3 @@
+module McpLogs
+  VERSION = "0.1.0"
+end

data/lib/mcp_logs.rb

@@ -0,0 +1,92 @@
+require "pagy"
+require "mcp_logs/version"
+require "mcp_logs/configuration"
+require "mcp_logs/engine"
+require "mcp_logs/context"
+require "mcp_logs/payload"
+
+module McpLogs
+  # `server` is absent on purpose: McpLogs.server calls the configured lambda
+  # rather than returning it, so it gets an explicit reader below and only its
+  # writer is generated here.
+  SETTINGS = %i[
+    enabled base_controller_class tool_sections record_payloads
+    max_payload_bytes payload_filter retention_days abandoned_after_hours page_size
+  ].freeze
+
+  MISSING_BASE_CONTROLLER = <<~MESSAGE.freeze
+    McpLogs has no base_controller_class, so its pages would have no authentication.
+
+    Set it in config/initializers/mcp_logs.rb to a controller of your own whose
+    authentication the log pages should inherit:
+
+      config.base_controller_class = "Admin::BaseController"
+
+    Use "ActionController::Base" only if you intend /mcp_logs — every tool
+    argument and response your MCP server has recorded — to be readable by
+    anyone who can reach the app.
+  MESSAGE
+
+  class << self
+    def setup
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Specs and hosts that reconfigure at runtime need a clean slate.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # One reader and one writer per setting, so `McpLogs.page_size = 1` works in a
+    # spec and `McpLogs.page_size` reads naturally in a view.
+    SETTINGS.each do |setting|
+      define_method(setting) { configuration.public_send(setting) }
+      define_method(:"#{setting}=") { |value| configuration.public_send(:"#{setting}=", value) }
+    end
+
+    def enabled? = !!configuration.enabled
+
+    def record_payloads? = !!configuration.record_payloads
+
+    # Calls the configured lambda. Returns nil when no server is configured, which
+    # the docs page renders as "no server configured" rather than raising.
+    def server = configuration.server&.call
+
+    def server=(value)
+      configuration.server = value
+    end
+
+    # Resolved when the engine's ApplicationController is first autoloaded, i.e.
+    # after the host's initializers have run.
+    #
+    # There is no default. Every page this engine serves renders arguments and
+    # responses the host's MCP server has logged, so an engine that quietly
+    # descended from ActionController::Base would publish the audit log of any
+    # app that installed it without reading the whole README. Failing here costs
+    # a stranger one boot; the alternative costs them the log.
+    def base_controller
+      configured = configuration.base_controller_class.to_s
+      raise ConfigurationError, MISSING_BASE_CONTROLLER if configured.empty?
+
+      configured.constantize
+    rescue NameError
+      # The generated initializer ships a placeholder, so "set but not resolvable"
+      # is the likeliest way a host gets here — and a bare NameError names the
+      # constant without saying which setting produced it.
+      raise ConfigurationError, "McpLogs base_controller_class is #{configured.inspect}, " \
+                                "which does not name a controller. #{MISSING_BASE_CONTROLLER}"
+    end
+
+    def around_request(server_name: nil)
+      McpLogs::Recorder.around_request(server_name: server_name)
+    end
+
+    def with_context(request = nil, **options, &block)
+      McpLogs::Context.with(request, **options, &block)
+    end
+  end
+end

data/lib/tasks/mcp_logs.rake

@@ -0,0 +1,10 @@
+namespace :mcp_logs do
+  desc "Delete logged MCP calls past McpLogs.retention_days, and settle any stranded in running"
+  task purge: :environment do
+    deleted = McpLogs::Call.purge!
+    puts "mcp_logs: deleted #{deleted} calls older than #{McpLogs.retention_days} days"
+
+    swept = McpLogs::Call.sweep_abandoned!
+    puts "mcp_logs: marked #{swept} calls abandoned after #{McpLogs.abandoned_after_hours} hours running"
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: mcp_logs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Anton
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '43.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '43.0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Mountable Rails engine that records every Model Context Protocol request
+  a Rails app serves and renders its tool contract as documentation.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/config/mcp_logs_manifest.js
+- app/assets/stylesheets/mcp_logs.css
+- app/controllers/mcp_logs/application_controller.rb
+- app/controllers/mcp_logs/calls_controller.rb
+- app/controllers/mcp_logs/docs_controller.rb
+- app/helpers/mcp_logs/calls_helper.rb
+- app/jobs/mcp_logs/purge_job.rb
+- app/models/mcp_logs/application_record.rb
+- app/models/mcp_logs/call.rb
+- app/models/mcp_logs/docs.rb
+- app/models/mcp_logs/recorder.rb
+- app/views/layouts/mcp_logs/application.html.erb
+- app/views/mcp_logs/calls/_pagination.html.erb
+- app/views/mcp_logs/calls/index.html.erb
+- app/views/mcp_logs/calls/show.html.erb
+- app/views/mcp_logs/docs/show.html.erb
+- config/routes.rb
+- db/migrate/001_create_mcp_logs_calls.rb
+- lib/generators/mcp_logs/install_generator.rb
+- lib/generators/mcp_logs/templates/initializer.rb
+- lib/mcp_logs.rb
+- lib/mcp_logs/configuration.rb
+- lib/mcp_logs/context.rb
+- lib/mcp_logs/engine.rb
+- lib/mcp_logs/payload.rb
+- lib/mcp_logs/version.rb
+- lib/tasks/mcp_logs.rake
+homepage: https://github.com/tonic20/mcp_logs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tonic20/mcp_logs
+  source_code_uri: https://github.com/tonic20/mcp_logs
+  changelog_uri: https://github.com/tonic20/mcp_logs/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Rails engine for MCP request logging and tool documentation
+test_files: []