rails-informant 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cb09528a587e40da2aa7b66b56483f97953dcde9fd01e172009e859236b1b83
-  data.tar.gz: ad121656a0ae00abd63c49ffc26f493a0cd5d90412f68ef657ec63dbb2eddce6
+  metadata.gz: 51a0bd3a42b6c332ee192a319eaf43b8b129013995ac42d35a0de294a69c968f
+  data.tar.gz: 2eef05b3963d12586672b650cff43f5b999d8852ff229e42114f6b9cff0572a3
 SHA512:
-  metadata.gz: 9b449febb753c029ac0905a9a9af076039e3b008be77bfe2f444fbabadfb1ca9c4b66e19165c618d326fa78f70bda1cd8e284c0a052425a69cdea13e8aa5b9a8
-  data.tar.gz: dd18b3b3e42d3551c08dc23bfe68e0f497e7b373713985e7fea8f569b5c352d263491e7ea98967d596cb6748530a702d03289936e5cc50a1a5fe2d22aaba7a66
+  metadata.gz: b9e51bc32c5393a1dced3621b661c72e8dcdf87d11a5d640c7addceb1ce9ec1526bc170519d0e71466503e2d589d53bdaec3b8063c21020d7fff3c6db5f12b82
+  data.tar.gz: 5eff7c322d4722b26d018dcf7a12e8f692e57e0f66374612e27271b41766a142cde8bb116dedbab1594f77aa6b1e28ec0e1b586929c69c39a9bd68b5f20cd2e3

data/README.md

@@ -13,10 +13,11 @@
   <p>
     <a href="#why-rails-informant">Why Rails Informant?</a>
     &#9670; <a href="#quick-start">Quick Start</a>
+    &#9670; <a href="#agent-setup">Agent Setup</a>
     &#9670; <a href="#configuration">Configuration</a>
     &#9670; <a href="#mcp-server">MCP Server</a>
     &#9670; <a href="#architecture">Architecture</a>
-    &#9670; <a href="#data--privacy">Data & Privacy</a>
+    &#9670; <a href="#data-and-privacy">Data and Privacy</a>
     &#9670; <a href="#security">Security</a>
   </p>
 </div>
@@ -65,6 +66,38 @@ Errors are captured automatically in non-local environments. To capture errors m
 RailsInformant.capture(exception, context: { order_id: 42 })
 ```
 
+## Agent Setup
+
+End-to-end path for AI agents (Claude Code, Devin) to start triaging errors:
+
+1. **Install the gem** -- follow [Quick Start](#quick-start) above
+2. **Set an authentication token** in your Rails credentials or env var:
+   ```ruby
+   # config/initializers/rails_informant.rb
+   config.api_token = Rails.application.credentials.dig(:rails_informant, :api_token)
+   ```
+3. **Add the MCP server** to your agent's config (see [MCP Server](#mcp-server) for full options):
+   ```json
+   {
+     "mcpServers": {
+       "informant": {
+         "command": "informant-mcp",
+         "env": {
+           "INFORMANT_PRODUCTION_URL": "https://myapp.com",
+           "INFORMANT_PRODUCTION_TOKEN": "your-api-token"
+         }
+       }
+     }
+   }
+   ```
+4. **Install the Claude Code skill** (optional but recommended):
+   ```sh
+   bin/rails generate rails_informant:skill
+   ```
+5. **Use `/informant`** in Claude Code to triage and fix errors, or let Devin handle them autonomously with the [Devin integration](#devin-ai).
+
+> **Env var scoping:** `INFORMANT_API_TOKEN` configures the Rails app. `INFORMANT_PRODUCTION_URL` and `INFORMANT_PRODUCTION_TOKEN` configure the MCP server (agent side). They are different processes -- both need a token, but the MCP env vars point the agent at your running app.
+
 ## Configuration
 
 ```ruby
@@ -77,11 +110,11 @@ RailsInformant.configure do |config|
 end
 ```
 
-Every option can be set via an environment variable. The initializer takes precedence over env vars.
+Every option can be set via an environment variable. The initializer takes precedence over env vars. These configure the **Rails app**. For MCP server env vars (agent side), see [Agent Setup](#agent-setup).
 
 | Option | Env var | Default | Description |
 |--------|---------|---------|-------------|
-| `api_token` | `INFORMANT_API_TOKEN` | `nil` | Bearer token for API authentication (required for MCP) |
+| `api_token` | `INFORMANT_API_TOKEN` | `nil` | Authentication token for MCP server access |
 | `capture_errors` | `INFORMANT_CAPTURE_ERRORS` | `true` | Enable/disable error capture (set to `"false"` to disable) |
 | `devin_api_key` | `INFORMANT_DEVIN_API_KEY` | `nil` | Devin AI API key for autonomous error fixing |
 | `devin_playbook_id` | `INFORMANT_DEVIN_PLAYBOOK_ID` | `nil` | Devin playbook ID for error triage workflow |
@@ -114,33 +147,10 @@ config.ignored_exceptions = ["MyApp::BoringError", /Stripe::/]
 
 Structured events from `ActiveSupport::Notifications` are captured automatically as breadcrumbs -- SQL query names, cache hits, template renders, HTTP calls, job executions. Stored per-occurrence for rich debugging context without raw log lines.
 
-## API
-
-Token-authenticated JSON API mounted at `/informant/api/v1/`.
-
-```text
-GET    /informant/api/v1/errors            # List error groups (paginated, filterable)
-GET    /informant/api/v1/errors/:id         # Show with recent occurrences
-PATCH  /informant/api/v1/errors/:id         # Update status or notes
-DELETE /informant/api/v1/errors/:id         # Delete group and occurrences
-PATCH  /informant/api/v1/errors/:id/fix_pending  # Mark fix pending
-PATCH  /informant/api/v1/errors/:id/duplicate    # Mark as duplicate
-GET    /informant/api/v1/occurrences        # List occurrences
-GET    /informant/api/v1/status             # Error monitoring summary
-```
-
-Authenticate with `Authorization: Bearer <token>`.
-
 ## MCP Server
 
 The bundled `informant-mcp` executable connects Claude Code to your error data via [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
 
-The MCP server requires the `mcp` gem, which is not a runtime dependency. Add it to your Gemfile:
-
-```ruby
-gem "mcp", ">= 0.7", "< 2"
-```
-
 ### Setup
 
 Add to your Claude Code MCP config:
@@ -233,12 +243,12 @@ The notification prompt includes: error class, error message (truncated), severi
 Development Machine                    Remote Servers
 +-----------------------+              +-----------------------+
 |  Claude Code          |              |  Production           |
-|        |              |              |  /informant/api/v1    |
+|        |              |              |  /informant           |
 |        | stdio        |              +-----------------------+
 |        v              |  HTTPS+Token
 |  MCP Server           | -----------> +-----------------------+
 |  (exe/informant-mcp)  |              |  Staging              |
-|                       |              |  /informant/api/v1    |
+|                       |              |  /informant           |
 +-----------------------+              +-----------------------+
 
 Inside the Rails app:
@@ -288,7 +298,7 @@ bin/rails informant:stats    # Show error monitoring statistics
 bin/rails informant:purge    # Purge resolved errors older than retention_days
 ```
 
-## Data & Privacy
+## Data and Privacy
 
 Each occurrence stores the following PII:
 
@@ -314,18 +324,18 @@ This replaces email values with `[FILTERED]` in occurrence data. IP addresses ca
 
 ## Security
 
-- API requires bearer token authentication (`secure_compare`)
+- MCP server requires token authentication (`secure_compare`)
 - All stored context is filtered through `ActiveSupport::ParameterFilter`
 - MCP server enforces HTTPS by default
 - Security headers: `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`
 - Error capture never breaks the host application
 - Webhook payloads strip PII by default
-- **Rate limiting** -- the API does not include built-in rate limiting. Add rate limiting on the `/informant/api/` prefix in production, for example with [Rack::Attack](https://github.com/rack/rack-attack):
+- **Rate limiting** -- the engine does not include built-in rate limiting. Add rate limiting on the `/informant/` prefix in production, for example with [Rack::Attack](https://github.com/rack/rack-attack):
 
 ```ruby
 # config/initializers/rack_attack.rb
-Rack::Attack.throttle("informant/api", limit: 60, period: 1.minute) do |req|
-  req.ip if req.path.start_with?("/informant/api/")
+Rack::Attack.throttle("informant", limit: 60, period: 1.minute) do |req|
+  req.ip if req.path.start_with?("/informant/")
 end
 ```
 

data/exe/informant-mcp

@@ -3,11 +3,7 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
-begin
-  require "mcp"
-rescue LoadError
-  abort 'The "mcp" gem is required to run the Informant MCP server. Add gem "mcp", ">= 0.7", "< 2" to your Gemfile and run bundle install.'
-end
+require "mcp"
 
 require "optparse"
 require "rails_informant/mcp"

data/lib/generators/rails_informant/install_generator.rb

@@ -20,5 +20,43 @@ module RailsInformant
     def mount_engine
       route "mount RailsInformant::Engine => '/informant'"
     end
+
+    def print_next_steps
+      say ""
+      say "Rails Informant installed!", :green
+      say ""
+      say "Next steps:", :yellow
+      say "  1. Run migrations:"
+      say "       bin/rails db:migrate"
+      say ""
+      say "  2. Set a token (required for MCP server access):"
+      say "       bin/rails credentials:edit"
+      say "       # Add: rails_informant:"
+      say "       #        api_token: #{SecureRandom.hex 32}"
+      say ""
+      say "  3. Add the MCP server to .mcp.json (for Claude Code):"
+      say "       {"
+      say "         \"mcpServers\": {"
+      say "           \"informant\": {"
+      say "             \"command\": \"informant-mcp\","
+      say "             \"env\": {"
+      say "               \"INFORMANT_PRODUCTION_URL\": \"https://your-app.com\","
+      say "               \"INFORMANT_PRODUCTION_TOKEN\": \"your-api-token\""
+      say "             }"
+      say "           }"
+      say "         }"
+      say "       }"
+      say ""
+      say "  4. Optional — install the Claude Code skill:"
+      say "       bin/rails generate rails_informant:skill"
+      say ""
+    end
+
+    private
+
+    def json_column_type
+      adapter = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).first&.adapter.to_s
+      adapter.match?(/postgres/i) ? "jsonb" : "json"
+    end
   end
 end

data/lib/generators/rails_informant/skill/templates/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools:
   - Glob
   - Edit
   - Write
-  - Bash(bin/test *)
+  - Bash(bin/rails test *)
   - Bash(bundle exec *)
 ---
 

data/lib/generators/rails_informant/templates/create_informant_tables.rb.erb

@@ -38,13 +38,13 @@ class CreateInformantTables < ActiveRecord::Migration[8.1]
     create_table :informant_occurrences do |t|
       t.references :error_group, null: false,
         foreign_key: { to_table: :informant_error_groups }
-      t.jsonb :backtrace
-      t.jsonb :exception_chain
-      t.jsonb :request_context
-      t.jsonb :user_context
-      t.jsonb :custom_context
-      t.jsonb :environment_context
-      t.jsonb :breadcrumbs
+      t.<%= json_column_type %> :backtrace
+      t.<%= json_column_type %> :exception_chain
+      t.<%= json_column_type %> :request_context
+      t.<%= json_column_type %> :user_context
+      t.<%= json_column_type %> :custom_context
+      t.<%= json_column_type %> :environment_context
+      t.<%= json_column_type %> :breadcrumbs
       t.string :git_sha
       t.timestamps
 

data/lib/generators/rails_informant/templates/initializer.rb.erb

@@ -15,7 +15,7 @@ RailsInformant.configure do |config|
   # Or override what is captured by setting user context explicitly:
   #   RailsInformant::Current.user_context = { id: current_user.id }
 
-  # API token for the JSON API (required for MCP server access)
+  # Authentication token (required for MCP server access)
   config.api_token = Rails.application.credentials.dig(:rails_informant, :api_token)
 
   # Slack webhook URL for error notifications

data/lib/rails_informant/engine.rb

@@ -68,19 +68,25 @@ module RailsInformant
 
       token = RailsInformant.api_token
 
-      if token.nil?
-        raise <<~MSG.squish
+      message = if token.nil?
+        <<~MSG.squish
           RailsInformant: api_token must be configured when capture_errors is enabled.
           Set it in your initializer: config.api_token = "your-secret-token"
         MSG
-      end
-
-      if token.length < MINIMUM_TOKEN_LENGTH
-        raise <<~MSG.squish
+      elsif token.length < MINIMUM_TOKEN_LENGTH
+        <<~MSG.squish
           RailsInformant: api_token must be at least #{MINIMUM_TOKEN_LENGTH} characters.
           Use SecureRandom.hex(32) or Rails credentials to generate a secure token.
         MSG
       end
+
+      return unless message
+
+      if RailsInformant.server_mode?
+        raise message
+      else
+        Rails.logger&.warn message
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-informant
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Daniel López Prat
@@ -65,6 +65,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement