Overview

This MCP (Model Context Protocol) server exposes Foobara Ruby commands as remote tools that an LLM agent or other clients can discover and invoke over HTTP. It wraps common Foobara project commands — such as task runners, console commands, and metadata queries — and presents them as MCP-compatible tools so models can call them safely and predictably.

Using an MCP server centralizes command execution, simplifies integrations with agents and automation systems, and enforces policy (whitelists, auth, logging). Instead of giving a model direct shell access to a repository, you present a limited, documented surface of capabilities: the model requests a named tool and the server runs the mapped Ruby command and returns structured output.

Features

Expose Foobara commands as named MCP tools (discoverable via a describe endpoint)
JSON RPC-style run endpoint with structured inputs and outputs
Configurable command whitelist and per-tool timeouts
Authentication tokens and optional request logging/auditing
Lightweight Ruby implementation — run locally or as a service in CI/staging
Simple CLI and HTTP examples to integrate with agents and scripts

Installation / Configuration

Prerequisites: Ruby 2.7+ (or compatible), bundler

Clone the repository and install dependencies:

git clone https://github.com/foobara/mcp-connector.git
cd mcp-connector
bundle install

Create a configuration file (config.yml). Define which Foobara commands should be exposed, optional args, and security settings:

server:
  bind: 0.0.0.0
  port: 8080
auth_token: "replace-with-a-secret-token"

tools:
  - name: foobara:run
    description: "Run a Foobara command in the project"
    command: "bundle exec foobara"
    allowed_args: ["migrate", "seed", "test"]
    timeout: 60

  - name: foobara:version
    description: "Return Foobara version"
    command: "bundle exec foobara --version"
    timeout: 5

Start the server (development):

export MCP_CONFIG=./config.yml
bundle exec ruby bin/mcp_server.rb
# or run with rack
bundle exec rackup -p 8080

Set PORT or bind address via env vars or config.yml as needed.

Available Tools

Below is a sample table of the default tool surface that the server can expose. The actual list is driven by your config.yml.

Tool name	Description	Example invocation
foobara:run	Run a Foobara command with args	foobara:run {“cmd”:“migrate”}
foobara:version	Get Foobara version string	foobara:version
foobara:list	List available tasks/commands	foobara:list

Tool metadata is returned by the MCP “describe” endpoint so agents can discover names, input schemas, and descriptions.

API examples

Describe available tools:

curl -H "Authorization: Bearer replace-with-a-secret-token" \
  http://localhost:8080/describe

Invoke a tool (run a migrate command):

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer replace-with-a-secret-token" \
  http://localhost:8080/run \
  -d '{
    "tool": "foobara:run",
    "input": {"cmd": "migrate"}
  }'

Typical response includes exit status, stdout, stderr and any structured result JSON:

{
  "status": 0,
  "stdout": "Migrations applied",
  "stderr": "",
  "result": null
}

Use Cases

LLM-driven automation: Allow an LLM agent to run safe maintenance tasks (db migrations, test suites) in a controlled way by exposing only approved commands.
CI / remote runners: Have a centralized MCP server accept job requests from other services and run Foobara tasks on a specific host (e.g., staging environment) with consistent logging.
ChatOps integration: Expose a minimal set of operations so operations staff or bots can query version info or trigger routine tasks from chat interfaces without direct SSH.
Debug & diagnostics: Provide a foil for agents to run diagnostics commands (list tasks, show logs) as part of a multi-step troubleshooting flow.

Security and Operational Notes

Always use an auth token or mTLS to secure the HTTP endpoint. Configure short-lived tokens where possible.
Use a strict whitelist of allowed commands and validate input arguments; never blindly run user-provided shell strings.
Enforce per-tool timeouts and resource limits to avoid long-running or runaway processes.
Log invocations and preserve stdout/stderr for auditability. Consider exposing a read-only audit endpoint for diagnostics.
Run MCP server behind a reverse proxy or inside a network zone appropriate for the tasks it will execute.

Resources

Source & issues: https://github.com/foobara/mcp-connector
Example config and startup scripts are included in the repo (see config.example.yml and bin/mcp_server.rb)
For integration patterns, refer to MCC/MCP client libraries to implement the agent side that calls /describe and /run endpoints.

Expose Foobara Ruby Tools via MCP Server