graphql_backed 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 688cf9549fad3d7eeac442d87b9e24aa3602b8f88d788974f685941c7fc3853a
+  data.tar.gz: cc98e73c3013faa2ff629b94baddcc49f8e19b37cb180ec214d1a36dbfb1525a
+SHA512:
+  metadata.gz: f0d328339fbd51167750b9cc3f8adc16323f51c3bfefa67efe9bfdd1d5238e60a2f29ed4227aab97b484fdd7fa618257a38a1f0651adf4e1f754bc8a521a3cd2
+  data.tar.gz: bb1d9bb8ea64d3bd90adf462ea42ea3b9fc3545bc322449df3077329b542f9918089f346a18175e66f8cec18381d257de30dcaa14d3b715c1dbbb5d5af575e17

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Robert Mosolgo
+
+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,42 @@
+# GraphQLBacked
+
+Build APIs on top of existing GraphQL APIs.
+
+## Installation
+
+```
+bundle add graphql_backed
+```
+
+## Documentation
+
+API docs are at https://rmosolgo.github.io/graphql_backed/main/:
+
+- [`GraphQLBacked::Resource`](https://rmosolgo.github.io/graphql_backed/main/GraphQLBacked/Resource.html): a reusable GraphQL fragment
+- [`GraphQLBacked::Operation`](https://rmosolgo.github.io/graphql_backed/main/GraphQLBacked/Operation.html): a query or mutation which includes resources
+- [`GraphQLBacked::Service`](https://rmosolgo.github.io/graphql_backed/main/GraphQLBacked/Service.html): a set of operations backed by a schema, which runs them
+- [`GraphQLBacked::MCP`](https://rmosolgo.github.io/graphql_backed/main/GraphQLBacked/MCP.html): serves a service's operations as MCP tools
+- [`GraphQLBacked::REST`](https://rmosolgo.github.io/graphql_backed/main/GraphQLBacked/REST.html): serves a service's operations as JSON over HTTP, and describes them with OpenAPI
+
+## Development
+
+- `bundle exec rake test` runs the tests
+- `bundle exec rake typecheck` runs Sorbet (`srb tc`)
+- `bundle exec rake rdoc` builds API docs into `doc/`
+
+### Types
+
+Type signatures are written as [RBS comments](https://sorbet.org/docs/rbs-support), not `sig` blocks, so there is no runtime dependency on `sorbet-runtime`:
+
+```ruby
+#: (String name) -> Integer
+def lookup(name)
+  # ...
+end
+```
+
+After changing dependencies, refresh the gem RBIs with `bin/tapioca gems`.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/graphql_backed/json_schema.rb

@@ -0,0 +1,310 @@
+# typed: strict
+# frozen_string_literal: true
+
+module GraphQLBacked
+  # Builds JSON Schema from GraphQL types, for frontends which describe their inputs and outputs that way.
+  module JSONSchema # :nodoc:
+    # Scalars from the GraphQL specification and those which come with GraphQL-Ruby, as they're accepted in variables.
+    # Other scalars accept any JSON value, unless they're configured with Service.scalar_json_schema.
+    INPUT_SCALARS = {
+      "String" => { "type" => "string" },
+      "ID" => { "type" => ["string", "integer"] },
+      "Int" => { "type" => "integer" },
+      "Float" => { "type" => "number" },
+      "Boolean" => { "type" => "boolean" },
+      "ISO8601Date" => { "type" => "string", "format" => "date" },
+      "ISO8601DateTime" => { "type" => "string", "format" => "date-time" },
+      "ISO8601Duration" => { "type" => "string", "format" => "duration" },
+      "BigInt" => { "type" => ["string", "integer"] },
+    }.freeze #: Hash[String, Hash[String, untyped]]
+
+    # IDs and BigInts are accepted as integers, but always returned as strings
+    OUTPUT_SCALARS = INPUT_SCALARS.merge(
+      "ID" => { "type" => "string" },
+      "BigInt" => { "type" => "string" },
+    ).freeze #: Hash[String, Hash[String, untyped]]
+
+    # A schema with one of these can't be made nullable by adding `"null"` to its `"type"`:
+    # either `null` still wouldn't match, or the result would be harder to read than `anyOf`.
+    NOT_NULL_KEYWORDS = ["enum", "const", "properties", "items"].freeze #: Array[String]
+
+    # A schema for an object whose properties are the variables of `operation_class`.
+    # Input objects are put in `$defs` since they may refer to each other.
+    #
+    # Each variable is described by the first argument that it's passed to, if that argument has a description.
+    #
+    # `scalars` are schemas for custom scalars, by name. See Service.scalar_json_schema.
+    #
+    #: (singleton(GraphQL::Schema) schema, singleton(Operation) operation_class, ?scalars: Hash[String, Hash[String, untyped]]) -> Hash[String, untyped]
+    def self.input(schema, operation_class, scalars: {})
+      Input.new(schema, operation_class, scalars).to_h
+    end
+
+    class Input
+      #: (singleton(GraphQL::Schema) schema, singleton(Operation) operation_class, Hash[String, Hash[String, untyped]] scalars) -> void
+      def initialize(schema, operation_class, scalars)
+        @schema = schema
+        @operation_class = operation_class
+        @scalars = scalars
+        @defs = {} #: Hash[String, untyped]
+      end
+
+      #: -> Hash[String, untyped]
+      def to_h
+        descriptions = variable_descriptions
+        properties = {} #: Hash[String, untyped]
+        required = [] #: Array[String]
+        @operation_class.definition.variables.each do |variable|
+          type = @schema.type_from_ast(variable.type)
+          properties[variable.name] = JSONSchema.with_description(type_schema(type), descriptions[variable.name])
+          required << variable.name if type.non_null? && variable.default_value.nil?
+        end
+        result = { "type" => "object", "properties" => properties } #: Hash[String, untyped]
+        result["required"] = required if required.any?
+        result["$defs"] = @defs if @defs.any?
+        result
+      end
+
+      private
+
+      #: (untyped type) -> Hash[String, untyped]
+      def type_schema(type)
+        if type.non_null?
+          type_schema(type.of_type)
+        elsif type.list?
+          { "type" => "array", "items" => type_schema(type.of_type) }
+        elsif type.kind.enum?
+          JSONSchema.with_description({ "type" => "string", "enum" => type.values.keys }, type.description)
+        elsif type.kind.input_object?
+          @defs[type.graphql_name] ||= begin
+            # Assign a placeholder first so that self-referential input objects don't recurse forever
+            input_object = @defs[type.graphql_name] = { "type" => "object" } #: Hash[String, untyped]
+            required = [] #: Array[String]
+            input_object["properties"] = type.arguments.to_h do |name, argument|
+              required << name if argument.type.non_null? && !argument.default_value?
+              [name, JSONSchema.with_description(type_schema(argument.type), argument.description)]
+            end
+            input_object["required"] = required if required.any?
+            JSONSchema.with_description(input_object, type.description)
+          end
+          { "$ref" => "#/$defs/#{type.graphql_name}" }
+        else
+          JSONSchema.scalar(type, INPUT_SCALARS, @scalars)
+        end
+      end
+
+      # The description of the first described argument that each variable is passed to, by variable name
+      #
+      #: -> Hash[String, String?]
+      def variable_descriptions
+        descriptions = {} #: Hash[String, String?]
+        root_type = @schema.root_type_for_operation(@operation_class.operation_type.to_s)
+        describe_selections(root_type, @operation_class.definition.selections, descriptions)
+        @operation_class.fragments.each_value do |fragment|
+          describe_selections(@schema.get_type(fragment.type.name), fragment.selections, descriptions)
+        end
+        descriptions
+      end
+
+      #: (untyped parent_type, Array[untyped] selections, Hash[String, String?] descriptions) -> void
+      def describe_selections(parent_type, selections, descriptions)
+        selections.each do |selection|
+          case selection
+          when GraphQL::Language::Nodes::Field
+            field = @schema.get_field(parent_type, selection.name)
+            describe_arguments(field, selection.arguments, descriptions)
+            describe_directives(selection.directives, descriptions)
+            describe_selections(field.type.unwrap, selection.selections, descriptions)
+          when GraphQL::Language::Nodes::InlineFragment
+            type = selection.type ? @schema.get_type(selection.type.name) : parent_type
+            describe_directives(selection.directives, descriptions)
+            describe_selections(type, selection.selections, descriptions)
+          when GraphQL::Language::Nodes::FragmentSpread
+            describe_directives(selection.directives, descriptions)
+          end
+        end
+      end
+
+      #: (Array[untyped] directives, Hash[String, String?] descriptions) -> void
+      def describe_directives(directives, descriptions)
+        directives.each do |directive|
+          describe_arguments(@schema.directives[directive.name], directive.arguments, descriptions)
+        end
+      end
+
+      # `owner` is the field, directive or input object which defines these arguments
+      #
+      #: (untyped owner, Array[untyped] argument_nodes, Hash[String, String?] descriptions) -> void
+      def describe_arguments(owner, argument_nodes, descriptions)
+        argument_nodes.each do |argument_node|
+          describe_value(owner.get_argument(argument_node.name), argument_node.value, descriptions)
+        end
+      end
+
+      #: (untyped argument, untyped value, Hash[String, String?] descriptions) -> void
+      def describe_value(argument, value, descriptions)
+        case value
+        when GraphQL::Language::Nodes::VariableIdentifier
+          descriptions[value.name] ||= argument.description
+        when GraphQL::Language::Nodes::InputObject
+          describe_arguments(argument.type.unwrap, value.arguments, descriptions)
+        when Array
+          # A variable which is one item of a list isn't described by the argument, which describes the whole list
+          value.each { |item| describe_value(argument, item, descriptions) unless item.is_a?(GraphQL::Language::Nodes::VariableIdentifier) }
+        end
+      end
+    end
+
+    # A schema for the `"data"` of a successful response to `operation_class`.
+    # Each fragment (including each Resource) that's always applied where it's spread is put in `$defs`.
+    #
+    # Fields which are only sometimes present aren't required: those with `@skip` or `@include`, and those
+    # selected on a type condition which doesn't match every possible type. There are no per-type variants for
+    # interfaces and unions.
+    #
+    # Each property has the description of its field. `scalars` are schemas for custom scalars, by name.
+    #
+    #: (singleton(GraphQL::Schema) schema, singleton(Operation) operation_class, ?scalars: Hash[String, Hash[String, untyped]]) -> Hash[String, untyped]
+    def self.output(schema, operation_class, scalars: {})
+      Output.new(schema, operation_class, scalars).to_h
+    end
+
+    class Output
+      #: (singleton(GraphQL::Schema) schema, singleton(Operation) operation_class, Hash[String, Hash[String, untyped]] scalars) -> void
+      def initialize(schema, operation_class, scalars)
+        @schema = schema
+        @operation_class = operation_class
+        @scalars = scalars
+        @defs = {} #: Hash[String, untyped]
+      end
+
+      #: -> Hash[String, untyped]
+      def to_h
+        root_type = @schema.root_type_for_operation(@operation_class.operation_type.to_s)
+        result = selections_schema(root_type, @operation_class.definition.selections)
+        result["$defs"] = @defs if @defs.any?
+        result
+      end
+
+      private
+
+      # The schema for an object of `parent_type` with `selections`
+      #
+      #: (untyped parent_type, Array[untyped] selections) -> Hash[String, untyped]
+      def selections_schema(parent_type, selections)
+        properties = {} #: Hash[String, untyped]
+        optional = [] #: Array[String]
+        refs = [] #: Array[Hash[String, untyped]]
+        collect(parent_type, selections, false, properties, optional, refs)
+        object = { "type" => "object", "properties" => properties } #: Hash[String, untyped]
+        required = properties.keys - optional
+        object["required"] = required if required.any?
+        if refs.empty?
+          object
+        elsif properties.empty?
+          refs.size == 1 ? refs.first : { "allOf" => refs } #: as !nil
+        else
+          { "allOf" => [*refs, object] }
+        end
+      end
+
+      # Gather the fields of `selections` into `properties`, following fragments.
+      # `conditional` is true when these selections might not apply to the object.
+      #
+      #: (untyped parent_type, Array[untyped] selections, bool conditional, Hash[String, untyped] properties, Array[String] optional, Array[Hash[String, untyped]] refs) -> void
+      def collect(parent_type, selections, conditional, properties, optional, refs)
+        selections.each do |selection|
+          sometimes = conditional || selection.directives.any? { |d| d.name == "skip" || d.name == "include" }
+          case selection
+          when GraphQL::Language::Nodes::Field
+            key = selection.alias || selection.name
+            field_schema = if selection.name == "__typename"
+              { "type" => "string" }
+            else
+              field = parent_type.get_field(selection.name)
+              JSONSchema.with_description(type_schema(field.type, selection.selections), field.description)
+            end
+            previous = properties[key]
+            # The same key may be selected more than once, with different subselections
+            properties[key] = previous && previous != field_schema ? { "allOf" => [previous, field_schema] } : field_schema
+            if !sometimes
+              optional.delete(key)
+            elsif previous.nil?
+              optional << key
+            end
+          when GraphQL::Language::Nodes::InlineFragment
+            type = selection.type ? @schema.get_type(selection.type.name) : parent_type
+            collect(type, selection.selections, sometimes || !always_applies?(parent_type, type), properties, optional, refs)
+          when GraphQL::Language::Nodes::FragmentSpread
+            fragment = @operation_class.fragments.fetch(selection.name)
+            type = @schema.get_type(fragment.type.name)
+            if sometimes || !always_applies?(parent_type, type)
+              collect(type, fragment.selections, true, properties, optional, refs)
+            else
+              @defs[fragment.name] ||= selections_schema(type, fragment.selections)
+              ref = { "$ref" => "#/$defs/#{fragment.name}" }
+              refs << ref unless refs.include?(ref)
+            end
+          end
+        end
+      end
+
+      # Whether a fragment on `fragment_type` applies to every object that `parent_type` could be
+      #
+      #: (untyped parent_type, untyped fragment_type) -> bool
+      def always_applies?(parent_type, fragment_type)
+        parent_type == fragment_type || (@schema.possible_types(parent_type) - @schema.possible_types(fragment_type)).empty?
+      end
+
+      #: (untyped type, Array[untyped] selections) -> Hash[String, untyped]
+      def type_schema(type, selections)
+        return non_null_schema(type.of_type, selections) if type.non_null?
+        json_schema = non_null_schema(type, selections)
+        if (json_schema.keys - ["description"]).empty?
+          json_schema # already accepts anything
+        elsif json_schema.key?("type") && (json_schema.keys & NOT_NULL_KEYWORDS).empty?
+          json_schema.merge("type" => [*json_schema["type"], "null"].uniq)
+        else
+          { "anyOf" => [json_schema, { "type" => "null" }] }
+        end
+      end
+
+      #: (untyped type, Array[untyped] selections) -> Hash[String, untyped]
+      def non_null_schema(type, selections)
+        if type.list?
+          { "type" => "array", "items" => type_schema(type.of_type, selections) }
+        elsif type.kind.enum?
+          JSONSchema.with_description({ "type" => "string", "enum" => type.values.keys }, type.description)
+        elsif type.kind.scalar?
+          JSONSchema.scalar(type, OUTPUT_SCALARS, @scalars)
+        else
+          selections_schema(type, selections)
+        end
+      end
+    end
+
+    # A schema for the scalar `type`: the one in `custom` if there is one, or else the one in `built_in`.
+    # Other scalars accept any JSON value.
+    #
+    #: (untyped type, Hash[String, Hash[String, untyped]] built_in, Hash[String, Hash[String, untyped]] custom) -> Hash[String, untyped]
+    def self.scalar(type, built_in, custom)
+      name = type.graphql_name
+      if (json_schema = custom[name])
+        json_schema.key?("description") ? json_schema.dup : with_description(json_schema.dup, type.description)
+      elsif (json_schema = built_in[name])
+        json_schema.dup
+      else
+        with_description({}, type.description)
+      end
+    end
+
+    # Replaces any description that `json_schema` already has, so a type's description is only used
+    # when the field or argument that returns it has none.
+    #
+    #: (Hash[String, untyped] json_schema, String? description) -> Hash[String, untyped]
+    def self.with_description(json_schema, description)
+      json_schema["description"] = description if description
+      json_schema
+    end
+  end
+end

data/lib/graphql_backed/mcp.rb

@@ -0,0 +1,137 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQLBacked
+  # Serves a Service's queries and mutations as [Model Context Protocol](https://modelcontextprotocol.io) tools,
+  # using the [`mcp` gem](https://github.com/modelcontextprotocol/ruby-sdk). That gem isn't a dependency of this one,
+  # so add it to your app (`bundle add mcp`); without it, these methods raise MissingDependencyError.
+  #
+  # - .transport returns a Streamable HTTP transport, which is a Rack app
+  # - .server returns the `MCP::Server`, for other transports (like stdio)
+  # - .tools returns the `MCP::Tool` classes
+  #
+  # Each of them is also available from the service, as Service.mcp_transport, Service.mcp_server and Service.mcp_tools:
+  #
+  #     # config.ru
+  #     run MyService.mcp_transport(allowed_hosts: ["api.example.com"])
+  #
+  # ## Tools
+  #
+  # Each Operation of the service becomes a tool:
+  #
+  # - its name is Operation.public_name
+  # - its description is Operation.description, or else the description of its root field in the schema
+  # - its hints come from Operation.query?, Operation.destructive?, Operation.idempotent? and Operation.open_world?
+  # - its input is the operation's variables, each described by the argument that it's passed to
+  # - its output schema describes the `"data"` of the GraphQL response, based on the operation's selections,
+  #   with the description of each field and each Resource as a reusable definition
+  # - custom scalars are described by Service.scalar_json_schema
+  # - its result is the `"data"` of the GraphQL response. If the response has `"errors"`,
+  #   the tool result is flagged as an error and contains the whole response instead.
+  module MCP
+    # The `MCP::Tool` classes for `service`, one for each of its operations. See the "Tools" section above for how they're built.
+    #
+    # This builds new classes each time; Service.mcp_tools keeps them until the service changes.
+    #
+    #: (singleton(Service) service) -> Array[singleton(::MCP::Tool)]
+    def self.tools(service)
+      require_mcp
+      service.operations.map { |operation_class| build_tool(service, operation_class) }
+    end
+
+    # An `MCP::Server` with the tools of `service` (from Service.mcp_tools), for use with any of the `mcp` gem's transports (for example, stdio).
+    # `context` is the GraphQL context which its tools execute with; other options are passed to `MCP::Server.new`:
+    #
+    #     GraphQLBacked::MCP.server(MyService, context: { current_user: user }, name: "my-api", version: "1.2.0")
+    #
+    # By default, the server is named after the service.
+    #
+    #: (singleton(Service) service, ?context: Hash[untyped, untyped], **untyped server_options) -> ::MCP::Server
+    def self.server(service, context: {}, **server_options)
+      service_tools = service.mcp_tools # this also makes sure that `mcp` is loaded
+      ::MCP::Server.new(
+        name: service.name || "GraphQLBacked",
+        capabilities: { tools: {} },
+        **server_options,
+        tools: service_tools,
+        server_context: { graphql_context: context },
+      )
+    end
+
+    # A Streamable HTTP transport for the .server of `service`, which is also a Rack app
+    # (so your app needs the `rack` gem as well as `mcp`):
+    #
+    #     # config.ru
+    #     run GraphQLBacked::MCP.transport(MyService, allowed_hosts: ["api.example.com"])
+    #
+    # `context` is the GraphQL context to execute with and `server_options` are passed to `MCP::Server.new`
+    # (see .server); other options are passed to `MCP::Server::Transports::StreamableHTTPTransport.new`:
+    #
+    #     GraphQLBacked::MCP.transport(MyService, server_options: { name: "my-api", version: "1.2.0" }, stateless: true)
+    #
+    # To use a different GraphQL context for each request, build a transport for each request,
+    # for example in a Rails controller:
+    #
+    #     def create
+    #       transport = MyService.mcp_transport(context: { current_user: current_user }, stateless: true, enable_json_response: true)
+    #       status, headers, body = transport.call(request.env)
+    #       # ...
+    #     end
+    #
+    #: (singleton(Service) service, ?context: Hash[untyped, untyped], ?server_options: Hash[Symbol, untyped], **untyped transport_options) -> ::MCP::Server::Transports::StreamableHTTPTransport
+    def self.transport(service, context: {}, server_options: {}, **transport_options)
+      mcp_server = server(service, context: context, **server_options)
+      ::MCP::Server::Transports::StreamableHTTPTransport.new(mcp_server, **transport_options)
+    end
+
+    # `mcp` isn't a dependency of this gem, so it's only required when MCP features are first used.
+    #
+    #: -> void
+    def self.require_mcp # :nodoc:
+      require "mcp"
+    rescue LoadError => err
+      raise unless err.path == "mcp"
+      raise MissingDependencyError, "GraphQLBacked's MCP support requires the `mcp` gem, add it to your app with `bundle add mcp`"
+    end
+
+    #: (singleton(Service) service, singleton(Operation) operation_class) -> singleton(::MCP::Tool)
+    def self.build_tool(service, operation_class) # :nodoc:
+      scalars = service.scalar_json_schemas
+      ::MCP::Tool.define(
+        name: operation_class.public_name,
+        description: operation_class.description || root_field_description(service, operation_class),
+        input_schema: JSONSchema.input(service.schema, operation_class, scalars: scalars),
+        output_schema: JSONSchema.output(service.schema, operation_class, scalars: scalars),
+        annotations: {
+          read_only_hint: operation_class.query?,
+          destructive_hint: operation_class.destructive?,
+          idempotent_hint: operation_class.idempotent?,
+          open_world_hint: operation_class.open_world?,
+        },
+      ) do |server_context:, **arguments|
+        response = service.execute(
+          operation_class,
+          variables: JSON.parse(JSON.generate(arguments)), # the `mcp` gem symbolizes keys, GraphQL wants strings
+          context: server_context[:graphql_context] || {},
+        )
+        data = response["data"]
+        if response.key?("errors")
+          ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(response) }], error: true)
+        else
+          # `data` rather than the root field's value, because structured content must be an object
+          ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(data) }], structured_content: data)
+        end
+      end
+    end
+
+    #: (singleton(Service) service, singleton(Operation) operation_class) -> String?
+    def self.root_field_description(service, operation_class) # :nodoc:
+      root_type = service.schema.root_type_for_operation(operation_class.operation_type.to_s)
+      root_type.get_field(operation_class.root_field_name)&.description
+    end
+
+    private_class_method :require_mcp, :build_tool, :root_field_description
+  end
+end