mcp_on_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc959666bde188d8d9642e81879d3e16436b592a36e503e7c3d6f23dd040810b
+  data.tar.gz: ce86ed0d4ce97276435ad7192133dc8a6b613cc4974996cdd41cbabae1f15ae7
+SHA512:
+  metadata.gz: a41b4314669cf296ff64d5d71524472da25de3ca43e8b27bfab3d1b5fdf5e2969f208c11c5b094849b648f7e1bc53ce3b51bf7c4917e4322542d026d53488d28
+  data.tar.gz: 541c892381b491280fa0c74f168782afcba411d43657686880cabd67a560a1fc34b7f8529ce0049cf3ac477209b52e134f60dcd3083aab10faa3dee311341803

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2025-04-18
+
+Initial release of version 0.1.0 of the Ruby Gem. 
+
+### Added
+- Core MCP implementation with Rack server
+- Provider support for OpenAI and Anthropic
+- In-memory storage backend
+- Context, message, and content management
+- Basic authentication support
+- Comprehensive test suite

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at nagendra.dhanakeerthi@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to RubyMCP
+
+Thank you for considering contributing to RubyMCP! This document outlines the process for contributing to the project.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+This section guides you through submitting a bug report for RubyMCP.
+
+Before creating bug reports, please check [the issue list](https://github.com/nagstler/mcp_on_ruby/issues) to avoid duplicating an existing report. When you create a bug report, include as many details as possible:
+
+* **Use a clear and descriptive title**
+* **Describe the exact steps to reproduce the bug**
+* **Provide specific examples**
+* **Describe the behavior you observed**
+* **Explain the behavior you expected**
+* **Include screenshots or animated GIFs** if possible
+* **Include details about your configuration and environment**
+
+### Suggesting Enhancements
+
+This section guides you through submitting an enhancement suggestion for RubyMCP.
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:
+
+* **Use a clear and descriptive title**
+* **Provide a detailed description of the suggested enhancement**
+* **Explain why this enhancement would be useful**
+* **Specify which version you're using**
+* **Specify the name and version of the OS you're using**
+
+### Pull Requests
+
+* Fill in the required template
+* Follow the Ruby style guide
+* Include tests for new features
+* Document new code based on the rest of the codebase
+* End all files with a newline
+
+## Development Process
+
+### Setting Up Development Environment
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/yourusername/ruby_mcp.git
+cd ruby_mcp
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+
+### Testing
+
+Write tests for all new features
+Ensure all tests pass before submitting a pull request
+Run the full test suite locally before submission
+
+```bash
+bundle exec rspec
+```
+
+### Style Guidelines
+
+Code should follow the Ruby style guide
+Run RuboCop to check your code style
+
+```bash
+bundle exec rubocop
+```
+
+### Release Process
+
+RubyMCP follows Semantic Versioning.
+
+- MAJOR version for incompatible API changes
+- MINOR version for backward-compatible functionality additions
+- PATCH version for backward-compatible bug fixes
+
+### First-time Contributors
+If you're new to the project, look for issues labeled with good first issue which are ideal starting points for newcomers.
+
+### License
+By contributing to RubyMCP, you agree that your contributions will be licensed under the project's MIT License.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nagendra Dhanakeerthi
+
+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,491 @@
+<div align="center">
+
+# RubyMCP
+
+[![Build](https://github.com/nagstler/ruby_mcp/actions/workflows/build.yml/badge.svg)](https://github.com/nagstler/ruby_mcp/actions/workflows/build.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![RuboCop](https://github.com/nagstler/ruby_mcp/actions/workflows/rubocop.yml/badge.svg)](https://github.com/nagstler/ruby_mcp/actions/workflows/rubocop.yml)
+[![Test](https://github.com/nagstler/ruby_mcp/actions/workflows/test.yml/badge.svg)](https://github.com/nagstler/ruby_mcp/actions/workflows/test.yml)
+[![codecov](https://codecov.io/github/nagstler/ruby_mcp/graph/badge.svg?token=SG4EJEIHW3)](https://codecov.io/github/nagstler/ruby_mcp)
+
+<strong>The Ruby way to build MCP servers and clients.</strong>
+</div>
+
+## Introduction
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) provides a standardized way for applications to interact with various language model providers (like OpenAI, Anthropic, etc.) through a consistent interface.
+
+![design-1](https://github.com/user-attachments/assets/c1d76dc9-6aea-4cbb-a779-f0f7d85e71fb)
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Why RubyMCP?](#why-rubymcp)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Interactive Demo](#interactive-demo)
+- [Configuration Options](#configuration-options)
+- [Server Endpoints](#server-endpoints)
+- [Detailed Usage](#detailed-usage)
+  - [Creating a Context](#creating-a-context)
+  - [Adding a Message](#adding-a-message)
+  - [Generating a Response](#generating-a-response)
+  - [Streaming a Response](#streaming-a-response)
+  - [Uploading Content](#uploading-content)
+  - [Using Tool Calls](#using-tool-calls)
+- [Rails Integration](#rails-integration)
+- [Custom Storage Backend](#custom-storage-backend)
+- [Authentication](#authentication)
+- [Development](#development)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why RubyMCP?
+
+RubyMCP provides a Ruby implementation of the Model Context Protocol:
+
+- Standard API for multiple LLM providers
+- Context management for conversations
+- Support for streaming responses
+- File handling capabilities
+- Tool calling support
+- Authentication
+- Schema validation using dry-schema
+
+The library is designed to be straightforward to use while maintaining full compatibility with the MCP specification.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mcp_on_ruby'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself as:
+
+```
+$ gem install mcp_on_ruby
+```
+
+## Quick Start
+
+Here's how to get a basic MCP server running:
+
+```ruby
+require 'ruby_mcp'
+
+# Configure RubyMCP
+RubyMCP.configure do |config|
+  config.providers = {
+    openai: { api_key: ENV['OPENAI_API_KEY'] },
+    anthropic: { api_key: ENV['ANTHROPIC_API_KEY'] }
+  }
+end
+
+# Start the MCP server
+server = RubyMCP::Server::Controller.new
+server.start  # This will block the current thread
+```
+
+### Interactive Demo
+
+The repository includes an interactive demo that walks through all the key MCP concepts:
+
+First, start the example server:
+
+```bash
+cd examples/simple_server
+ruby server.rb
+```
+
+Then, in a separate terminal, run the client:
+
+```bash
+cd examples/simple_server
+ruby client.rb
+```
+This demo provides a guided tour of the MCP functionality, showing each step of creating contexts, adding messages, and generating responses with detailed explanations.
+
+## Configuration Options
+
+RubyMCP offers several configuration options:
+
+```ruby
+RubyMCP.configure do |config|
+  # LLM Provider configurations
+  config.providers = {
+    openai: { 
+      api_key: ENV['OPENAI_API_KEY'],
+      api_base: 'https://api.openai.com/v1' # Optional
+    },
+    anthropic: { 
+      api_key: ENV['ANTHROPIC_API_KEY'] 
+    }
+  }
+  
+  # Storage backend (:memory, :redis, :active_record, or custom)
+  config.storage = :memory
+  
+  # Server settings
+  config.server_port = 3000
+  config.server_host = "0.0.0.0"
+  
+  # Authentication settings
+  config.auth_required = false
+  config.jwt_secret = ENV['JWT_SECRET']
+  config.token_expiry = 3600 # 1 hour
+  
+  # Limits
+  config.max_contexts = 1000
+end
+```
+
+## Server Endpoints
+
+The MCP server provides the following endpoints:
+
+### Engines
+- `GET /engines` - List available language models
+
+### Contexts
+- `POST /contexts` - Create a new conversation context
+- `GET /contexts` - List existing contexts
+- `GET /contexts/:id` - Get details of a specific context
+- `DELETE /contexts/:id` - Delete a context
+
+### Messages
+- `POST /messages` - Add a message to a context
+
+### Generation
+- `POST /generate` - Generate a response from a language model
+- `POST /generate/stream` - Stream a response with incremental updates
+
+### Content
+- `POST /content` - Upload content (files)
+- `GET /content/:context_id/:id` - Retrieve uploaded content
+
+## Detailed Usage
+
+### Creating a Context
+
+```ruby
+# Using the HTTP API
+response = Faraday.post(
+  "http://localhost:3000/contexts",
+  {
+    messages: [
+      {
+        role: "system",
+        content: "You are a helpful assistant."
+      }
+    ],
+    metadata: {
+      user_id: "user_123",
+      conversation_name: "Technical Support"
+    }
+  }.to_json,
+  "Content-Type" => "application/json"
+)
+
+context_id = JSON.parse(response.body)["id"]
+```
+
+### Adding a Message
+
+```ruby
+Faraday.post(
+  "http://localhost:3000/messages",
+  {
+    context_id: context_id,
+    role: "user",
+    content: "What is the capital of France?"
+  }.to_json,
+  "Content-Type" => "application/json"
+)
+```
+
+### Generating a Response
+
+```ruby
+response = Faraday.post(
+  "http://localhost:3000/generate",
+  {
+    context_id: context_id,
+    engine_id: "anthropic/claude-3-sonnet-20240229",
+    max_tokens: 1000,
+    temperature: 0.7
+  }.to_json,
+  "Content-Type" => "application/json"
+)
+
+assistant_response = JSON.parse(response.body)["content"]
+```
+
+### Streaming a Response
+
+```ruby
+conn = Faraday.new do |f|
+  f.request :json
+  f.response :json
+  f.adapter :net_http
+end
+
+conn.post("http://localhost:3000/generate/stream") do |req|
+  req.headers["Content-Type"] = "application/json"
+  req.body = {
+    context_id: context_id,
+    engine_id: "openai/gpt-4",
+    temperature: 0.7
+  }.to_json
+  
+  req.options.on_data = Proc.new do |chunk, size, total|
+    event_data = chunk.split("data: ").last.strip
+    next if event_data.empty? || event_data == "[DONE]"
+    
+    event = JSON.parse(event_data)
+    if event["event"] == "generation.content" && event["content"]
+      print event["content"]
+    end
+  end
+end
+```
+
+### Uploading Content
+
+```ruby
+file_data = Base64.strict_encode64(File.read("example.pdf"))
+
+Faraday.post(
+  "http://localhost:3000/content",
+  {
+    context_id: context_id,
+    type: "file",
+    filename: "example.pdf",
+    content_type: "application/pdf",
+    file_data: file_data
+  }.to_json,
+  "Content-Type" => "application/json"
+)
+```
+
+### Using Tool Calls
+
+```ruby
+tools = [
+  {
+    type: "function",
+    function: {
+      name: "get_weather",
+      description: "Get the current weather for a location",
+      parameters: {
+        type: "object",
+        properties: {
+          location: {
+            type: "string",
+            description: "City and state, e.g., San Francisco, CA"
+          }
+        },
+        required: ["location"]
+      }
+    }
+  }
+]
+
+response = Faraday.post(
+  "http://localhost:3000/generate",
+  {
+    context_id: context_id,
+    engine_id: "openai/gpt-4",
+    tools: tools
+  }.to_json,
+  "Content-Type" => "application/json"
+)
+
+if response.body["tool_calls"]
+  # Handle tool calls
+  tool_calls = response.body["tool_calls"]
+  # Process tool calls and add tool response message
+end
+```
+
+## Rails Integration
+
+For Rails applications, create an initializer at `config/initializers/ruby_mcp.rb`:
+
+```ruby
+RubyMCP.configure do |config|
+  config.providers = {
+    openai: { api_key: ENV['OPENAI_API_KEY'] },
+    anthropic: { api_key: ENV['ANTHROPIC_API_KEY'] }
+  }
+  
+  # Use memory storage in development, consider persistent storage in production
+  if Rails.env.development? || Rails.env.test?
+    config.storage = :memory
+  else
+    config.storage = :memory  # Replace with persistent option when implemented
+  end
+  
+  # Enable authentication in production
+  if Rails.env.production?
+    config.auth_required = true
+    config.jwt_secret = ENV["JWT_SECRET"]
+  end
+end
+```
+
+And mount the server in your `config/routes.rb` file:
+
+```ruby
+Rails.application.routes.draw do
+  # Mount RubyMCP at /api/mcp
+  mount_mcp_at = "/api/mcp"
+  
+  Rails.application.config.middleware.use Rack::Config do |env|
+    env["SCRIPT_NAME"] = mount_mcp_at if env["PATH_INFO"].start_with?(mount_mcp_at)
+  end
+  
+  mount RubyMCP::Server::App.new.rack_app, at: mount_mcp_at
+  
+  # Rest of your routes
+  # ...
+end
+```
+
+## Custom Storage Backend
+
+You can implement custom storage backends by extending the base storage class:
+
+```ruby
+class RedisStorage < RubyMCP::Storage::Base
+  def initialize(options = {})
+    super
+    @redis = Redis.new(options)
+  end
+  
+  def create_context(context)
+    @redis.set("context:#{context.id}", JSON.dump(context.to_h))
+    context
+  end
+  
+  def get_context(context_id)
+    data = @redis.get("context:#{context_id}")
+    raise RubyMCP::Errors::ContextError, "Context not found: #{context_id}" unless data
+    
+    hash = JSON.parse(data, symbolize_names: true)
+    
+    # Create message objects
+    messages = hash[:messages].map do |msg|
+      RubyMCP::Models::Message.new(
+        role: msg[:role],
+        content: msg[:content],
+        id: msg[:id],
+        metadata: msg[:metadata]
+      )
+    end
+    
+    # Create the context
+    RubyMCP::Models::Context.new(
+      id: hash[:id],
+      messages: messages,
+      metadata: hash[:metadata]
+    )
+  end
+  
+  # Implement other required methods...
+end
+
+# Configure RubyMCP to use your custom storage
+RubyMCP.configure do |config|
+  config.storage = RedisStorage.new(url: ENV["REDIS_URL"])
+end
+```
+
+## Authentication
+
+To enable JWT authentication:
+
+```ruby
+RubyMCP.configure do |config|
+  config.auth_required = true
+  config.jwt_secret = ENV['JWT_SECRET']
+  config.token_expiry = 3600 # 1 hour
+end
+```
+
+Then, create and use JWT tokens:
+
+```ruby
+# Generate a token
+require 'jwt'
+
+payload = {
+  sub: "user_123",
+  exp: Time.now.to_i + 3600
+}
+
+token = JWT.encode(payload, ENV['JWT_SECRET'], 'HS256')
+
+# Use the token in requests
+conn = Faraday.new do |f|
+  f.request :json
+  f.response :json
+  f.adapter :net_http
+end
+
+conn.get("http://localhost:3000/contexts") do |req|
+  req.headers["Authorization"] = "Bearer #{token}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Running Tests
+
+```
+bundle exec rspec
+```
+
+### Local Development Server
+
+```
+bundle exec ruby examples/simple_server/server.rb
+```
+
+## Roadmap
+
+While RubyMCP is functional for basic use cases, there are several areas planned for improvement:
+
+- [ ] Persistent storage backends (Redis, ActiveRecord)
+- [ ] Complete test coverage, including integration tests
+- [ ] Improved error handling and recovery strategies
+- [ ] Rate limiting for provider APIs
+- [ ] Proper tokenization for context window management
+- [ ] More robust streaming implementation
+- [ ] Additional provider integrations
+
+:heart: Contributions in any of these areas are welcome!
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nagstler/mcp_on_ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).