hotwire_club-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57446ec06e4bcaf140824c61878fb0722ebde8a71bababe3eb55eab7d79e1a61
+  data.tar.gz: a59948add0b83f1eca7a95179c3dd8fc3e9a812082b60039803c8877a8daca40
+SHA512:
+  metadata.gz: bc49883004dbefadacdc9b573cd0ed1795732306ea22edcfcd4c49a806235d52484c1feb38fb6b43d33990a105397515313ff882b25268a923da316adf11a3a6
+  data.tar.gz: 794e37882e4d1114561cac68373d1725a9327c063cd418cd55ab56ce400ba509e3f42702efe7f1e803239b0f940d27fb0ab6b06f6e9e88a9223befc593c64494

data/.rubocop.yml

@@ -0,0 +1,195 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'db/**/*'
+    - 'bin/**/*'
+    - 'exe/**/*'
+    - '*.gemspec'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - '*.gemspec'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'test/**/*'
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 30
+  Exclude:
+    - 'test/**/*'
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Max: 200
+  Exclude:
+    - 'test/**/*'
+    - 'spec/**/*'
+
+Metrics/ModuleLength:
+  Max: 200
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/ParameterLists:
+  Max: 6
+
+Naming/FileName:
+  Exclude:
+    - '*.gemspec'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: aligned
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: nested
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+
+Style/GuardClause:
+  MinBodyLength: 3
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundMethodBody:
+  Enabled: false
+
+Layout/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: no_space
+
+Layout/SpaceInsideBlockBraces:
+  EnforcedStyle: space
+
+Style/BlockDelimiters:
+  EnforcedStyle: semantic
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/WordArray:
+  EnforcedStyle: brackets
+
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%': '()'
+    '%i': '()'
+    '%q': '()'
+    '%Q': '()'
+    '%r': '{}'
+    '%s': '()'
+    '%w': '()'
+    '%W': '()'
+    '%x': '()'
+
+Style/RegexpLiteral:
+  EnforcedStyle: percent_r
+
+Style/RedundantReturn:
+  AllowMultipleReturnValues: true
+
+Style/RedundantSelf:
+  Enabled: true
+
+Style/RescueModifier:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: true
+
+Style/Semicolon:
+  AllowAsExpressionSeparator: true
+
+Style/TrivialAccessors:
+  Enabled: false
+
+Style/YodaCondition:
+  Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  Enabled: false
+
+Lint/SuppressedException:
+  Enabled: false
+
+Lint/UselessAssignment:
+  Enabled: true
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Lint/UnusedBlockArgument:
+  AllowUnusedKeywordArguments: true
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - id
+    - to
+    - ok
+    - op
+    - io
+    - db
+
+Naming/VariableNumber:
+  Enabled: false
+
+Naming/BinaryOperatorParameterName:
+  Enabled: false
+

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-17
+
+### Added
+- Initial release of HotwireClub::MCP server
+- MCP tools for searching and browsing the Hotwire Club knowledge base:
+  - `SearchHwcKbTool` - Search the knowledge base for chunks matching a query
+  - `GetHwcKbChunkTool` - Get a single knowledge base chunk by its chunk_id
+  - `ListHwcKbCategoriesTool` - List all unique categories from the knowledge base
+  - `ListHwcKbTagsTool` - List all tags from the knowledge base
+  - `ListHwcKbDocsTool` - List documents from the knowledge base with optional filters
+  - `RelatedHwcKbDocsTool` - Find documents related to a given document or chunk based on category and tag overlap
+- SQLite database builder for converting markdown documents into a searchable knowledge base
+- Pre-built knowledge base database included in the gem
+- Support for Claude Desktop and Cursor MCP configuration
+- Full-text search using SQLite FTS5 with Porter stemming

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Julian Rubisch
+
+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,96 @@
+# HotwireClub::Mcp
+
+MCP server for Hotwire Club knowledge base - provides tools for searching, browsing, and discovering documentation from the Hotwire Club knowledge base.
+
+A Model Context Protocol (MCP) server that provides access to the Hotwire Club knowledge base. Builds a searchable SQLite database from markdown documents and exposes MCP tools for searching and browsing documentation, categories, tags, and documents.
+
+## Features
+
+The server provides the following MCP tools:
+
+- **SearchHwcKbTool** - Search the knowledge base for chunks matching a query with optional category and tag filters
+- **GetHwcKbChunkTool** - Retrieve a single knowledge base chunk by its chunk_id
+- **ListHwcKbCategoriesTool** - List all unique categories available in the knowledge base
+- **ListHwcKbTagsTool** - List all tags available in the knowledge base
+- **ListHwcKbDocsTool** - List documents with optional filtering by category and tags, with pagination support
+- **RelatedHwcKbDocsTool** - Find documents related to a given document or chunk based on shared categories and tags
+
+The knowledge base is pre-built and included in the gem, so no additional setup is required after installation.
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install hotwire_club-mcp
+```
+
+**Important:** After installing, if you're using `rbenv`, you might need to regenerate the shims so the `hwc-mcp` executable is available:
+
+```bash
+rbenv rehash
+```
+
+If you encounter an error like "cannot rehash: /Users/username/.rbenv/shims/.rbenv-shim exists", remove the lock file and try again:
+
+```bash
+rm -f ~/.rbenv/shims/.rbenv-shim
+rbenv rehash
+```
+
+## Requirements
+
+- Ruby 3.1.0 or higher
+- SQLite3
+
+## Usage
+
+Run the MCP server:
+
+```bash
+hwc-mcp
+```
+
+The server uses a pre-built SQLite database (`db/kb.sqlite`) that is included with the gem. No additional configuration or database setup is required.
+
+### Configuration
+
+#### Claude
+
+```json
+{
+  "mcpServers": {
+    "hotwire-club-mcp": {
+      "command": "hwc-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+#### Cursor
+
+```json
+{
+  "mcpServers": {
+    "hotwire-club-mcp": {
+      "command": "hwc-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/julianrubisch/hotwire_club-mcp.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: [:test, :standard]
+
+namespace :kb do
+  desc "Build the knowledge base from corpus directory"
+  task :build do
+    require_relative "lib/hotwire_club/mcp"
+
+    HotwireClub::MCP::Builder.run("corpus", "db/kb.sqlite")
+    puts "Knowledge base built successfully!"
+  end
+end
+
+# Hook kb:build into the build task
+Rake::Task[:build].enhance(["kb:build"])

data/exe/hwc-mcp

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Only use bundler/setup in development (when Gemfile exists in parent directory)
+# When installed as a gem, the Gemfile won't exist, so just require the gem directly
+gemfile_path = File.expand_path(File.join(__dir__, "..", "Gemfile"))
+if File.exist?(gemfile_path)
+  require "bundler/setup"
+end
+
+require "hotwire_club/mcp"
+
+# Find the database path:
+# 1. In development: look in current directory's db/ folder
+# 2. When installed as gem: look in gem's installation directory
+def find_database_path
+  # Check if we're in development (Gemfile exists)
+  gemfile_path = File.expand_path(File.join(__dir__, "..", "Gemfile"))
+  if File.exist?(gemfile_path)
+    # Development: use current directory
+    dev_db_path = File.join(Dir.pwd, "db", "kb.sqlite")
+    return dev_db_path if File.exist?(dev_db_path)
+  end
+
+  # Installed as gem: find gem root directory
+  # The executable is in exe/, so go up to gem root
+  gem_root = File.expand_path(File.join(__dir__, ".."))
+  gem_db_path = File.join(gem_root, "db", "kb.sqlite")
+  return gem_db_path if File.exist?(gem_db_path)
+
+  # Fallback to current directory (for backward compatibility)
+  File.join(Dir.pwd, "db", "kb.sqlite")
+end
+
+db_path = find_database_path
+database = HotwireClub::MCP::Database::Adapter.new(db_path: db_path)
+server = HotwireClub::MCP::Server.new(adapter: database)
+server.run

data/lib/hotwire_club/mcp/builder.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+require "date"
+require_relative "schema"
+require_relative "loader"
+require_relative "chunker"
+
+module HotwireClub
+  module MCP
+    # Builder class for knowledge base
+    class Builder
+      # Build the knowledge base from a corpus directory
+      #
+      # @param corpus_path [String] Path to the corpus directory
+      # @param db_path [String, nil] Optional database path (defaults to Schema::DB_PATH)
+      def self.run(corpus_path, db_path = nil)
+        db_path ||= Schema::DB_PATH
+
+        # 1. Create fresh database
+        Schema.create!(db_path)
+
+        # 2. Load documents
+        docs = Loader.load_docs(corpus_path)
+
+        # 3. Chunk documents
+        chunks = Chunker.chunk_docs(docs)
+
+        # 4. Insert into DB in one transaction
+        db = SQLite3::Database.new(db_path)
+
+        db.transaction do
+          insert_docs(db, docs)
+          insert_tags(db, docs)
+          insert_doc_tags(db, docs)
+          insert_chunks(db, chunks)
+        end
+
+        db.close
+      end
+
+      # Convert date to string format for database storage
+      #
+      # @param date [Date, String, nil] Date value to convert
+      # @return [String, nil] ISO8601 formatted date string or original string/nil
+      def self.format_date_for_db(date)
+        return nil if date.nil?
+
+        if date.is_a?(Date)
+          date.iso8601
+        elsif date.is_a?(String)
+          date
+        else
+          date.to_s
+        end
+      end
+
+      # Insert documents into database
+      #
+      # @param db [SQLite3::Database] Database connection
+      # @param docs [Array<Doc>] Documents to insert
+      def self.insert_docs(db, docs)
+        docs.each do |doc|
+          date_value = format_date_for_db(doc.date)
+
+          db.execute(
+            "INSERT INTO docs (id, title, category, summary, body, date) VALUES (?, ?, ?, ?, ?, ?)",
+            [doc.id, doc.title, doc.category, doc.summary, doc.body, date_value],
+          )
+        end
+      end
+
+      # Insert unique tags into database
+      #
+      # @param db [SQLite3::Database] Database connection
+      # @param docs [Array<Doc>] Documents to extract tags from
+      def self.insert_tags(db, docs)
+        all_tags = docs.flat_map(&:tags).uniq
+
+        all_tags.each do |tag|
+          db.execute("INSERT OR IGNORE INTO tags (name) VALUES (?)", [tag])
+        end
+      end
+
+      # Insert document-tag relationships into database
+      #
+      # @param db [SQLite3::Database] Database connection
+      # @param docs [Array<Doc>] Documents to extract relationships from
+      def self.insert_doc_tags(db, docs)
+        docs.each do |doc|
+          doc.tags.each do |tag|
+            db.execute("INSERT INTO doc_tags (doc_id, tag) VALUES (?, ?)", [doc.id, tag])
+          end
+        end
+      end
+
+      # Insert chunks into database with comma-joined tags
+      #
+      # @param db [SQLite3::Database] Database connection
+      # @param chunks [Array<Chunk>] Chunks to insert
+      def self.insert_chunks(db, chunks)
+        chunks.each do |chunk|
+          comma_joined_tags = chunk.tags.join(",")
+          insert_sql = "INSERT INTO chunks (chunk_id, doc_id, title, text, category, tags, position) " \
+                       "VALUES (?, ?, ?, ?, ?, ?, ?)"
+
+          db.execute(
+            insert_sql,
+            [chunk.id, chunk.doc_id, chunk.title, chunk.text, chunk.category, comma_joined_tags, chunk.position],
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hotwire_club/mcp/chunk.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module HotwireClub
+  module MCP
+    # Data class representing a single chunk of a document
+    Chunk = Data.define(:id, :doc_id, :title, :category, :tags, :position, :text) {
+      # Create a chunk from a document section
+      #
+      # @param doc [Doc] The document this chunk belongs to
+      # @param section_idx [Integer] The index of the section within the document
+      # @param part_idx [Integer] The index of the part within the section (0 for first part)
+      # @param section_title [String, nil] The title of the section
+      # @param text [String] The text content of the chunk
+      # @param position [Integer] The position of the chunk within the document
+      # @return [Chunk] A new Chunk instance with generated ID
+      def self.create_from_section(doc:, section_idx:, part_idx:, section_title:, text:, position:)
+        chunk_id = build_chunk_id(doc.id, section_idx, part_idx)
+
+        new(
+          id:       chunk_id,
+          doc_id:   doc.id,
+          title:    section_title,
+          category: doc.category,
+          tags:     doc.tags,
+          position: position,
+          text:     text,
+        )
+      end
+
+      # Build chunk ID from document ID, section index, and part index
+      #
+      # @param doc_id [String] Document ID
+      # @param section_idx [Integer] Section index
+      # @param part_idx [Integer] Part index
+      # @return [String] Chunk ID
+      def self.build_chunk_id(doc_id, section_idx, part_idx)
+        if part_idx.zero?
+          "#{doc_id}#s#{section_idx}"
+        else
+          "#{doc_id}#s#{section_idx}-#{part_idx}"
+        end
+      end
+    }
+  end
+end