rapitapir 0.1.2 → 2.0.0

data/docs/using-mcp.md

@@ -0,0 +1,93 @@
+# Using RapiTapir APIs as LLM Tools (MCP)
+
+RapiTapir supports the Model Context Protocol (MCP) to make your API endpoints discoverable and consumable by LLMs and AI agents.
+
+### How to Mark Endpoints for MCP Export
+
+Use the `.mcp_export` method in your endpoint DSL chain:
+
+```ruby
+endpoint(
+  GET('/hello')
+    .query(:name, T.string, description: 'Name to greet')
+    .ok(T.hash({ "message" => T.string }))
+    .enable_mcp  # Mark for MCP export
+    .build
+) do |inputs|
+  { message: "Hello, #{inputs[:name]}!" }
+end
+```
+
+### CLI Usage
+
+Generate MCP context using the command line:
+
+```bash
+# Generate MCP context for all marked endpoints
+rapitapir generate mcp --endpoints api.rb --output mcp-context.json
+
+# Alternative export command
+rapitapir export mcp --endpoints api.rb --output mcp-context.json
+```
+
+### Ruby API Usage
+
+Use the MCP exporter directly in Ruby code:
+
+```ruby
+require 'rapitapir/ai/mcp'
+
+# Load your endpoints
+endpoints = [your_endpoint_list]
+
+# Create exporter and generate context
+exporter = RapiTapir::AI::MCP::Exporter.new(endpoints)
+mcp_context = exporter.as_mcp_context
+
+# Save to file
+File.write('mcp-context.json', JSON.pretty_generate(mcp_context))
+```
+
+### Example Output
+
+The generated MCP context includes:
+
+```json
+{
+  "name": "RapiTapir API Context",
+  "version": "1.0.0",
+  "endpoints": [
+    {
+      "name": "get__users__id_",
+      "method": "GET", 
+      "path": "/users/{id}",
+      "summary": "Retrieve a user by ID",
+      "description": "Fetches a single user record by their unique identifier",
+      "input_schema": {
+        "id": {
+          "type": "integer",
+          "kind": "path",
+          "required": true
+        }
+      },
+      "output_schema": {
+        "json": {
+          "type": {
+            "id": "integer",
+            "name": "string",
+            "email": "string"
+          }
+        }
+      },
+      "examples": []
+    }
+  ]
+}
+```
+
+### Use Cases
+- LLM/agent tool discovery
+- Automated API documentation for AI
+- Integration with agent frameworks (LangChain, OpenAI, etc.)
+
+See the AI integration plan for more details.

data/examples/ai/knowledge_base_rag.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+# Add the project root to the load path for development
+project_root = File.expand_path('../../', __dir__)
+$LOAD_PATH.unshift(File.join(project_root, 'lib')) unless $LOAD_PATH.include?(File.join(project_root, 'lib'))
+
+require 'rapitapir'
+require 'rapitapir/ai/rag'
+require 'json'
+
+# Example: Knowledge Base API with RAG Support
+module KnowledgeBaseAPI
+  extend RapiTapir::DSL
+
+  # Type alias for convenience
+  T = RapiTapir::Types
+
+  # Define schemas
+  ASK_SCHEMA = T.hash({
+    'question' => T.string,
+    'user_id' => T.string
+  }).freeze
+
+  ANSWER_SCHEMA = T.hash({
+    'answer' => T.string,
+    'sources' => T.array(T.string),
+    'timestamp' => T.string
+  }).freeze
+
+  CHAT_INPUT_SCHEMA = T.hash({
+    'message' => T.string
+  }).freeze
+
+  CHAT_OUTPUT_SCHEMA = T.hash({
+    'response' => T.string
+  }).freeze
+
+  # Ask a question using RAG
+  ASK_QUESTION = RapiTapir.post('/ask')
+    .json_body(ASK_SCHEMA)
+    .ok(ANSWER_SCHEMA)
+    .rag_inference(
+      llm: :openai,
+      retrieval: :memory,
+      context_fields: [:user_id],
+      config: {
+        llm: { api_key: 'mock' },
+        retrieval: {
+          documents: [
+            { content: 'RapiTapir is a Ruby API framework that provides type-safe endpoints.' },
+            { content: 'RAG combines document retrieval with LLM text generation.' },
+            { content: 'This API demonstrates AI-powered question answering.' }
+          ]
+        }
+      }
+    )
+    .summary('Ask a question about the knowledge base')
+    .mcp_export
+
+  # Simple chat
+  CHAT = RapiTapir.post('/chat')
+    .json_body(CHAT_INPUT_SCHEMA)
+    .ok(CHAT_OUTPUT_SCHEMA)
+    .rag_inference(
+      llm: :openai,
+      retrieval: :memory,
+      config: {
+        llm: { api_key: 'mock' },
+        retrieval: {
+          documents: [
+            { content: 'RapiTapir supports MCP for AI agent integration.' }
+          ]
+        }
+      }
+    )
+    .summary('Chat with AI')
+    .mcp_export
+end
+
+# Endpoints for CLI
+knowledge_base_api = [KnowledgeBaseAPI::ASK_QUESTION, KnowledgeBaseAPI::CHAT]

data/examples/ai/user_management_mcp.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/rapitapir'
+require_relative '../../lib/rapitapir/endpoint_registry'
+
+# Example: User Management API with MCP Export
+# This demonstrates how to mark endpoints for MCP export for AI/LLM consumption
+
+class UserManagementAPI
+  include RapiTapir::DSL
+
+  # User schema for consistent typing
+  USER_SCHEMA = {
+    id: :integer,
+    name: :string,
+    email: :string,
+    created_at: :datetime
+  }.freeze
+
+  # Endpoint 1: Get user by ID - marked for MCP export
+  GET_USER = RapiTapir.get('/users/{id}')
+    .in(path_param(:id, :integer))
+    .out(json_body(USER_SCHEMA))
+    .summary('Retrieve a user by ID')
+    .description('Fetches a single user record by their unique identifier')
+    .mcp_export  # Mark for MCP export
+
+  # Endpoint 2: Create new user - marked for MCP export  
+  CREATE_USER = RapiTapir.post('/users')
+    .in(json_body({
+      name: :string,
+      email: :string
+    }))
+    .out(status_code(201))
+    .out(json_body(USER_SCHEMA))
+    .summary('Create a new user')
+    .description('Creates a new user account with name and email')
+    .mcp_export  # Mark for MCP export
+
+  # Endpoint 3: Update user - NOT marked for MCP export
+  UPDATE_USER = RapiTapir.put('/users/{id}')
+    .in(path_param(:id, :integer))
+    .in(json_body({
+      name: :string,
+      email: :string
+    }))
+    .out(json_body(USER_SCHEMA))
+    .summary('Update an existing user')
+    .description('Updates user information')
+    # No .mcp_export - this endpoint won't be included in MCP context
+
+  # Endpoint 4: List users with pagination - marked for MCP export
+  LIST_USERS = RapiTapir.get('/users')
+    .in(query(:page, :integer, required: false))
+    .in(query(:limit, :integer, required: false))
+    .out(json_body({
+      users: [:array, USER_SCHEMA],
+      total: :integer,
+      page: :integer,
+      limit: :integer
+    }))
+    .summary('List all users')
+    .description('Retrieves a paginated list of all users')
+    .mcp_export  # Mark for MCP export
+
+  # Store endpoints for export
+  ALL_ENDPOINTS = [GET_USER, CREATE_USER, UPDATE_USER, LIST_USERS].freeze
+
+  # Register endpoints in global registry
+  RapiTapir::EndpointRegistry.register_all(ALL_ENDPOINTS)
+end
+
+# Usage demonstration
+if __FILE__ == $PROGRAM_NAME
+  puts "User Management API Example"
+  puts "==========================="
+  
+  # Show which endpoints are marked for MCP export
+  mcp_endpoints = UserManagementAPI::ALL_ENDPOINTS.select(&:mcp_export?)
+  puts "\nEndpoints marked for MCP export:"
+  mcp_endpoints.each do |ep|
+    puts "- #{ep.method.upcase} #{ep.path} (#{ep.metadata[:summary]})"
+  end
+  
+  # Generate MCP context
+  require_relative '../../lib/rapitapir/ai/mcp'
+  exporter = RapiTapir::AI::MCP::Exporter.new(UserManagementAPI::ALL_ENDPOINTS)
+  mcp_context = exporter.as_mcp_context
+  
+  puts "\nGenerated MCP Context:"
+  puts JSON.pretty_generate(mcp_context)
+end

data/examples/ai/user_validation_llm.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+# Add the project root to the load path for development
+project_root = File.expand_path('../../', __dir__)
+$LOAD_PATH.unshift(File.join(project_root, 'lib')) unless $LOAD_PATH.include?(File.join(project_root, 'lib'))
+
+require 'rapitapir'
+require 'rapitapir/ai/llm_instruction'
+require 'json'
+
+# Type alias for convenience (avoid warning if already defined)
+T = RapiTapir::Types unless defined?(T)
+
+module UserValidationAPI
+  # User creation validation schema
+  USER_INPUT_SCHEMA = T.hash({
+    'name' => T.string(min_length: 2, max_length: 50),
+    'email' => T.email,
+    'age' => T.integer(minimum: 18, maximum: 120),
+    'preferences' => T.optional(T.hash({
+      'newsletter' => T.boolean,
+      'notifications' => T.boolean
+    }))
+  }).freeze
+
+  USER_OUTPUT_SCHEMA = T.hash({
+    'id' => T.integer,
+    'name' => T.string,
+    'email' => T.string,
+    'status' => T.string,
+    'created_at' => T.datetime
+  }).freeze
+
+  VALIDATION_ERROR_SCHEMA = T.hash({
+    'error' => T.string,
+    'field_errors' => T.array(T.hash({
+      'field' => T.string,
+      'message' => T.string,
+      'code' => T.string
+    }))
+  }).freeze
+
+  # Data transformation schemas
+  LEGACY_USER_INPUT = T.hash({
+    'full_name' => T.string,
+    'email_address' => T.string,
+    'birth_year' => T.integer,
+    'settings' => T.optional(T.string) # JSON string in legacy format
+  }).freeze
+
+  # Analytics schema
+  USER_ANALYTICS_SCHEMA = T.hash({
+    'user_count' => T.integer,
+    'active_users' => T.integer,
+    'signup_rate' => T.float,
+    'demographics' => T.hash({
+      'avg_age' => T.float,
+      'age_distribution' => T.array(T.hash({
+        'range' => T.string,
+        'count' => T.integer
+      }))
+    })
+  }).freeze
+
+  # Validation endpoint with LLM instruction for input validation
+  CREATE_USER = RapiTapir.post('/users')
+    .json_body(USER_INPUT_SCHEMA)
+    .ok(USER_OUTPUT_SCHEMA)
+    .error_out(400, VALIDATION_ERROR_SCHEMA)
+    .llm_instruction(
+      purpose: :validation,
+      fields: [:body] # Focus on request body validation
+    )
+    .summary('Create a new user with validation')
+    .description('Creates a new user account with comprehensive input validation and business rule checking')
+    .mcp_export
+
+  # Transformation endpoint for legacy data migration
+  MIGRATE_LEGACY_USER = RapiTapir.post('/users/migrate')
+    .json_body(LEGACY_USER_INPUT)
+    .ok(USER_OUTPUT_SCHEMA)
+    .llm_instruction(
+      purpose: :transformation,
+      fields: :all
+    )
+    .summary('Migrate legacy user data to new format')
+    .description('Transforms legacy user data format to current schema with proper field mapping')
+    .mcp_export
+
+  # Analysis endpoint for user analytics
+  USER_ANALYTICS = RapiTapir.get('/users/analytics')
+    .query(:start_date, :date)
+    .query(:end_date, :date) 
+    .query(:segment, T.optional(T.string))
+    .ok(USER_ANALYTICS_SCHEMA)
+    .llm_instruction(
+      purpose: :analysis,
+      fields: [:json] # Focus on analyzing the response data
+    )
+    .summary('Get user analytics and insights')
+    .description('Provides comprehensive user analytics including demographics and engagement metrics')
+    .mcp_export
+
+  # Documentation endpoint for API reference
+  USER_SEARCH = RapiTapir.get('/users/search')
+    .query(:q, T.string(min_length: 1))
+    .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)))
+    .query(:offset, T.optional(T.integer(minimum: 0)))
+    .ok(T.hash({
+      'users' => T.array(USER_OUTPUT_SCHEMA),
+      'total_count' => T.integer,
+      'has_more' => T.boolean
+    }))
+    .llm_instruction(
+      purpose: :documentation,
+      fields: :all
+    )
+    .summary('Search for users')
+    .description('Full-text search across user profiles with pagination support')
+    .mcp_export
+
+  # Testing endpoint for comprehensive test generation
+  UPDATE_USER = RapiTapir.put('/users/:id')
+    .path_param(:id, :integer)
+    .json_body(T.hash({
+      'name' => T.optional(T.string(min_length: 2, max_length: 50)),
+      'email' => T.optional(T.email),
+      'preferences' => T.optional(T.hash({
+        'newsletter' => T.boolean,
+        'notifications' => T.boolean
+      }))
+    }))
+    .ok(USER_OUTPUT_SCHEMA)
+    .error_out(404, T.hash({'error' => T.string}))
+    .error_out(400, VALIDATION_ERROR_SCHEMA)
+    .llm_instruction(
+      purpose: :testing,
+      fields: :all
+    )
+    .summary('Update user information')
+    .description('Updates user profile with partial data and validation')
+    .mcp_export
+
+  # Completion endpoint for smart field suggestions
+  USER_PROFILE_COMPLETION = RapiTapir.post('/users/complete')
+    .json_body(T.hash({
+      'partial_profile' => T.hash({
+        'name' => T.optional(T.string),
+        'email' => T.optional(T.string),
+        'location' => T.optional(T.string),
+        'interests' => T.optional(T.array(T.string))
+      })
+    }))
+    .ok(T.hash({
+      'suggestions' => T.hash({
+        'name' => T.optional(T.array(T.string)),
+        'email' => T.optional(T.string),
+        'location' => T.optional(T.array(T.string)),
+        'interests' => T.optional(T.array(T.string))
+      }),
+      'confidence_scores' => T.hash({
+        'name' => T.optional(T.float),
+        'email' => T.optional(T.float),
+        'location' => T.optional(T.float),
+        'interests' => T.optional(T.float)
+      })
+    }))
+    .llm_instruction(
+      purpose: :completion,
+      fields: [:body]
+    )
+    .summary('Get smart profile completion suggestions')
+    .description('Provides intelligent suggestions for completing user profile data')
+    .mcp_export
+end
+
+# Endpoints for CLI
+user_validation_api = [
+  UserValidationAPI::CREATE_USER,
+  UserValidationAPI::MIGRATE_LEGACY_USER,
+  UserValidationAPI::USER_ANALYTICS,
+  UserValidationAPI::USER_SEARCH,
+  UserValidationAPI::UPDATE_USER,
+  UserValidationAPI::USER_PROFILE_COMPLETION
+]

data/examples/rails/RAILS_8_GUIDE.md

@@ -0,0 +1,165 @@
+# Rails 8 + RapiTapir Quick Start Guide
+
+## 🚀 How to Fix the `uninitialized constant RapiTapir::Server::Rails::ControllerBase` Error
+
+The error you're encountering is due to the **loading order**. RapiTapir's Rails integration requires Rails to be loaded first.
+
+### ✅ **Solution: Correct Loading Order**
+
+In your Rails application, ensure this loading order:
+
+#### 1. In your `Gemfile`:
+```ruby
+source 'https://rubygems.org'
+ruby '3.2.0'
+
+gem 'rails', '~> 8.0.0'  # Rails 8
+gem 'rapitapir', '~> 1.0'  # RapiTapir after Rails
+
+# Other gems...
+gem 'sqlite3'
+gem 'puma'
+```
+
+#### 2. In your application (or initializer):
+```ruby
+# This is already handled by Rails bundler, but if you need manual loading:
+
+# 1. Rails loads first (via bundle/require in application.rb)
+require 'rails/all'
+
+# 2. RapiTapir loads after Rails
+require 'rapitapir'  # Usually handled by bundler
+
+# 3. Now you can use RapiTapir classes
+class ApplicationController < RapiTapir::Server::Rails::ControllerBase
+  # This works!
+end
+```
+
+### 🧪 **Test with Our Runnable Example**
+
+The easiest way to verify everything works:
+
+```bash
+cd examples/rails
+ruby traditional_app_runnable.rb
+```
+
+This should start successfully and show:
+```
+🚀 Starting Traditional Rails App with RapiTapir on http://localhost:3000
+📚 API Documentation: http://localhost:3000/docs
+📋 OpenAPI Spec: http://localhost:3000/openapi.json
+🏥 Health Check: http://localhost:3000/health
+```
+
+### 🔧 **For New Rails 8 Applications**
+
+#### 1. Create Rails App
+```bash
+rails new my_api --api
+cd my_api
+```
+
+#### 2. Add RapiTapir to Gemfile
+```ruby
+# Gemfile
+gem 'rapitapir', '~> 1.0'
+```
+
+#### 3. Install
+```bash
+bundle install
+```
+
+#### 4. Update ApplicationController
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < RapiTapir::Server::Rails::ControllerBase
+  rapitapir do
+    development_defaults! if Rails.env.development?
+    
+    # Global error responses
+    error_out(json_body(error: T.string), 404)
+    error_out(json_body(error: T.string, errors: T.array(T.string).optional), 422)
+    
+    # Health endpoint
+    GET('/health')
+      .out(json_body(status: T.string, timestamp: T.string))
+      .summary("Health check")
+  end
+  
+  def health_check
+    { status: 'ok', timestamp: Time.current.iso8601 }
+  end
+end
+```
+
+#### 5. Create API Controllers
+```ruby
+# app/controllers/api/v1/users_controller.rb
+class Api::V1::UsersController < ApplicationController
+  rapitapir do
+    user_type = T.hash(id: T.integer, name: T.string, email: T.string)
+    
+    GET('/api/v1/users')
+      .out(json_body(users: T.array(user_type)))
+      .summary("List users")
+      .tag("Users")
+  end
+  
+  def list_users
+    { users: [{ id: 1, name: "Test User", email: "test@example.com" }] }
+  end
+end
+```
+
+#### 6. Update Routes
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  rapitapir_routes_for ApplicationController
+  
+  namespace :api do
+    namespace :v1 do
+      rapitapir_routes_for 'Api::V1::UsersController'
+    end
+  end
+end
+```
+
+#### 7. Start Server
+```bash
+rails server
+```
+
+Visit:
+- 🏥 Health: http://localhost:3000/health  
+- 📚 Docs: http://localhost:3000/docs
+- 👥 Users: http://localhost:3000/api/v1/users
+
+### ⚠️ **Common Issues & Solutions**
+
+#### Issue: `uninitialized constant RapiTapir::Server::Rails::ControllerBase`
+**Solution**: Make sure Rails is loaded before RapiTapir. In most Rails apps, this happens automatically via bundler.
+
+#### Issue: `NoMethodError: undefined method 'rapitapir_routes_for'`
+**Solution**: Ensure RapiTapir's Rails integration is loaded. Add to `config/application.rb`:
+```ruby
+require 'rapitapir'
+```
+
+#### Issue: Documentation not showing up
+**Solution**: Make sure you have `development_defaults!` in your rapitapir block.
+
+### 🎉 **Benefits of Rails 8 + RapiTapir**
+
+- ✅ **Modern Rails**: Latest Rails 8 features and performance
+- ✅ **Type Safety**: Automatic input validation and output schemas  
+- ✅ **Auto Documentation**: Swagger UI and OpenAPI 3.0 specs
+- ✅ **Clean Syntax**: Sinatra-like DSL in Rails controllers
+- ✅ **Zero Config**: Works out of the box with `development_defaults!`
+- ✅ **Production Ready**: Error handling, health checks, monitoring
+
+The combination of Rails 8 and RapiTapir gives you the best of both worlds: Rails' maturity and ecosystem with RapiTapir's elegant API design! 🚀

data/examples/rails/RAILS_LOADING_FIX.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Instructions for using RapiTapir with Rails
+# 
+# To fix the "uninitialized constant RapiTapir::Server::Rails::ControllerBase" error:
+#
+# 1. In your Rails application, make sure to require 'rapitapir' AFTER Rails is loaded
+# 2. In your Gemfile, add:
+#    gem 'rapitapir'
+# 3. In your ApplicationController or in an initializer, add:
+#    require 'rapitapir' (only if needed - bundler usually handles this)
+#
+# The error occurs because RapiTapir's Rails integration requires Rails and ActiveSupport
+# to be loaded first.
+
+# For the traditional_app_runnable.rb example, the require order should be:
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'rails', '~> 8.0'
+  gem 'sqlite3'
+  gem 'puma'
+end
+
+# Load Rails first
+require 'rails/all'
+
+# THEN load RapiTapir (this is the key!)
+require_relative '../../../lib/rapitapir'
+
+# Now you can use RapiTapir::Server::Rails::ControllerBase
+
+puts "✅ This order works correctly!"