micro_mcp 0.1.0 → 0.1.4

data/README.md

@@ -1,28 +1,59 @@
 # MicroMcp
 
-TODO: Delete this and the text below, and describe your gem
+MicroMcp is a tiny framework for building [MCP](https://github.com/openai/AIAPI-Protocol) servers in Ruby.  It ships with a Rust extension that handles the low level protocol while your Ruby code focuses on registering tools.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/micro_mcp`. To experiment with that code, run `bin/console` for an interactive prompt.
+The gem is available on [RubyGems](https://rubygems.org/gems/micro_mcp).
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add the gem to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem "micro_mcp"
+```
+
+Then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it directly with RubyGems:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install micro_mcp
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+Define one or more tools and start the server:
+
+```ruby
+require "micro_mcp"
+
+ MicroMcp::ToolRegistry.register_tool(name: "say_hello") do
+  "Hello World!"
+end
+
+# Tools can also accept arguments defined using JSON Schema.
+# The arguments hash is provided as the first block parameter.
+ MicroMcp::ToolRegistry.register_tool(
+  name: "add_numbers",
+  description: "Adds two integers",
+  arguments: {
+    "type" => "object",
+    "properties" => {
+      "a" => {"type" => "integer"},
+      "b" => {"type" => "integer"}
+    },
+    "required" => ["a", "b"]
+  }
+) do |args, _runtime|
+  (args["a"] + args["b"]).to_s
+end
+
+MicroMcp.start_server
+```
 
 ## Development
 

data/docs/changes/ERGONOMIC_IMPROVEMENTS.md

@@ -0,0 +1,133 @@
+# MicroMCP Ergonomic Improvements
+
+## Problem
+
+The original MCP tool creation was error-prone due to several issues:
+
+1. **Missing return value handling** - Easy to forget `result["content"]["text"]`
+2. **Cryptic error messages** - "no implicit conversion of Hash into String"
+3. **Symbol vs String key confusion** - JSON requires string keys
+4. **Repetitive boilerplate** - Same patterns repeated in every tool
+5. **No validation** - Hard to debug parameter issues
+
+## Solution
+
+We've added several layers of improvements to make tool creation more ergonomic and less error-prone:
+
+### 1. Helper Methods (`runtime_helpers.rb`)
+
+```ruby
+# Simple question-answering
+runtime.ask_assistant("What is the capital of France?")
+
+# Multi-message conversations
+runtime.chat_with_assistant([
+  "Let's discuss Ruby",
+  {"role" => "assistant", "content" => {"type" => "text", "text" => "I'd love to help!"}},
+  "What are the key features?"
+])
+
+# Safe wrapper with validation
+runtime.safe_create_message(params)
+```
+
+### 2. Enhanced Tool Registration (`tool_registry.rb`)
+
+```ruby
+# One-liner for simple Q&A tools
+TR.register_qa_tool(
+  name: "ask",
+  description: "Ask a question"
+)
+
+# Enhanced registration with error handling
+TR.register_assistant_tool(name: "custom", description: "Custom tool") do |args, runtime|
+  runtime.ask_assistant(args["question"])
+end
+```
+
+### 3. Validation System (`validation_helpers.rb`)
+
+- Pre-flight validation of `create_message` parameters
+- Clear error messages for common mistakes
+- Automatic symbol-to-string key conversion
+- Structural validation of message format
+
+## Response Format Handling
+
+The system now properly handles the MCP response format:
+
+```json
+{
+  "role": "assistant",
+  "content": {
+    "type": "text",
+    "text": "The actual response text"
+  },
+  "model": "o4-mini",
+  "stopReason": "endTurn"
+}
+```
+
+Helper methods automatically extract `result["content"]["text"]` with proper error handling.
+
+## Before vs After
+
+### Before (Error-prone)
+```ruby
+TR.register_tool(
+  name: "ask",
+  arguments: S.object(question: S.string.required)
+) do |args, runtime|
+  result = runtime.create_message({
+    "messages" => [
+      {"role" => "user", "content" => {"type" => "text", "text" => args["question"]}}
+    ],
+    "modelPreferences" => {
+      "hints" => [{"name" => "o4-mini"}],
+      "intelligencePriority" => 0.8,
+      "speedPriority" => 0.5
+    },
+    "systemPrompt" => "You are a helpful assistant.",
+    "maxTokens" => 100
+  })
+  result["content"]["text"]  # Easy to forget!
+end
+```
+
+### After (Simple)
+```ruby
+# One-liner approach
+TR.register_qa_tool(name: "ask", description: "Ask a question")
+
+# Or with customization
+TR.register_assistant_tool(name: "ask", description: "Ask a question") do |args, runtime|
+  runtime.ask_assistant(args["question"])
+end
+```
+
+## Error Handling
+
+The new system provides:
+
+1. **Pre-validation** - Catches errors before sending to MCP
+2. **Clear error messages** - Explains what went wrong
+3. **Automatic error recovery** - Handles common formatting issues
+4. **Debug mode** - Set `ENV['MCP_DEBUG']` for detailed logging
+
+## Backward Compatibility
+
+All existing tools continue to work unchanged. The improvements are additive.
+
+## Usage Examples
+
+See `test/support/ergonomic_test.rb` and `test/support/ergonomic_examples.rb` for comprehensive examples.
+
+## Key Benefits
+
+1. ✅ **Reduced boilerplate** - Simple tools are one-liners
+2. ✅ **Better error messages** - Clear validation feedback
+3. ✅ **Automatic result extraction** - No more forgetting return values
+4. ✅ **Symbol key safety** - Automatic string conversion
+5. ✅ **Validation** - Catch issues before they cause problems
+6. ✅ **Backward compatible** - Existing code keeps working

data/ext/micro_mcp/AGENTS.md

@@ -0,0 +1,66 @@
+# Rust Development Agent Instructions
+
+This directory contains Rust code that interfaces with Ruby via FFI. These instructions help agents navigate Rust source code efficiently.
+
+## Environment Setup
+
+The following environment variables should be exported for Rust source navigation:
+
+```bash
+# Standard library source (requires `rustup component add rust-src`)
+export RUST_STD_SRC="$(rustc --print sysroot)/lib/rustlib/src/rust/library"
+
+# Crates.io tarball cache (downloaded by `cargo fetch`)
+export RUST_CRATE_SRC="${CARGO_HOME:-$HOME/.cargo}/registry/src"
+
+# Git checkouts for dependencies using `git = "..."`
+export RUST_GIT_SRC="${CARGO_HOME:-$HOME/.cargo}/git/checkouts"
+```
+
+## Helper Commands
+
+### Locating Standard Library Items
+
+```bash
+rg "pub .* <TypeOrFnName>" "$RUST_STD_SRC"
+```
+
+### Finding Versioned Crates
+
+```bash
+# Example: finding serde 1.0.200
+rg --files "$RUST_CRATE_SRC" | grep '/serde-1\.0\.200/' | head -n1
+# Then search inside that path
+```
+
+### Locating Git Dependencies
+
+```bash
+# Example: finding a crate directory containing 'mycrate'
+find "$RUST_GIT_SRC" -maxdepth 3 -type d -name '*mycrate*' | head
+```
+
+### Quick Jump to Crate Root
+
+```bash
+cargo metadata --format-version 1 --no-deps \
+  | jq -r '.packages[] | select(.name=="tokio") | .manifest_path' \
+  | xargs dirname
+```
+
+## Agent Rules
+
+1. **Source Code Lookup Order**: Always search in this order:
+   - `$RUST_STD_SRC` (standard library)
+   - `$RUST_CRATE_SRC` (crates.io dependencies)
+   - `$RUST_GIT_SRC` (git dependencies)
+
+2. **Exact Signatures**: Copy the **exact** function/type signature you find in the source. If no match is found, report:
+   - Which symbol is missing
+   - Which directory was searched
+   - Stop and ask for clarification
+
+3. **FFI Considerations**: This project uses Ruby FFI, so pay attention to:
+   - Memory management between Rust and Ruby
+   - Proper error handling across language boundaries
+   - Thread safety considerations

data/ext/micro_mcp/Cargo.toml

@@ -15,7 +15,9 @@ magnus = { version = "0.7", features = ["rb-sys"] }
 rb-sys = { version = "*", default-features = false, features = [
   "stable-api-compiled-fallback",
 ] }
-rust-mcp-sdk = "0.4.3"
+rust-mcp-sdk = { version = "0.4.3", default-features = false, features = [
+  "server", "client", "2025_03_26"
+]}
 serde = "1.0.219"
 serde_json = "1.0.140"
 tokio = "1.45.1"

data/ext/micro_mcp/src/lib.rs

@@ -1,12 +1,28 @@
-mod utils;
 mod server;
+mod utils;
 
-use magnus::{function, prelude::*, Error, Ruby};
+use magnus::{function, method, prelude::*, Error, Ruby};
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
-    let module = ruby.define_module("MicroMcpNative")?;
-    module.define_singleton_method("start_server", function!(server::start_server, 0))?;
-    module.define_singleton_method("register_tool", function!(server::register_tool, 3))?;
+    let native = ruby.define_module("MicroMcpNative")?;
+    native.define_singleton_method("start_server", function!(server::start_server, 0))?;
+    native.define_singleton_method("shutdown_server", function!(server::shutdown_server, 0))?;
+    native.define_singleton_method("register_tool", function!(server::register_tool, 4))?;
+
+    let parent = ruby.define_module("MicroMcp")?;
+    let class = parent.define_class("Runtime", ruby.class_object())?;
+    class.define_method(
+        "is_initialized",
+        method!(server::RubyMcpServer::is_initialized, 0),
+    )?;
+    class.define_method(
+        "client_supports_sampling",
+        method!(server::RubyMcpServer::client_supports_sampling, 0),
+    )?;
+    class.define_method(
+        "create_message",
+        method!(server::RubyMcpServer::create_message, 1),
+    )?;
     Ok(())
 }