rails-informant 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cb09528a587e40da2aa7b66b56483f97953dcde9fd01e172009e859236b1b83
-  data.tar.gz: ad121656a0ae00abd63c49ffc26f493a0cd5d90412f68ef657ec63dbb2eddce6
+  metadata.gz: b66bd1a6283f2a349a57994f529a0b57b71053c979c874268283d97477928873
+  data.tar.gz: d17e62d7ba21318f94205d9365d293ce1110fe58e9c56b4c82cc0c334e4f65bf
 SHA512:
-  metadata.gz: 9b449febb753c029ac0905a9a9af076039e3b008be77bfe2f444fbabadfb1ca9c4b66e19165c618d326fa78f70bda1cd8e284c0a052425a69cdea13e8aa5b9a8
-  data.tar.gz: dd18b3b3e42d3551c08dc23bfe68e0f497e7b373713985e7fea8f569b5c352d263491e7ea98967d596cb6748530a702d03289936e5cc50a1a5fe2d22aaba7a66
+  metadata.gz: cf7f02ec548bbd755dc411b3f08a9a74807d45e333ccd3aedaf99b02be909ec4b4a046146ca913943dc41b88dc3e78cafcdf140163cdb1de2537c5d3f5a5b170
+  data.tar.gz: dd582dce1ccee4a3e6eaa3678c118416f9dff50afeafc00ad0a9a65a59e50760188541817f859d374f8aec5d139b5febb3024c54340b2b5fd98e36aa47fcfcf1

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,33 @@ 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. The install generator creates `.mcp.json` automatically.
+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. **Set env vars** for the MCP server (e.g., via `.envrc` + [direnv](https://direnv.net)):
+   ```sh
+   # .envrc
+   export INFORMANT_PRODUCTION_URL=https://myapp.com
+   export INFORMANT_PRODUCTION_TOKEN=your-api-token
+   ```
+   The MCP server process inherits environment variables from your shell, so `INFORMANT_*` vars set via `.envrc` (or any other method) are picked up automatically -- no need to inline them in `.mcp.json`.
+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).
+
+> **Connecting the tokens:** The `api_token` in your Rails credentials and `INFORMANT_PRODUCTION_TOKEN` must be the **same value**. The first authenticates incoming requests to your app; the second tells the MCP server what token to send.
+
+> **Secrets hygiene:** `.envrc` contains secrets and should be in `.gitignore`. `.mcp.json` is safe to commit -- it only contains the command name, no tokens.
+
 ## Configuration
 
 ```ruby
@@ -77,11 +105,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,52 +142,27 @@ 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:
+The install generator creates `.mcp.json` for you. To set it up manually:
 
 ```json
 {
   "mcpServers": {
     "informant": {
-      "command": "informant-mcp",
-      "env": {
-        "INFORMANT_PRODUCTION_URL": "https://myapp.com",
-        "INFORMANT_PRODUCTION_TOKEN": "your-api-token"
-      }
+      "command": "informant-mcp"
     }
   }
 }
 ```
 
-Or create `~/.config/informant-mcp.yml` for multi-environment setups:
+Set `INFORMANT_PRODUCTION_URL` and `INFORMANT_PRODUCTION_TOKEN` as environment variables (e.g., via `.envrc` + direnv). The MCP server inherits env vars from your shell -- no need to put secrets in `.mcp.json`.
+
+For multi-environment setups, create `~/.config/informant-mcp.yml`:
 
 ```yaml
 environments:
@@ -188,6 +191,23 @@ environments:
 | `get_informant_status` | Summary with counts and top errors |
 | `list_occurrences` | List occurrences with filtering |
 
+### Local Development
+
+The MCP server enforces HTTPS by default. When pointing at a local HTTP URL (e.g., `http://localhost:3000`), pass `--allow-insecure`:
+
+```json
+{
+  "mcpServers": {
+    "informant": {
+      "command": "informant-mcp",
+      "args": ["--allow-insecure"]
+    }
+  }
+}
+```
+
+This is only needed for local development/testing. Production setups over HTTPS don't need it.
+
 ## Claude Code Skill
 
 Use `/informant` in Claude Code to triage and fix errors interactively. The skill:
@@ -233,12 +253,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 +308,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 +334,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

@@ -1,3 +1,4 @@
+require "json"
 require "rails/generators"
 require "rails/generators/active_record"
 
@@ -20,5 +21,53 @@ module RailsInformant
     def mount_engine
       route "mount RailsInformant::Engine => '/informant'"
     end
+
+    def create_or_update_mcp_json
+      mcp_path = File.join(destination_root, ".mcp.json")
+      informant_entry = { "command" => "informant-mcp" }
+
+      if File.exist?(mcp_path)
+        existing = JSON.parse(File.read(mcp_path))
+        existing["mcpServers"] ||= {}
+        existing["mcpServers"]["informant"] = informant_entry
+        create_file ".mcp.json", JSON.pretty_generate(existing) + "\n", force: true
+      else
+        create_file ".mcp.json", JSON.pretty_generate(
+          "mcpServers" => { "informant" => informant_entry }
+        ) + "\n"
+      end
+    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. Configure env vars for the MCP server (e.g., via .envrc + direnv):"
+      say "       export INFORMANT_PRODUCTION_URL=https://your-app.com"
+      say "       export INFORMANT_PRODUCTION_TOKEN=your-api-token"
+      say ""
+      say "     The token must match the api_token in your Rails credentials."
+      say "     Add .envrc to .gitignore — it contains secrets."
+      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.7
 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