firestore-https-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2a2f507167e36197b1f31f02abe19759531f8115c22f225e3a4ee1c1186a555
+  data.tar.gz: 7cb925baacab72c49c5a7c9a9e742d54b76c115bcbba99719e96d5ac3ce5393a
+SHA512:
+  metadata.gz: 2f8aae71fd7d00a23107f6f3e47faece9ad4e0eeae1caedbc23c43eba2b1fc8f11b379596b699dc0edb91f5bb3336bc4158b9b45a89d2502cff88cea23b32920
+  data.tar.gz: 6e655a335e5e4d828db85f3687b260ee86556b1f01c05688dbb1cd2b680aa279dd9715c8cc3cb99bd48599e0cd904aaa106a59f1db163487adfbe1e434f7d2b1

data/GEMINI.md

@@ -0,0 +1,75 @@
+# Gemini Code Assistant Context
+
+This document provides context for the Gemini Code Assistant to understand the project and assist in development.
+
+## Project Overview
+
+This is a **Ruby based Model Context Protocol (MCP) server**. It is designed to expose tools over a streaming HTTP transport for integration with MCP clients (such as Claude Desktop or Gemini clients).
+
+## Key Technologies
+
+*   **Language:** Ruby
+*   **SDK:** `mcp` (Model Context Protocol SDK)
+    https://github.com/modelcontextprotocol/ruby-sdk
+*   **Database:** Google Cloud Firestore
+*   **Server:** Puma (via Rack)
+
+## Project Structure
+
+*   `main.rb`: Main entry point (Ruby). Registers tools, initializes Firestore, and starts the HTTP transport using Puma.
+*   `Makefile`: Development shortcuts (test, lint, clean).
+*   `spec/`: Contains test files.
+
+## Ruby MCP Best Practices
+
+*   **Logging:** Always log to `stderr` (e.g., `LOGGER = Logger.new($stderr)`).
+*   **Tool Definition:**
+    *   Inherit from `MCP::Tool`.
+    *   Define `description` and `input_schema`.
+    *   Implement the logic in a class method `self.call`.
+    *   Return an `MCP::Tool::Response` containing an array of content blocks (e.g., `{ type: 'text', text: '...' }`).
+*   **Modularity:** For larger projects, keep tools in separate files. In this project, they are currently in `main.rb` for simplicity.
+*   **Error Handling:** Wrap tool logic in `begin...rescue` blocks or check pre-requisites (like database connectivity) to return meaningful error messages to the client.
+*   **Environment Variables:** Use `dotenv` for local development. Ensure sensitive credentials are never committed.
+
+## Firestore Integration
+
+*   **Client:** Uses the `google-cloud-firestore` gem.
+*   **Collection:** The primary collection used is `inventory`.
+*   **Schema (Inventory):**
+    *   `name` (String)
+    *   `price` (Number)
+    *   `quantity` (Number)
+    *   `imgfile` (String)
+    *   `timestamp` (Timestamp)
+    *   `actualdateadded` (Timestamp)
+*   **Operations:**
+    *   `seed`: Populates the database with sample data.
+    *   `reset`: Clears the `inventory` collection.
+    *   `get_products`: Retrieves all items.
+    *   `get_product_by_id`: Retrieves a specific item by document ID.
+    *   `get_root`: Returns a welcome message.
+    *   `check_db`: Checks database connectivity.
+
+## Development Setup
+
+1.  **Install Dependencies:**
+    ```bash
+    bundle install
+    ```
+2.  **Environment Variables:** Create a `.env` file with necessary Google Cloud credentials if not using default application credentials.
+
+## Running the Server
+
+The server is configured to run using a streaming HTTP transport on port 8080.
+
+```bash
+bundle exec ruby main.rb
+```
+
+*Note: Since this is an MCP server, it is typically spawned or connected to by an MCP client.*
+
+## Ruby MCP Developer Resources
+
+*   **MCP Ruby SDK (GitHub):** [https://github.com/modelcontextprotocol/ruby-sdk](https://github.com/modelcontextprotocol/ruby-sdk)
+*   **Model Context Protocol Documentation:** [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)

data/README.md

@@ -0,0 +1,85 @@
+# Firestore Inventory MCP Server (Ruby)
+
+A Ruby implementation of a **Model Context Protocol (MCP)** server that connects to **Google Cloud Firestore**. This server exposes tools to manage and inspect a "Cymbal Superstore" inventory database over a streaming HTTP transport.
+
+It is designed to be used with MCP clients (like Claude Desktop or Gemini Code Assist) to enable LLMs to interact with your Firestore data.
+
+## Features & Tools
+
+This server provides the following MCP tools:
+
+*   **`get_root`**: Returns a welcome message and confirms the server is reachable.
+*   **`check_db`**: Checks the connectivity status of the Firestore database.
+*   **`get_products`**: Retrieves the full list of products from the inventory.
+*   **`get_product_by_id`**: Fetches details for a specific product using its document ID.
+*   **`seed`**: Populates the Firestore `inventory` collection with sample data (useful for demos/testing).
+*   **`reset`**: Clears all documents from the `inventory` collection.
+
+## Prerequisites
+
+*   **Ruby 3.0+**
+*   **Google Cloud Project**: You need a Google Cloud project with Firestore enabled.
+*   **Authentication**: The environment where this server runs must be authenticated with Google Cloud.
+    *   Locally, you can use `gcloud auth application-default login`.
+    *   Or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key JSON file.
+
+## Setup
+
+1.  **Clone the repository**:
+    ```bash
+    git clone <your-repo-url>
+    cd firestore-https-ruby
+    ```
+
+2.  **Install Dependencies**:
+    ```bash
+    bundle install
+    ```
+
+3.  **Configure Environment**:
+    Create a `.env` file if you need to load specific environment variables (handled by `dotenv`).
+
+## Running the Server
+
+This server communicates over **HTTP** using Server-Sent Events (SSE). It is not meant to be run manually in a terminal for human interaction, but rather spawned or connected to by an MCP client.
+
+To start the server:
+
+```bash
+bundle exec ruby main.rb
+```
+
+The server will start on port 8080 (by default).
+
+### Integration with MCP Clients
+
+Configure your MCP client to connect to the server's HTTP endpoint or run it as a command if the client supports it. For example:
+
+**Command:** `bundle`
+**Args:** `['exec', 'ruby', '/path/to/firestore-https-ruby/main.rb']`
+
+## Development
+
+### Testing
+
+Run the test suite using RSpec:
+
+```bash
+bundle exec rspec
+```
+
+### Linting
+
+Check code style with RuboCop:
+
+```bash
+bundle exec rubocop
+```
+
+### Building the Gem
+
+This project can also be built as a Ruby gem:
+
+```bash
+gem build firestore-mcp-server.gemspec
+```

data/lib/mcp_server/config.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'time'
+require 'json'
+require 'google/cloud/firestore'
+
+module MCPServer
+  # Configuration and initialization for the MCP server.
+  module Config
+    LOGGER = Logger.new($stderr)
+    LOGGER.level = Logger::INFO
+    LOGGER.formatter = proc do |severity, datetime, _progname, msg|
+      log_entry = {
+        timestamp: datetime.iso8601,
+        level: severity
+      }
+      if msg.is_a?(Hash)
+        log_entry.merge!(msg)
+      else
+        log_entry[:message] = msg.to_s
+      end
+      "#{log_entry.to_json}\n"
+    end
+
+    def self.logger
+      LOGGER
+    end
+
+    def self.firestore
+      @firestore
+    end
+
+    def self.db_running?
+      @db_running
+    end
+
+    def self.init_firestore
+      @firestore = Google::Cloud::Firestore.new
+      @db_running = true
+      logger.info 'Firestore client initialized'
+    rescue StandardError => e
+      logger.error "Failed to initialize Firestore: #{e.message}"
+      @db_running = false
+    end
+  end
+end

data/lib/mcp_server/database_helper.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+
+module MCPServer
+  # Helper class for database operations.
+  class DatabaseHelper
+    def self.doc_to_product(doc)
+      data = doc.data
+      {
+        id: doc.document_id,
+        name: data[:name],
+        price: data[:price],
+        quantity: data[:quantity],
+        imgfile: data[:imgfile],
+        timestamp: data[:timestamp],
+        actualdateadded: data[:actualdateadded]
+      }
+    end
+
+    def self.add_or_update_firestore(product)
+      firestore = MCPServer::Config.firestore
+      query = firestore.col('inventory').where('name', '==', product[:name]).get
+
+      if query.empty?
+        firestore.col('inventory').add(product)
+      else
+        query.each do |doc|
+          doc.ref.update(product)
+        end
+      end
+    end
+
+    def self.seed_database
+      seed_old_products
+      seed_recent_products
+      seed_out_of_stock_products
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def self.seed_old_products
+      names = [
+        'Apples', 'Bananas', 'Milk', 'Whole Wheat Bread', 'Eggs', 'Cheddar Cheese',
+        'Whole Chicken', 'Rice', 'Black Beans', 'Bottled Water', 'Apple Juice',
+        'Cola', 'Coffee Beans', 'Green Tea', 'Watermelon', 'Broccoli',
+        'Jasmine Rice', 'Yogurt', 'Beef', 'Shrimp', 'Walnuts',
+        'Sunflower Seeds', 'Fresh Basil', 'Cinnamon'
+      ]
+
+      names.each do |name|
+        product = {
+          name: name,
+          price: rand(1..10),
+          quantity: rand(1..500),
+          imgfile: "product-images/#{name.gsub(/\s+/, '').downcase}.png",
+          timestamp: Time.now - rand(0..31_536_000) - 7_776_000,
+          actualdateadded: Time.now
+        }
+        MCPServer::Config.logger.info "⬆️ Adding (or updating) product in firestore: #{product[:name]}"
+        add_or_update_firestore(product)
+      end
+    end
+
+    def self.seed_recent_products
+      names = [
+        'Parmesan Crisps', 'Pineapple Kombucha', 'Maple Almond Butter',
+        'Mint Chocolate Cookies', 'White Chocolate Caramel Corn', 'Acai Smoothie Packs',
+        'Smores Cereal', 'Peanut Butter and Jelly Cups'
+      ]
+
+      names.each do |name|
+        product = {
+          name: name,
+          price: rand(1..10),
+          quantity: rand(1..100),
+          imgfile: "product-images/#{name.gsub(/\s+/, '').downcase}.png",
+          timestamp: Time.now - rand(0..518_400),
+          actualdateadded: Time.now
+        }
+        MCPServer::Config.logger.info "🆕 Adding (or updating) product in firestore: #{product[:name]}"
+        add_or_update_firestore(product)
+      end
+    end
+
+    def self.seed_out_of_stock_products
+      names = ['Wasabi Party Mix', 'Jalapeno Seasoning']
+
+      names.each do |name|
+        product = {
+          name: name,
+          price: rand(1..10),
+          quantity: 0,
+          imgfile: "product-images/#{name.gsub(/\s+/, '').downcase}.png",
+          timestamp: Time.now - rand(0..518_400),
+          actualdateadded: Time.now
+        }
+        MCPServer::Config.logger.info "😱 Adding (or updating) out of stock product in firestore: #{product[:name]}"
+        add_or_update_firestore(product)
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def self.clean_firestore_collection
+      MCPServer::Config.logger.info 'Cleaning Firestore collection...'
+      firestore = MCPServer::Config.firestore
+      snapshot = firestore.col('inventory').get
+      return if snapshot.empty?
+
+      batch = firestore.batch
+      snapshot.each_with_index do |doc, index|
+        batch.delete(doc.ref)
+        if ((index + 1) % 400).zero?
+          batch.commit
+          batch = firestore.batch
+        end
+      end
+      batch.commit if (snapshot.size % 400).positive?
+      MCPServer::Config.logger.info 'Firestore collection cleaned.'
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+  end
+end

data/lib/mcp_server/tools/check_db.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative '../config'
+
+module MCPServer
+  module Tools
+    # Tool to check if the database is running.
+    class CheckDb < MCP::Tool
+      description 'Checks if the inventory database is running.'
+      input_schema(type: 'object', properties: {})
+
+      def self.call(*)
+        MCP::Tool::Response.new(
+          [{ type: 'text', text: "Database running: #{MCPServer::Config.db_running?}" }]
+        )
+      end
+    end
+  end
+end

data/lib/mcp_server/tools/get_product_by_id.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'json'
+require_relative '../config'
+require_relative '../database_helper'
+
+module MCPServer
+  module Tools
+    # Tool to retrieve a specific product by its ID.
+    class GetProductById < MCP::Tool
+      description 'Get a single product from the inventory database by its ID'
+      input_schema(
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'The ID of the product to get' }
+        },
+        required: ['id']
+      )
+
+      def self.call(id:)
+        unless MCPServer::Config.db_running?
+          return MCP::Tool::Response.new([{ type: 'text', text: 'Database not running.' }], is_error: true)
+        end
+
+        doc = MCPServer::Config.firestore.col('inventory').doc(id).get
+        unless doc.exists?
+          return MCP::Tool::Response.new([{ type: 'text', text: 'Product not found.' }], is_error: true)
+        end
+
+        product = MCPServer::DatabaseHelper.doc_to_product(doc)
+        MCP::Tool::Response.new([{ type: 'text', text: JSON.pretty_generate(product) }])
+      end
+    end
+  end
+end

data/lib/mcp_server/tools/get_products.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'json'
+require_relative '../config'
+require_relative '../database_helper'
+
+module MCPServer
+  module Tools
+    # Tool to retrieve all products from the inventory.
+    class GetProducts < MCP::Tool
+      description 'Get a list of all products from the inventory database'
+      input_schema(type: 'object', properties: {})
+
+      def self.call(*)
+        unless MCPServer::Config.db_running?
+          return MCP::Tool::Response.new([{ type: 'text', text: 'Inventory database is not running.' }], is_error: true)
+        end
+
+        firestore = MCPServer::Config.firestore
+        products = firestore.col('inventory').get.map { |doc| MCPServer::DatabaseHelper.doc_to_product(doc) }
+        MCP::Tool::Response.new(
+          [{ type: 'text', text: JSON.pretty_generate(products) }]
+        )
+      end
+    end
+  end
+end

data/lib/mcp_server/tools/get_root.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'mcp'
+
+module MCPServer
+  module Tools
+    # Tool to get the root greeting.
+    class GetRoot < MCP::Tool
+      description 'Get a greeting from the Cymbal Superstore Inventory API.'
+      input_schema(type: 'object', properties: {})
+
+      def self.call(*)
+        MCP::Tool::Response.new(
+          [{ type: 'text', text: '🍎 Hello! This is the Cymbal Superstore Inventory API.' }]
+        )
+      end
+    end
+  end
+end

data/lib/mcp_server/tools/reset.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative '../config'
+require_relative '../database_helper'
+
+module MCPServer
+  module Tools
+    # Tool to reset the inventory database.
+    class Reset < MCP::Tool
+      description 'Clears all products from the inventory database.'
+      input_schema(type: 'object', properties: {})
+
+      def self.call(*)
+        unless MCPServer::Config.db_running?
+          return MCP::Tool::Response.new([{ type: 'text', text: 'Inventory database is not running.' }], is_error: true)
+        end
+
+        MCPServer::DatabaseHelper.clean_firestore_collection
+        MCP::Tool::Response.new(
+          [{ type: 'text', text: 'Database reset successfully.' }]
+        )
+      end
+    end
+  end
+end

data/lib/mcp_server/tools/seed.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative '../config'
+require_relative '../database_helper'
+
+module MCPServer
+  module Tools
+    # Tool to seed the inventory database.
+    class Seed < MCP::Tool
+      description 'Seed the inventory database with products.'
+      input_schema(type: 'object', properties: {})
+
+      def self.call(*)
+        unless MCPServer::Config.db_running?
+          return MCP::Tool::Response.new([{ type: 'text', text: 'Inventory database is not running.' }], is_error: true)
+        end
+
+        MCPServer::DatabaseHelper.seed_database
+        MCP::Tool::Response.new(
+          [{ type: 'text', text: 'Database seeded successfully.' }]
+        )
+      end
+    end
+  end
+end

data/main.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Redirect stdout to stderr to ensure all output goes to stderr immediately
+$stdout.reopen($stderr)
+
+require 'mcp'
+require 'rack'
+require 'rackup'
+require 'json'
+require 'puma'
+require 'dotenv/load'
+
+require_relative 'lib/mcp_server/config'
+require_relative 'lib/mcp_server/database_helper'
+require_relative 'lib/mcp_server/tools/get_products'
+require_relative 'lib/mcp_server/tools/get_product_by_id'
+require_relative 'lib/mcp_server/tools/seed'
+require_relative 'lib/mcp_server/tools/reset'
+require_relative 'lib/mcp_server/tools/get_root'
+require_relative 'lib/mcp_server/tools/check_db'
+
+# Initialize Configuration and Firestore
+MCPServer::Config.init_firestore
+LOGGER = MCPServer::Config.logger
+
+# Configure MCP
+MCP.configure do |config|
+  config.protocol_version = '2024-11-05'
+end
+
+# Custom transport to fix response format for SSE
+class FixedStreamableHTTPTransport < MCP::Server::Transports::StreamableHTTPTransport
+  private
+
+  def send_response_to_stream(stream, response, _session_id)
+    message = JSON.parse(response)
+    send_to_stream(stream, message)
+    [202, {}, []]
+  end
+end
+
+# Middleware for JSON request logging
+class JsonRequestLogger
+  def initialize(app, logger)
+    @app = app
+    @logger = logger
+  end
+
+  def call(env)
+    status, headers, body = @app.call(env)
+    @logger.info(
+      type: 'request',
+      method: env['REQUEST_METHOD'],
+      path: env['PATH_INFO'],
+      status: status,
+      remote_addr: env['REMOTE_ADDR']
+    )
+    [status, headers, body]
+  end
+end
+
+# Initialize MCP Server
+server = MCP::Server.new(
+  name: 'inventory-server',
+  version: '1.0.0',
+  tools: [
+    MCPServer::Tools::GetProducts,
+    MCPServer::Tools::GetProductById,
+    MCPServer::Tools::Seed,
+    MCPServer::Tools::Reset,
+    MCPServer::Tools::GetRoot,
+    MCPServer::Tools::CheckDb
+  ]
+)
+
+# Create the Fixed Streamable HTTP transport
+transport = FixedStreamableHTTPTransport.new(server)
+server.transport = transport
+
+# Create the Rack application
+base_app = proc do |env|
+  request = Rack::Request.new(env)
+  transport.handle_request(request)
+end
+
+# Wrap with JSON logger
+app = JsonRequestLogger.new(base_app, LOGGER)
+
+# Run the server using streaming HTTP transport
+if __FILE__ == $PROGRAM_NAME
+  begin
+    port = ENV.fetch('PORT', 8080).to_i
+    LOGGER.info "Starting MCP server: #{server.name} (v#{server.version}) on HTTP port #{port}"
+    Rackup::Handler.get('puma').run(app, Port: port, Host: '0.0.0.0', Quiet: true)
+  rescue Interrupt
+    LOGGER.info 'Shutting down MCP server...'
+    transport.close
+  rescue StandardError => e
+    LOGGER.error(message: "Server error: #{e.message}", backtrace: e.backtrace)
+    exit 1
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: firestore-https-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- xbill
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: Exposes Firestore operations (inventory management) as MCP tools over
+  stdio.
+email:
+- xbill9@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- GEMINI.md
+- README.md
+- lib/mcp_server/config.rb
+- lib/mcp_server/database_helper.rb
+- lib/mcp_server/tools/check_db.rb
+- lib/mcp_server/tools/get_product_by_id.rb
+- lib/mcp_server/tools/get_products.rb
+- lib/mcp_server/tools/get_root.rb
+- lib/mcp_server/tools/reset.rb
+- lib/mcp_server/tools/seed.rb
+- main.rb
+homepage: https://github.com/xbill9/gemini-cli-codeassist/firestore-https-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/xbill9/gemini-cli-codeassist/firestore-https-ruby
+  source_code_uri: https://github.com/xbill9/gemini-cli-codeassist/firestore-https-ruby
+  bug_tracker_uri: https://github.com/xbill9/gemini-cli-codeassist/firestore-https-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Model Context Protocol (MCP) server for Google Cloud Firestore.
+test_files: []