charlesgwilson/simple-mcp-gem

Simple MCP

A minimal, fast, and reliable Model Context Protocol (MCP) server implementation for testing and development purposes.

Overview

A minimal MCP server that runs within your Ruby application's process. Provides a foundation for building custom AI tools that can evolve alongside your codebase.

Experiment with: Custom MCP tools, AI-assisted workflows, and intelligent code interactions.

Why an Embeddable Gem?

Most MCP servers run as separate processes. This gem explores a different approach by running within your application:

• Shared Runtime: Access to your project's loaded gems and Ruby environment
• Workspace Awareness: Tools know your project's root directory context
• Extensible Foundation: Simple architecture for building project-specific tools
• Future Potential: Foundation for deeper integrations with Ruby LSP, Rails, and other tooling

What could you build when AI tools understand your specific codebase and business domain?

Installation

Add to your Ruby application's Gemfile:

group :development do
  gem "simple-mcp", path: "simple-mcp-gem"
end

Then run:

bundle install

Configuration

Claude Code

Create .claude/mcp.json in your project root:

{
  "mcpServers": {
    "simple-mcp": {
      "command": "bundle",
      "args": ["exec", "simple-mcp"],
      "cwd": "/path/to/your/project",
      "env": {}
    }
  }
}

Cursor

Add to your MCP settings or configuration file with the same format as above.

Usage

Command Line

# Show help
bundle exec simple-mcp --help

# Show version
bundle exec simple-mcp --version

# Start MCP server (for testing)
bundle exec simple-mcp

MCP Tool

The gem provides one tool:

hello_world_tool

Says hello to a provided name or defaults to "World".

Parameters:

• name (optional): Name to greet

Example responses:

{"type": "text", "text": "Hello, World!"}
{"type": "text", "text": "Hello, Alice!"}

Development

Requirements

• Ruby 3.0+
• Bundler
• RSpec (testing)
• RuboCop (linting)

Setup

bundle install

Testing

# Run all tests
bundle exec rspec

# Run with coverage
bundle exec rspec --format documentation

Code Quality

# Run RuboCop
bundle exec rubocop

# Check syntax
ruby -c exe/simple-mcp

Manual Testing

# Test initialization
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}}}' | bundle exec simple-mcp

# Test tool listing
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' | bundle exec simple-mcp

# Test tool call
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "hello_world_tool", "arguments": {"name": "Test"}}}' | bundle exec simple-mcp

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with AI assistance from Claude Code and Cursor, following standards from BuoySoftware and thoughtbot, with hat tip to Cursor Rules.

Disclaimer

All documentation, including this file, was generated with AI assistance.