Foobara::McpConnector

Exposes Foobara commands according to the Model Context Protocol (MCP) specification

Installation

Typical stuff: add gem "foobara-mcp-connector to your Gemfile or .gemspec file. Or even just gem install foobara-mcp-connector if just playing with it directly in scripts.

Usage

Code demo video!

You can watch a code demo here: https://youtu.be/_w3ZHdiJEGU

Code examples

You can find examples in examples/

Super basic example

Let's create a simple Foobara command:

class BuildSuperDuperSecret < Foobara::Command
  inputs do
    seed :integer, :required
  end
  result :integer

  def execute
    seed * seed * seed
  end
end

This just cubes the integer we pass to it. You can run it with BuildSuperDuperSecret.run!(seed: 3) which would give 27. See the foobara gem for more info about Foobara commands.

Now, let's connect it to an McpConnector:

require "foobara/mcp_connector"

mcp_connector = Foobara::McpConnector.new
mcp_connector.connect(BuildSuperDuperSecret)

And we can start a stdio server like so:

mcp_connector.run_stdio_server

Putting it all together in a single script called simple-mcp-server-example we get:

#!/usr/bin/env ruby

require "foobara/mcp_connector"

class BuildSuperDuperSecret < Foobara::Command
  inputs do
    seed :integer, :required
  end
  result :integer

  def execute
    seed * seed * seed
  end
end

mcp_connector = Foobara::McpConnector.new
mcp_connector.connect(BuildSuperDuperSecret)
mcp_connector.run_stdio_server

We can now add it to programs that can consume MCP servers. For example, with claude code, we can tell claude code about it by running claude mcp add and following the instructions or we can create a .mcp.json file like this:

{
  "mcpServers": {
    "mcp-test": {
      "type": "stdio",
      "command": "simple-mcp-server-example",
      "args": [],
      "env": {}
    }
  }
}

You need to set "command" to the path of your script.

Now when we run claude, we can ask it a question that would result in it running our command:

$ claude
> Hi! Could you please build me a super duper secret using a seed of 5?

An example with entities

Let's say we have a model (see examples/capybaras.rb):

class Capybara < Foobara::Entity
  attributes do
    id :integer
    name :string, :required
    year_of_birth :integer, :required
  end

  primary_key :id
end

As well as some commands like FindAllCapybaras, CreateCapybara, and UpdateCapybara (see examples/capybara_commands.rb)

We can write an MCP connector to expose those commands so we can ask questions that require running those commands to answer:

require "foobara/mcp_connector"
require_relative "capybara_commands"

CreateCapybara.run!(name: "Fumiko", year_of_birth: 2020)
CreateCapybara.run!(name: "Barbara", year_of_birth: 2019)
CreateCapybara.run!(name: "Basil", year_of_birth: 2021)

mcp_connector = Foobara::McpConnector.new
mcp_connector.connect(FindAllCapybaras)

mcp_connector.run_stdio_server

We can now ask a tool like claude a relevant question:

$ claude
> Which Capybara is the oldest?

A destructive example

Let's say we would like to mutate data. Let's pretend we've accidentally entered a year-of-birth in a 2-digit format where a 4-digit format was expected. Let's do that and also expose our UpdateCapybara command:

# We will simulate a year accidentally being entered with a 2-digit format where a 4-digit format was expected
UpdateCapybara.run!(id: barbara.id, year_of_birth: 19)

mcp_connector = Foobara::McpConnector.new

mcp_connector.connect(FindAllCapybaras)
mcp_connector.connect(UpdateCapybara)

mcp_connector.run_stdio_server

Now we can ask a tool like claude to find and fix our data:

$ claude
> Hi! There's a Capybara whose birth year was entered incorrectly. Can you find which one
  and fix it? Thanks!
● I'll help find and fix the capybara with the incorrect birth year. Let me search for the
  capybaras first.

Moar examples

Please see the examples/ directory for executable scripts of these examples.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/foobara/mcp-connector

Feel free to reach out if you'd like help with this gem or if you'd like to help with this gem!

License

This project is licensed under the MPL-2.0 license. Please see LICENSE.txt for more info.