mcp_toolkit 0.3.0

data/lib/mcp_toolkit.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+# Stdlib + external gems the toolkit's own code calls. Zeitwerk autoloads the
+# gem's `lib/mcp_toolkit/**` tree, but NOT these third-party / stdlib constants,
+# so they are required here once (centralized) rather than scattered across the
+# subfiles that happen to touch them:
+#
+#   json          - JSON.parse / JSON.generate (introspection parse, tools, transport)
+#   digest        - Digest::SHA256 (introspection cache key)
+#   time          - Time.iso8601 / Time.parse (introspection expiry parsing)
+#   securerandom  - SecureRandom.uuid (Session ids)
+#   mcp           - the official MCP SDK (Server wraps it; Tools::Base subclasses MCP::Tool)
+#   active_support/concern - Transport::ControllerMethods is an includable concern
+#   active_support/cache   - the default MemoryStore cache_store
+#
+# `faraday` is the one exception: it is required alongside its sole owner,
+# Auth::AuthorityServerClient, which is the only object that builds an HTTP
+# connection.
+require "json"
+require "digest"
+require "time"
+require "securerandom"
+require "mcp"
+require "active_support/concern"
+require "active_support/cache"
+
+# External dependencies (NOT autoloaded by Zeitwerk — only the gem's own tree is).
+# ActiveSupport's specific core extensions are required up front (rather than full
+# Rails) so the gem works in any host. Each line below earns its place; they were
+# audited against actual usage:
+#
+#   object/blank             - blank? / present? / presence (used throughout)
+#   hash/keys                - deep_symbolize_keys (ListExecutor#initialize)
+#   array/wrap               - Array.wrap (Transport::ControllerMethods)
+#   enumerable               - compact_blank (ListExecutor#apply_ids)
+#   time/conversions         - Time#iso8601 (Serializer::Base timestamps;
+#                              Time.zone.parse in ListExecutor)
+#   date_time/conversions    - DateTime#iso8601 (token expires_at may be a DateTime)
+#   string/inflections       - String#pluralize (ResourceSchema resolves a link's
+#                              singular name to the plural registered resource name)
+require "active_support"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/array/wrap"
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/time/conversions"
+require "active_support/core_ext/date_time/conversions"
+require "active_support/core_ext/string/inflections"
+
+# The version constant is needed eagerly by the gemspec (before the loader is set
+# up), so it stays an explicit require rather than an autoload.
+require_relative "mcp_toolkit/version"
+
+loader = Zeitwerk::Loader.for_gem
+# `version.rb` is loaded manually above; let Zeitwerk ignore it so it doesn't try
+# to manage the already-defined constant.
+loader.ignore("#{__dir__}/mcp_toolkit/version.rb")
+# `engine.rb` subclasses ::Rails::Engine, which is absent in a non-Rails host (and
+# in the gem's own unit suite). Keep it out of the autoloadable set and require it
+# explicitly below only when Rails is present. The gem-internal controller lives
+# under `app/controllers` (outside this lib-rooted loader), so it needs no ignore;
+# it is loaded by Rails' autoloader via the engine when mounted.
+loader.ignore("#{__dir__}/mcp_toolkit/engine.rb")
+loader.setup
+
+# The toolkit for building account-scoped, read-only MCP servers on top of the
+# official `mcp` gem. See README.md for the satellite + authority quickstarts.
+#
+# Entry points:
+#   McpToolkit.configure { |c| ... }  # set up the server
+#   McpToolkit.config                 # the active Configuration
+#   McpToolkit.registry               # the active config's resource registry
+#
+# `MCPToolkit` is provided as an alias for the same module.
+module McpToolkit
+  # The toolkit's own base error (kept distinct from tool-level Errors::*).
+  class Error < StandardError; end
+
+  # Yields the active configuration for mutation, returning it.
+  #
+  #   McpToolkit.configure do |c|
+  #     c.server_name = "my-app-mcp"
+  #     c.central_app_url = ENV.fetch("MCP_CENTRAL_APP_URL")
+  #     c.registry.default_required_permissions_scope "my_app__read"
+  #   end
+  def self.configure
+    yield(config) if block_given?
+    config
+  end
+
+  # The active Configuration (created on first access).
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # The active config's resource registry. Register resources against this in a
+  # boot initializer.
+  def self.registry
+    config.registry
+  end
+
+  # Replaces the active configuration with a fresh default. Primarily for tests.
+  def self.reset_config!
+    @config = Configuration.new
+  end
+end
+
+# Karol's requested entry-point spelling. `MCPToolkit.configure { ... }` and
+# `MCPToolkit.config` work identically to `McpToolkit.*`.
+MCPToolkit = McpToolkit unless defined?(MCPToolkit)
+
+# The mountable engine is ADDITIVE and Rails-only: a satellite can either mount
+# `McpToolkit::Engine` (engine + gem controller) OR keep including
+# `McpToolkit::Transport::ControllerMethods` in its own controller. Loaded only
+# when Rails::Engine is present (it was ignored by the loader above).
+require_relative "mcp_toolkit/engine" if defined?(Rails::Engine)

data/sig/mcp_toolkit.rbs

@@ -0,0 +1,4 @@
+module McpToolkit
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: mcp_toolkit
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Karol Galanciak
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  mcp_toolkit extracts the shared MCP-server framework that Smily's apps grew
+  independently: a Streamable-HTTP transport, cache-backed sessions, central-app
+  token introspection (satellite + authority roles), a registry-driven
+  "generic tools over N resources" dispatcher, and an injectable serializer DSL.
+  It wraps the official `mcp` gem as the JSON-RPC core so each app ships only its
+  serializers, resource registrations, and scope blocks.
+email:
+- karol.galanciak@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/mcp_toolkit/server_controller.rb
+- config/routes.rb
+- lib/mcp_toolkit.rb
+- lib/mcp_toolkit/auth/authenticator.rb
+- lib/mcp_toolkit/auth/authority.rb
+- lib/mcp_toolkit/auth/authority_server_client.rb
+- lib/mcp_toolkit/auth/introspection.rb
+- lib/mcp_toolkit/configuration.rb
+- lib/mcp_toolkit/engine.rb
+- lib/mcp_toolkit/errors/base.rb
+- lib/mcp_toolkit/errors/configuration_error.rb
+- lib/mcp_toolkit/errors/invalid_params.rb
+- lib/mcp_toolkit/errors/unauthorized.rb
+- lib/mcp_toolkit/field_selection.rb
+- lib/mcp_toolkit/filtering.rb
+- lib/mcp_toolkit/get_executor.rb
+- lib/mcp_toolkit/list_executor.rb
+- lib/mcp_toolkit/registry.rb
+- lib/mcp_toolkit/resource.rb
+- lib/mcp_toolkit/resource_schema.rb
+- lib/mcp_toolkit/serialization.rb
+- lib/mcp_toolkit/serializer/base.rb
+- lib/mcp_toolkit/server.rb
+- lib/mcp_toolkit/session.rb
+- lib/mcp_toolkit/sql_sanitizer.rb
+- lib/mcp_toolkit/token_kinds.rb
+- lib/mcp_toolkit/tools/base.rb
+- lib/mcp_toolkit/tools/get.rb
+- lib/mcp_toolkit/tools/list.rb
+- lib/mcp_toolkit/tools/resource_schema.rb
+- lib/mcp_toolkit/tools/resources.rb
+- lib/mcp_toolkit/transport/controller_methods.rb
+- lib/mcp_toolkit/unknown_resource_message.rb
+- lib/mcp_toolkit/version.rb
+- sig/mcp_toolkit.rbs
+homepage: https://github.com/BookingSync/mcp_toolkit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/BookingSync/mcp_toolkit
+  source_code_uri: https://github.com/BookingSync/mcp_toolkit
+  changelog_uri: https://github.com/BookingSync/mcp_toolkit/blob/master/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.2.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: Opinionated toolkit for building account-scoped, read-only MCP servers.
+test_files: []