crumb-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da7be171e2bd8321f2ff39694fc935a988f8ae6231f1ae97ff2dd7be5fc8ed87
+  data.tar.gz: '0969611434b08ad6cd336414579a8014fb99a058e61d03d51f3c50634ccfb776'
+SHA512:
+  metadata.gz: 0fb3f2b41f71fb409df580fb2f635303be27e02504437de1f909d6ac93138c88ac0b1f7f7de43b546d6eab61c0c20461c05f09a99eeeea06bc92142106901694
+  data.tar.gz: 6a5b2f8e95518b09a4a651419624040cc174c00092ef9698754e0064e876f266440b7163c0477c80cd6c5fa328f9825b62fd0a55906aaf5b2d58edb1f80991b4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolás Galdámez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# crumb-mcp
+
+A standalone [MCP](https://modelcontextprotocol.io) server that queries one or more
+[Crumb](../README.md) endpoints, so an AI assistant (e.g. Claude Code) can answer
+questions about your deploys: what shipped, when, by whom, and which files changed.
+
+Each developer runs this locally. It talks to the read API exposed by the
+[`crumb` engine](../engine) mounted in your apps, authenticating with a read token.
+
+## Installation
+
+Install the gem from RubyGems — no clone needed:
+
+```bash
+gem install crumb-mcp
+```
+
+The entrypoint is `crumb-mcp`, run over stdio.
+
+> **Working on the gem itself?** Clone the repo and `cd mcp && bundle install`; the
+> entrypoint is then `bundle exec exe/crumb-mcp`.
+
+## Configuration
+
+Create `~/.config/crumb/config.yml` describing each app endpoint you want to query:
+
+```yaml
+endpoints:
+  my-app-staging:
+    base_url: https://staging.your-app.com/crumb
+    token_env: CRUMB_READ_TOKEN_STAGING
+    repo_path: ~/code/your-app          # optional, for local git lookups
+  my-app-production:
+    base_url: https://your-app.com/crumb
+    token_env: CRUMB_READ_TOKEN_PRODUCTION
+    repo_path: ~/code/your-app
+```
+
+- **`base_url`** — the engine's mount URL (the same `/crumb` path the app mounts).
+- **`token_env`** — the name of the env var holding this endpoint's read token. The
+  server reads the token from the environment, so secrets stay out of the config file.
+- **`repo_path`** — optional local checkout, used by tools that inspect git directly.
+
+The map keys (`my-app-staging`, …) are the endpoint **slugs** you pass to the tools;
+omit the slug on most tools to fan out across every endpoint.
+
+Mint a token from each app (`bin/rails crumb:tokens:mint OWNER=you@example.com` — see the
+[engine README](../engine/README.md#read-access-tokens)) and export it under the matching
+`token_env`:
+
+```bash
+# ~/.zshrc
+export CRUMB_READ_TOKEN_STAGING=...
+export CRUMB_READ_TOKEN_PRODUCTION=...
+```
+
+## Registering with Claude Code
+
+If you ran `gem install crumb-mcp`, register the executable directly:
+
+```bash
+claude mcp add crumb -- crumb-mcp
+```
+
+Or skip the install step entirely and let `gem exec` fetch and run the gem on demand
+(Ruby 3.4+ / RubyGems 3.5+):
+
+```bash
+claude mcp add crumb -- gem exec crumb-mcp
+```
+
+Restart Claude Code so the tools register in a fresh session, then ask things like
+*"What deployed to my-app-staging today?"*.
+
+> **From a local checkout** (gem development): point the command at `bundle exec`:
+> `claude mcp add crumb -- bash -c "cd /absolute/path/to/crumb/mcp && bundle exec exe/crumb-mcp"`
+
+## Tools
+
+| Tool | Input | Returns |
+|------|-------|---------|
+| `recent_deploys` | `endpoint?`, `limit?` | Most recent deploys, across all endpoints or one |
+| `deploy_details` | `endpoint`, `id`, `include_diff?` | One deploy with commits and changed files |
+| `compare_deploys` | `endpoint`, `from_id`, `to_id` | Union of commits/files between two deploys |
+| `find_deploys_touching` | `path_prefix`, `endpoint?`, `limit?` | Deploys that changed files under a path prefix |
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT).

data/exe/crumb-mcp

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "crumb/mcp"
+
+server = MCP::Server.new(
+  name:    "crumb",
+  version: Crumb::MCP::VERSION,
+  tools:   [
+    Crumb::MCP::Tools::RecentDeploysTool,
+    Crumb::MCP::Tools::DeployDetailsTool,
+    Crumb::MCP::Tools::CompareDeploysTool,
+    Crumb::MCP::Tools::FindDeploysTouchingTool
+  ]
+)
+
+MCP::Server::Transports::StdioTransport.new(server).open

data/lib/crumb/mcp/api_client.rb

@@ -0,0 +1,70 @@
+require "faraday"
+require "json"
+require "shellwords"
+require "uri"
+
+module Crumb
+  module MCP
+    class ApiClient
+      class Error < StandardError; end
+
+      def self.for(slug)
+        ep    = Registry.endpoint_for(slug)
+        token = ENV.fetch(ep[:token_env]) do
+          raise Error, "Missing env var #{ep[:token_env]} for endpoint #{slug}"
+        end
+        new(ep[:base_url], token, ep[:repo_path], slug)
+      end
+
+      def initialize(base_url, token, repo_path, slug)
+        @base_url  = base_url.chomp("/")
+        @token     = token
+        @repo_path = repo_path
+        @slug      = slug
+      end
+
+      def recent(limit: 20)
+        data = get("/deploys?limit=#{limit}")
+        (data["deploys"] || []).map { |d| d.merge("endpoint" => @slug) }
+      end
+
+      def detail(id)
+        get("/deploys/#{id}").merge("endpoint" => @slug)
+      end
+
+      def touching(path_prefix, limit: 20)
+        data = get("/deploys?touching=#{URI.encode_uri_component(path_prefix)}&limit=#{limit}")
+        (data["deploys"] || []).map { |d| d.merge("endpoint" => @slug) }
+      end
+
+      def diff(sha, repo_path: nil)
+        dir = repo_path || @repo_path
+        raise Error, "No repo_path configured for endpoint #{@slug}" unless dir
+        `git -C #{Shellwords.escape(dir)} show #{Shellwords.escape(sha)} --stat 2>&1`
+      end
+
+      private
+
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 15
+
+      def get(path)
+        response = connection.get("#{@base_url}#{path}") do |req|
+          req.headers["Authorization"] = "Bearer #{@token}"
+          req.headers["Accept"]        = "application/json"
+        end
+        raise Error, "HTTP #{response.status} from #{@slug}" unless response.status == 200
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise Error, "Request to #{@slug} failed: #{e.message}"
+      end
+
+      def connection
+        @connection ||= Faraday.new do |f|
+          f.options.open_timeout = OPEN_TIMEOUT
+          f.options.timeout      = READ_TIMEOUT
+        end
+      end
+    end
+  end
+end

data/lib/crumb/mcp/registry.rb

@@ -0,0 +1,39 @@
+require "yaml"
+
+module Crumb
+  module MCP
+    class Registry
+      CONFIG_PATH = File.expand_path("~/.config/crumb/config.yml")
+
+      class << self
+        def all_slugs
+          endpoints.keys
+        end
+
+        def endpoint_for(slug)
+          ep = endpoints[slug]
+          raise ArgumentError, "Unknown Crumb endpoint: #{slug}" unless ep
+          {
+            base_url:  ep["base_url"],
+            token_env: ep["token_env"],
+            repo_path: ep["repo_path"] && File.expand_path(ep["repo_path"])
+          }
+        end
+
+        private
+
+        def endpoints
+          config["endpoints"] or
+            raise "No 'endpoints' key found in #{CONFIG_PATH}"
+        end
+
+        def config
+          @config ||= begin
+            raise "Crumb config not found at #{CONFIG_PATH}" unless File.exist?(CONFIG_PATH)
+            YAML.safe_load_file(CONFIG_PATH)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crumb/mcp/tools/compare_deploys.rb

@@ -0,0 +1,39 @@
+module Crumb
+  module MCP
+    module Tools
+      class CompareDeploysTool < ::MCP::Tool
+        tool_name "compare_deploys"
+        description "Union of commits and changed files between two deploys on the same endpoint."
+        input_schema(
+          properties: {
+            endpoint: { type: "string",  description: "Endpoint slug." },
+            from_id:  { type: "integer", description: "Older deploy ID." },
+            to_id:    { type: "integer", description: "Newer deploy ID." }
+          },
+          required: [ "endpoint", "from_id", "to_id" ]
+        )
+
+        class << self
+          def call(endpoint:, from_id:, to_id:, server_context: nil)
+            client = ApiClient.for(endpoint)
+            from   = client.detail(from_id)
+            to     = client.detail(to_id)
+
+            all_commits = (Array(from["commits"]) + Array(to["commits"]))
+              .uniq { |c| c["sha"] }
+            all_files   = (Array(from["changed_files"]) + Array(to["changed_files"]))
+              .uniq { |f| f["path"] }
+
+            text = "Comparison between deploy ##{from_id} and ##{to_id} on #{endpoint}\n\n"
+            text += "Commits (#{all_commits.size} unique):\n"
+            all_commits.each { |c| text += "  #{c["sha"].to_s[0, 8]} #{c["author"]} — #{c["message"]}\n" }
+            text += "\nChanged files (#{all_files.size} unique):\n"
+            all_files.each { |f| text += "  #{f["change_type"]} #{f["path"]}\n" }
+
+            ::MCP::Tool::Response.new([ { type: "text", text: text } ])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crumb/mcp/tools/deploy_details.rb

@@ -0,0 +1,51 @@
+module Crumb
+  module MCP
+    module Tools
+      class DeployDetailsTool < ::MCP::Tool
+        tool_name "deploy_details"
+        description "Full detail for one deploy: commits, changed files, and optionally the git diff."
+        input_schema(
+          properties: {
+            endpoint:     { type: "string",  description: "Endpoint slug (required)." },
+            id:           { type: "integer", description: "Deploy ID." },
+            include_diff: { type: "boolean", description: "Include git diff output (slow)." }
+          },
+          required: [ "endpoint", "id" ]
+        )
+
+        class << self
+          def call(endpoint:, id:, include_diff: false, server_context: nil)
+            client = ApiClient.for(endpoint)
+            deploy = client.detail(id)
+            text   = format_detail(deploy)
+            text  += "\n\n" + client.diff(deploy["sha"]) if include_diff
+            ::MCP::Tool::Response.new([ { type: "text", text: text } ])
+          end
+
+          private
+
+          def format_detail(d)
+            lines = []
+            lines << "Deploy #{d["id"]} on #{d["endpoint"]}"
+            lines << "SHA:      #{d["sha"]} (prev: #{d["previous_sha"]})"
+            lines << "Branch:   #{d["branch"]}  Author: #{d["author"]}"
+            lines << "Status:   #{d["status"]}  Kind: #{d["kind"]}"
+            lines << "Time:     #{d["started_at"]} → #{d["finished_at"]} (#{d["duration_seconds"]}s)"
+            lines << "Reverts:  deploy ##{d["reverts_deploy_id"]}" if d["reverts_deploy_id"]
+            lines << ""
+            lines << "Commits (#{Array(d["commits"]).size}):"
+            Array(d["commits"]).each do |c|
+              lines << "  #{c["sha"].to_s[0, 8]} #{c["author"]} — #{c["message"]}"
+            end
+            lines << ""
+            lines << "Changed files (#{Array(d["changed_files"]).size}):"
+            Array(d["changed_files"]).each do |f|
+              lines << "  #{f["change_type"]} #{f["path"]}"
+            end
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crumb/mcp/tools/find_deploys_touching.rb

@@ -0,0 +1,46 @@
+module Crumb
+  module MCP
+    module Tools
+      class FindDeploysTouchingTool < ::MCP::Tool
+        tool_name "find_deploys_touching"
+        description "Find deploys that touched files matching a path prefix. Fast via indexed DB query."
+        input_schema(
+          properties: {
+            path_prefix: { type: "string",  description: "Path prefix to match (e.g. 'app/models/order')." },
+            endpoint:    { type: "string",  description: "Endpoint slug. Omit to query all endpoints." },
+            limit:       { type: "integer", description: "Max results per endpoint (default 20)." }
+          },
+          required: [ "path_prefix" ]
+        )
+
+        class << self
+          def call(path_prefix:, endpoint: nil, limit: 20, server_context: nil)
+            slugs   = endpoint ? [ endpoint ] : Registry.all_slugs
+            deploys = []
+            errors  = []
+
+            slugs.each do |slug|
+              deploys.concat(ApiClient.for(slug).touching(path_prefix, limit: limit))
+            rescue => e
+              errors << "[#{slug}] error: #{e.message}"
+            end
+
+            deploys.sort_by! { |d| d["finished_at"].to_s }.reverse!
+
+            text =
+              if deploys.empty?
+                "No deploys found touching '#{path_prefix}'."
+              else
+                "Deploys touching '#{path_prefix}':\n\n" + deploys.map do |d|
+                  "[#{d["endpoint"]}] ##{d["id"]} #{d["sha"].to_s[0, 8]} by #{d["author"]} on #{d["finished_at"]}"
+                end.join("\n")
+              end
+            text += "\n\n" + errors.join("\n") unless errors.empty?
+
+            ::MCP::Tool::Response.new([ { type: "text", text: text } ])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crumb/mcp/tools/recent_deploys.rb

@@ -0,0 +1,47 @@
+module Crumb
+  module MCP
+    module Tools
+      class RecentDeploysTool < ::MCP::Tool
+        tool_name "recent_deploys"
+        description "List recent deployments. Omit `endpoint` to query all configured endpoints."
+        input_schema(
+          properties: {
+            endpoint: { type: "string", description: "Endpoint slug (e.g. my-app). Omit for all." },
+            limit:    { type: "integer", description: "Max results per endpoint (default 20)." }
+          }
+        )
+
+        class << self
+          def call(endpoint: nil, limit: 20, server_context: nil)
+            slugs   = endpoint ? [ endpoint ] : Registry.all_slugs
+            deploys = []
+            errors  = []
+
+            slugs.each do |slug|
+              deploys.concat(ApiClient.for(slug).recent(limit: limit))
+            rescue => e
+              errors << "[#{slug}] error: #{e.message}"
+            end
+
+            deploys.sort_by! { |d| d["finished_at"].to_s }.reverse!
+
+            text  = format_deploys(deploys)
+            text += "\n\n" + errors.join("\n") unless errors.empty?
+            ::MCP::Tool::Response.new([ { type: "text", text: text } ])
+          end
+
+          private
+
+          def format_deploys(deploys)
+            return "No deployments found." if deploys.empty?
+            deploys.map do |d|
+              "[#{d["endpoint"]}] ##{d["id"]} #{d["sha"].to_s[0, 8]} — #{d["branch"]} by #{d["author"]} " \
+                "(#{d["status"]}, #{d["duration_seconds"]}s) #{d["finished_at"]} " \
+                "[#{d["commit_count"]} commits, #{d["changed_file_count"]} files]"
+            end.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/crumb/mcp/version.rb

@@ -0,0 +1,5 @@
+module Crumb
+  module MCP
+    VERSION = "0.1.0"
+  end
+end

data/lib/crumb/mcp.rb

@@ -0,0 +1,9 @@
+require "mcp"
+
+require_relative "mcp/version"
+require_relative "mcp/registry"
+require_relative "mcp/api_client"
+require_relative "mcp/tools/recent_deploys"
+require_relative "mcp/tools/deploy_details"
+require_relative "mcp/tools/compare_deploys"
+require_relative "mcp/tools/find_deploys_touching"

data/lib/crumb-mcp.rb

@@ -0,0 +1 @@
+require_relative "crumb/mcp"

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: crumb-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nico Galdamez
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Standalone MCP server that federates across Crumb-enabled endpoints and
+  exposes deploy history as LLM tools.
+email:
+- nicogaldamez@gmail.com
+executables:
+- crumb-mcp
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/crumb-mcp
+- lib/crumb-mcp.rb
+- lib/crumb/mcp.rb
+- lib/crumb/mcp/api_client.rb
+- lib/crumb/mcp/registry.rb
+- lib/crumb/mcp/tools/compare_deploys.rb
+- lib/crumb/mcp/tools/deploy_details.rb
+- lib/crumb/mcp/tools/find_deploys_touching.rb
+- lib/crumb/mcp/tools/recent_deploys.rb
+- lib/crumb/mcp/version.rb
+homepage: https://github.com/nicogaldamez/crumb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nicogaldamez/crumb
+  source_code_uri: https://github.com/nicogaldamez/crumb/tree/main/mcp
+  changelog_uri: https://github.com/nicogaldamez/crumb/blob/main/mcp/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: MCP server for Crumb deployment observability.
+test_files: []