firestore-mcp-server 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2a58dc40cd41de1247e8fe51f11b7be2599e14ae664a0a31f5a2795e700e362
+  data.tar.gz: de4d5c7f6e3c82e438dcadfb399b0ee278b77aa7b6449dac9891e948d2f16188
+SHA512:
+  metadata.gz: 0f70c698bc793104fddba57cf80d7bcbf9cd8e82bea532af4a392bd25ebba24866e7a4d5db1776cf808f5350c38c5c204d14eae4899a3d69e51be17b2cea5af1
+  data.tar.gz: 53f7c5d2ba45e26ed422d57f9ededb1eb4757795c1779118907b294e61c8882f743e7c9a4f1cf4ea508face2c2c45ce0df1864a03f590e9efc3848051cc55e8f

data/GEMINI.md

@@ -0,0 +1,74 @@
+# 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 (like `greet`) over standard input/output (stdio) 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
+
+## Project Structure
+
+*   `main.rb`: Main entry point (Ruby). Registers tools and starts the stdio transport.
+*   `lib/`: Contains tool definitions and the Firestore client.
+    *   `firestore_client.rb`: Singleton client for Firestore interactions.
+    *   `*_tool.rb`: Individual tool implementations.
+*   `Makefile`: Development shortcuts (test, lint, clean).
+
+## Ruby MCP Best Practices
+
+*   **Logging:** Always log to `stderr` (e.g., `Logger.new($stderr)`). `stdout` is exclusively used for MCP JSON-RPC communication.
+*   **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:** Keep tools in separate files under `lib/` to maintain a clean `main.rb`.
+*   **Error Handling:** Wrap tool logic in `begin...rescue` blocks to return meaningful error messages to the client instead of crashing the server.
+*   **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.
+
+## 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 the `stdio` transport.
+
+```bash
+bundle exec ruby main.rb
+```
+
+*Note: Since this is an MCP server running over stdio, it is typically not run directly by a human but rather spawned 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,84 @@
+# 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 standard input/output (stdio) 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.
+*   **`greet`**: A simple echo utility for testing basic tool invocation.
+
+## 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-stdio-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 **stdio**. It is not meant to be run manually in a terminal for human interaction, but rather spawned by an MCP client.
+
+To test that it starts up correctly (you'll see a log message on stderr, but it will hang waiting for stdin):
+
+```bash
+bundle exec ruby main.rb
+```
+
+### Integration with MCP Clients
+
+Configure your MCP client to run the server. For example:
+
+**Command:** `bundle`
+**Args:** `['exec', 'ruby', '/path/to/firestore-stdio-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/check_db_tool.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative 'firestore_client'
+
+# Tool to check if the Firestore database is accessible.
+class CheckDbTool < MCP::Tool
+  tool_name 'check_db'
+  description 'Checks if the inventory database is running.'
+  input_schema(type: 'object', properties: {})
+
+  class << self
+    def call(*)
+      client = FirestoreClient.instance
+      running = client.db_running
+      MCP::Tool::Response.new(
+        [{ type: 'text', text: "Database running: #{running}" }]
+      )
+    end
+  end
+end

data/lib/firestore_client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'google/cloud/firestore'
+require 'dotenv/load'
+require_relative 'inventory_data'
+require_relative 'firestore_seeder'
+
+# Client for interacting with Google Cloud Firestore for inventory management.
+class FirestoreClient
+  include InventoryData
+  include FirestoreSeeder
+
+  attr_reader :client, :db_running
+
+  def initialize
+    # Assuming environment variables for auth are set or will be handled by library defaults
+    @client = Google::Cloud::Firestore.new
+    @db_running = true
+    LOGGER.info 'Firestore client initialized' if defined?(LOGGER)
+  rescue StandardError => e
+    LOGGER.error "Failed to initialize Firestore: #{e.message}" if defined?(LOGGER)
+    @db_running = false
+    @client = nil
+  end
+
+  def self.instance
+    @instance ||= new
+  end
+
+  def products
+    return [] unless @db_running
+
+    products = @client.col('inventory').get
+    products.map { |doc| doc_to_product(doc) }
+  end
+
+  def product_by_id(id)
+    return nil unless @db_running
+
+    doc = @client.col('inventory').doc(id).get
+    return nil unless doc.exists?
+
+    doc_to_product(doc)
+  end
+
+  def reset
+    return unless @db_running
+
+    clean_firestore_collection
+  end
+
+  private
+
+  def 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 clean_firestore_collection
+    LOGGER.info 'Cleaning Firestore collection...' if defined?(LOGGER)
+    snapshot = @client.col('inventory').get
+    batch_delete(snapshot) unless snapshot.empty?
+    LOGGER.info 'Firestore collection cleaned.' if defined?(LOGGER)
+  end
+
+  def batch_delete(snapshot)
+    batch = @client.batch
+    snapshot.each_with_index do |doc, i|
+      batch.delete(doc.ref)
+      if ((i + 1) % 400).zero?
+        batch.commit
+        batch = @client.batch
+      end
+    end
+    batch.commit unless (snapshot.size % 400).zero?
+  end
+end

data/lib/firestore_seeder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'inventory_data'
+
+# Module for seeding Firestore collection with sample data.
+module FirestoreSeeder
+  include InventoryData
+
+  def seed
+    return unless @db_running
+
+    seed_old_products
+    seed_recent_products
+    seed_out_of_stock_products
+  end
+
+  private
+
+  def seed_old_products
+    OLD_PRODUCTS.each do |name|
+      data = {
+        name: name, price: rand(1..10), quantity: rand(1..500),
+        imgfile: "product-images/#{name.gsub(/\s/, '').downcase}.png",
+        timestamp: Time.now - rand(7_776_000_000..31_536_000_000), actualdateadded: Time.now
+      }
+      LOGGER.info "⬆️ Adding: #{name}" if defined?(LOGGER)
+      add_or_update_firestore(data)
+    end
+  end
+
+  def seed_recent_products
+    RECENT_PRODUCTS.each do |name|
+      data = {
+        name: name, price: rand(1..10), quantity: rand(1..100),
+        imgfile: "product-images/#{name.gsub(/\s/, '').downcase}.png",
+        timestamp: Time.now - rand(1..518_400_000), actualdateadded: Time.now
+      }
+      LOGGER.info "🆕 Adding: #{name}" if defined?(LOGGER)
+      add_or_update_firestore(data)
+    end
+  end
+
+  def seed_out_of_stock_products
+    RECENT_PRODUCTS_OUT_OF_STOCK.each do |name|
+      data = {
+        name: name, price: rand(1..10), quantity: 0,
+        imgfile: "product-images/#{name.gsub(/\s/, '').downcase}.png",
+        timestamp: Time.now - rand(1..518_400_000), actualdateadded: Time.now
+      }
+      LOGGER.info "😱 Adding OOS: #{name}" if defined?(LOGGER)
+      add_or_update_firestore(data)
+    end
+  end
+
+  def add_or_update_firestore(product)
+    query = @client.col('inventory').where('name', '=', product[:name]).get
+
+    if query.empty?
+      @client.col('inventory').add(product)
+    else
+      query.each { |doc| doc.ref.update(product) }
+    end
+  end
+end

data/lib/get_product_by_id_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative 'firestore_client'
+require 'json'
+
+# Tool to retrieve a specific product by its ID from Firestore.
+class GetProductByIdTool < MCP::Tool
+  tool_name 'get_product_by_id'
+  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']
+  )
+
+  class << self
+    def call(id:)
+      client = FirestoreClient.instance
+      return db_not_running_response unless client.db_running
+
+      product = client.product_by_id(id)
+      return product_not_found_response if product.nil?
+
+      MCP::Tool::Response.new([{ type: 'text', text: JSON.pretty_generate(product) }])
+    end
+
+    private
+
+    def db_not_running_response
+      MCP::Tool::Response.new([{ type: 'text', text: 'Inventory database is not running.' }])
+    end
+
+    def product_not_found_response
+      MCP::Tool::Response.new([{ type: 'text', text: 'Product not found.' }])
+    end
+  end
+end

data/lib/get_products_tool.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative 'firestore_client'
+require 'json'
+
+# Tool to retrieve all products from Firestore.
+class GetProductsTool < MCP::Tool
+  tool_name 'get_products'
+  description 'Get a list of all products from the inventory database'
+  input_schema(type: 'object', properties: {})
+
+  class << self
+    def call
+      client = FirestoreClient.instance
+      if client.db_running
+        products = client.products
+        [{ type: 'text', text: products.to_json }]
+      else
+        [{ type: 'text', text: 'Inventory database is not running.' }]
+      end
+    end
+  end
+end

data/lib/get_root_tool.rb

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

data/lib/greet_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'mcp'
+
+# Define the greet tool
+class GreetTool < MCP::Tool
+  tool_name 'greet'
+  description 'Get a greeting from a local stdio server.'
+  input_schema(
+    type: 'object',
+    properties: {
+      message: {
+        type: 'string',
+        description: 'The message to repeat.'
+      }
+    },
+    required: ['message']
+  )
+
+  class << self
+    def call(message:)
+      LOGGER.info "GreetTool called with message: #{message}" if defined?(LOGGER)
+      MCP::Tool::Response.new(
+        [
+          {
+            type: 'text',
+            text: message
+          }
+        ]
+      )
+    end
+  end
+end

data/lib/inventory_data.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module InventoryData
+  OLD_PRODUCTS = [
+    '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'
+  ].freeze
+
+  RECENT_PRODUCTS = [
+    'Parmesan Crisps', 'Pineapple Kombucha', 'Maple Almond Butter',
+    'Mint Chocolate Cookies', 'White Chocolate Caramel Corn', 'Acai Smoothie Packs',
+    'Smores Cereal', 'Peanut Butter and Jelly Cups'
+  ].freeze
+
+  RECENT_PRODUCTS_OUT_OF_STOCK = ['Wasabi Party Mix', 'Jalapeno Seasoning'].freeze
+end

data/lib/reset_tool.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative 'firestore_client'
+
+# Tool to clear all products from the Firestore collection.
+class ResetTool < MCP::Tool
+  tool_name 'reset'
+  description 'Clears all products from the inventory database.'
+  input_schema(type: 'object', properties: {})
+
+  class << self
+    def call(*)
+      client = FirestoreClient.instance
+      unless client.db_running
+        return MCP::Tool::Response.new(
+          [{ type: 'text', text: 'Inventory database is not running.' }]
+        )
+      end
+
+      client.reset
+      MCP::Tool::Response.new(
+        [{ type: 'text', text: 'Database reset successfully.' }]
+      )
+    end
+  end
+end

data/lib/seed_tool.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require_relative 'firestore_client'
+
+# Tool to seed the Firestore collection with sample products.
+class SeedTool < MCP::Tool
+  tool_name 'seed'
+  description 'Seed the inventory database with products.'
+  input_schema(type: 'object', properties: {})
+
+  class << self
+    def call(*)
+      client = FirestoreClient.instance
+      unless client.db_running
+        return MCP::Tool::Response.new(
+          [{ type: 'text', text: 'Inventory database is not running.' }]
+        )
+      end
+
+      client.seed
+      MCP::Tool::Response.new(
+        [{ type: 'text', text: 'Database seeded successfully.' }]
+      )
+    end
+  end
+end

data/main.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'mcp'
+require 'logger'
+require 'json'
+require_relative 'lib/greet_tool'
+require_relative 'lib/get_products_tool'
+require_relative 'lib/get_product_by_id_tool'
+require_relative 'lib/seed_tool'
+require_relative 'lib/reset_tool'
+require_relative 'lib/check_db_tool'
+require_relative 'lib/get_root_tool'
+require_relative 'lib/firestore_client'
+
+# Set up logging to stderr
+# We use stderr because stdout is used for MCP protocol communication
+LOGGER = Logger.new($stderr)
+LOGGER.formatter = proc do |severity, datetime, progname, msg|
+  "#{({
+    severity: severity,
+    timestamp: datetime.iso8601,
+    progname: progname,
+    message: msg
+  }.to_json)}\n"
+end
+LOGGER.level = Logger::INFO
+
+# Initialize Firestore Client
+FirestoreClient.instance
+
+# Initialize MCP Server
+server = MCP::Server.new(
+  name: 'inventory-server',
+  version: '1.0.0',
+  tools: [
+    GreetTool,
+    GetProductsTool,
+    GetProductByIdTool,
+    SeedTool,
+    ResetTool,
+    CheckDbTool,
+    GetRootTool
+  ]
+)
+
+# Run the server using stdio transport
+if __FILE__ == $PROGRAM_NAME
+  begin
+    LOGGER.info "Starting MCP server: #{server.name} (v#{server.version})"
+    transport = MCP::Server::Transports::StdioTransport.new(server)
+    transport.open
+  rescue Interrupt
+    LOGGER.info 'Shutting down MCP server...'
+  rescue StandardError => e
+    LOGGER.error "Server error: #{e.message}"
+    LOGGER.error e.backtrace.join("\n")
+    exit 1
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: firestore-mcp-server
+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/check_db_tool.rb
+- lib/firestore_client.rb
+- lib/firestore_seeder.rb
+- lib/get_product_by_id_tool.rb
+- lib/get_products_tool.rb
+- lib/get_root_tool.rb
+- lib/greet_tool.rb
+- lib/inventory_data.rb
+- lib/reset_tool.rb
+- lib/seed_tool.rb
+- main.rb
+homepage: https://github.com/xbill9/gemini-cli-codeassist/firestore-mcp-server
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/xbill9/gemini-cli-codeassist/firestore-mcp-server
+  source_code_uri: https://github.com/xbill9/gemini-cli-codeassist/firestore-mcp-server
+  bug_tracker_uri: https://github.com/xbill9/gemini-cli-codeassist/firestore-mcp-server/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: []