rapitapir 0.1.2 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.rubocop.yml +7 -7
- data/.rubocop_todo.yml +88 -0
- data/CHANGELOG.md +29 -1
- data/README.md +1339 -236
- data/RUBY_WEEKLY_LAUNCH_POST.md +200 -0
- data/docs/RAILS_INTEGRATION_IMPLEMENTATION.md +209 -0
- data/docs/SINATRA_EXTENSION.md +399 -348
- data/docs/STRICT_VALIDATION.md +229 -0
- data/docs/VALIDATION_IMPROVEMENTS.md +218 -0
- data/docs/adr/0001-base-class-strategy.md +33 -0
- data/docs/adr/0002-type-shortcut-and-type-system.md +30 -0
- data/docs/adr/0003-openapi-source-of-truth.md +32 -0
- data/docs/adr/0004-client-generation-typescript-first.md +34 -0
- data/docs/adr/0005-auth-architecture.md +32 -0
- data/docs/adr/0006-observability-defaults.md +30 -0
- data/docs/adr/0007-ai-scope-and-boundaries.md +30 -0
- data/docs/adr/README.md +46 -0
- data/docs/adr/template.md +24 -0
- data/docs/ai-integration-plan.md +112 -0
- data/docs/auto-derivation.md +505 -92
- data/docs/blueprint.md +92 -4
- data/docs/endpoint-definition.md +536 -129
- data/docs/implementation-status.md +1 -1
- data/docs/n8n-integration.md +212 -0
- data/docs/observability.md +810 -500
- data/docs/using-mcp.md +93 -0
- data/examples/ai/knowledge_base_rag.rb +83 -0
- data/examples/ai/user_management_mcp.rb +92 -0
- data/examples/ai/user_validation_llm.rb +187 -0
- data/examples/auto_derivation_ruby_friendly.rb +44 -113
- data/examples/cli/user_api_endpoints.rb +63 -36
- data/examples/demo_api.rb +57 -18
- data/examples/enterprise_extension_demo.rb +13 -13
- data/examples/enterprise_rapitapir_api.rb +81 -93
- data/examples/nocodb/nocodb_scaffold/Gemfile +22 -0
- data/examples/nocodb/nocodb_scaffold/README.md +10 -0
- data/examples/nocodb/nocodb_scaffold/Rakefile +7 -0
- data/examples/nocodb/nocodb_scaffold/app/api/app.rb +1139 -0
- data/examples/nocodb/nocodb_scaffold/app/models/email_template.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/faq.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/feature.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/idea.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/itinerary_day.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/route.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/subscriber.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/tour.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/webhook.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models_loader.rb +3 -0
- data/examples/nocodb/nocodb_scaffold/config/database.yml +11 -0
- data/examples/nocodb/nocodb_scaffold/config.ru +9 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152012_create_features.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152013_create_tours.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152014_create_routes.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152015_create_itinerary_days.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152016_create_subscribers.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152017_create_email_templates.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152018_create_faqs.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152019_create_webhooks.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152020_create_ideas.rb +10 -0
- data/examples/nocodb/swagger.json +4378 -0
- data/examples/production_ready_example.rb +78 -58
- data/examples/rails/RAILS_8_GUIDE.md +165 -0
- data/examples/rails/RAILS_LOADING_FIX.rb +35 -0
- data/examples/rails/README.md +497 -0
- data/examples/rails/comprehensive_test.rb +91 -0
- data/examples/rails/config/routes.rb +48 -0
- data/examples/rails/debug_controller.rb +63 -0
- data/examples/rails/detailed_test.rb +46 -0
- data/examples/rails/enhanced_users_controller.rb +278 -0
- data/examples/rails/final_server_test.rb +50 -0
- data/examples/rails/hello_world_app.rb +116 -0
- data/examples/rails/hello_world_controller.rb +186 -0
- data/examples/rails/hello_world_routes.rb +28 -0
- data/examples/rails/rails8_minimal_demo.rb +132 -0
- data/examples/rails/rails8_simple_demo.rb +140 -0
- data/examples/rails/rails8_working_demo.rb +255 -0
- data/examples/rails/real_world_blog_api.rb +510 -0
- data/examples/rails/server_test.rb +46 -0
- data/examples/rails/test_direct_processing.rb +41 -0
- data/examples/rails/test_hello_world.rb +80 -0
- data/examples/rails/test_rails_integration.rb +54 -0
- data/examples/rails/traditional_app/Gemfile +37 -0
- data/examples/rails/traditional_app/README.md +265 -0
- data/examples/rails/traditional_app/app/controllers/api/v1/posts_controller.rb +254 -0
- data/examples/rails/traditional_app/app/controllers/api/v1/users_controller.rb +220 -0
- data/examples/rails/traditional_app/app/controllers/application_controller.rb +86 -0
- data/examples/rails/traditional_app/app/controllers/application_controller_simplified.rb +87 -0
- data/examples/rails/traditional_app/app/controllers/documentation_controller.rb +149 -0
- data/examples/rails/traditional_app/app/controllers/health_controller.rb +42 -0
- data/examples/rails/traditional_app/config/routes.rb +25 -0
- data/examples/rails/traditional_app/config/routes_best_practice.rb +25 -0
- data/examples/rails/traditional_app/config/routes_simplified.rb +36 -0
- data/examples/rails/traditional_app_runnable.rb +406 -0
- data/examples/rails/users_controller.rb +4 -1
- data/examples/serverless/Gemfile +43 -0
- data/examples/serverless/QUICKSTART.md +331 -0
- data/examples/serverless/README.md +520 -0
- data/examples/serverless/aws_lambda_example.rb +307 -0
- data/examples/serverless/aws_sam_template.yaml +215 -0
- data/examples/serverless/azure_functions_example.rb +407 -0
- data/examples/serverless/deploy.rb +204 -0
- data/examples/serverless/gcp_cloud_functions_example.rb +367 -0
- data/examples/serverless/gcp_function.yaml +23 -0
- data/examples/serverless/host.json +24 -0
- data/examples/serverless/package.json +32 -0
- data/examples/serverless/spec/aws_lambda_spec.rb +196 -0
- data/examples/serverless/spec/spec_helper.rb +89 -0
- data/examples/serverless/vercel.json +31 -0
- data/examples/serverless/vercel_example.rb +404 -0
- data/examples/simple_demo_api.rb +40 -7
- data/examples/strict_validation_examples.rb +104 -0
- data/examples/user_api.rb +130 -132
- data/examples/validation_error_examples.rb +173 -0
- data/lib/rapitapir/ai/llm_instruction.rb +456 -0
- data/lib/rapitapir/ai/mcp.rb +134 -0
- data/lib/rapitapir/ai/rag.rb +287 -0
- data/lib/rapitapir/ai/rag_middleware.rb +147 -0
- data/lib/rapitapir/auth/oauth2.rb +44 -58
- data/lib/rapitapir/cli/command.rb +392 -6
- data/lib/rapitapir/cli/mcp_export.rb +18 -0
- data/lib/rapitapir/cli/scaffold_generator.rb +639 -0
- data/lib/rapitapir/cli/validator.rb +3 -7
- data/lib/rapitapir/core/endpoint.rb +59 -6
- data/lib/rapitapir/core/enhanced_endpoint.rb +3 -7
- data/lib/rapitapir/dsl/enhanced_structures.rb +1 -1
- data/lib/rapitapir/dsl/fluent_endpoint_builder.rb +53 -0
- data/lib/rapitapir/endpoint_registry.rb +47 -0
- data/lib/rapitapir/observability/health_check.rb +4 -4
- data/lib/rapitapir/observability/logging.rb +10 -10
- data/lib/rapitapir/openapi/schema_generator.rb +46 -2
- data/lib/rapitapir/schema.rb +2 -2
- data/lib/rapitapir/server/enhanced_rack_adapter.rb +11 -8
- data/lib/rapitapir/server/middleware.rb +2 -2
- data/lib/rapitapir/server/rack_adapter.rb +1 -3
- data/lib/rapitapir/server/rails/configuration.rb +77 -0
- data/lib/rapitapir/server/rails/controller_base.rb +185 -0
- data/lib/rapitapir/server/rails/documentation_helpers.rb +76 -0
- data/lib/rapitapir/server/rails/resource_builder.rb +181 -0
- data/lib/rapitapir/server/rails/routes.rb +114 -0
- data/lib/rapitapir/server/rails_adapter.rb +10 -3
- data/lib/rapitapir/server/rails_adapter_class.rb +1 -3
- data/lib/rapitapir/server/rails_controller.rb +1 -3
- data/lib/rapitapir/server/rails_integration.rb +67 -0
- data/lib/rapitapir/server/rails_response_handler.rb +16 -3
- data/lib/rapitapir/server/sinatra_adapter.rb +29 -5
- data/lib/rapitapir/server/sinatra_integration.rb +4 -4
- data/lib/rapitapir/sinatra/extension.rb +2 -2
- data/lib/rapitapir/sinatra/oauth2_helpers.rb +34 -40
- data/lib/rapitapir/types/array.rb +4 -0
- data/lib/rapitapir/types/auto_derivation.rb +4 -20
- data/lib/rapitapir/types/datetime.rb +1 -3
- data/lib/rapitapir/types/float.rb +2 -6
- data/lib/rapitapir/types/hash.rb +40 -2
- data/lib/rapitapir/types/integer.rb +4 -12
- data/lib/rapitapir/types/object.rb +6 -2
- data/lib/rapitapir/types.rb +6 -2
- data/lib/rapitapir/version.rb +1 -1
- data/lib/rapitapir.rb +5 -3
- data/rapitapir.gemspec +3 -2
- metadata +142 -8
data/docs/using-mcp.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Using RapiTapir APIs as LLM Tools (MCP)
|
|
2
|
+
|
|
3
|
+
RapiTapir supports the Model Context Protocol (MCP) to make your API endpoints discoverable and consumable by LLMs and AI agents.
|
|
4
|
+
|
|
5
|
+
### How to Mark Endpoints for MCP Export
|
|
6
|
+
|
|
7
|
+
Use the `.mcp_export` method in your endpoint DSL chain:
|
|
8
|
+
|
|
9
|
+
```ruby
|
|
10
|
+
endpoint(
|
|
11
|
+
GET('/hello')
|
|
12
|
+
.query(:name, T.string, description: 'Name to greet')
|
|
13
|
+
.ok(T.hash({ "message" => T.string }))
|
|
14
|
+
.enable_mcp # Mark for MCP export
|
|
15
|
+
.build
|
|
16
|
+
) do |inputs|
|
|
17
|
+
{ message: "Hello, #{inputs[:name]}!" }
|
|
18
|
+
end
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### CLI Usage
|
|
22
|
+
|
|
23
|
+
Generate MCP context using the command line:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# Generate MCP context for all marked endpoints
|
|
27
|
+
rapitapir generate mcp --endpoints api.rb --output mcp-context.json
|
|
28
|
+
|
|
29
|
+
# Alternative export command
|
|
30
|
+
rapitapir export mcp --endpoints api.rb --output mcp-context.json
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### Ruby API Usage
|
|
34
|
+
|
|
35
|
+
Use the MCP exporter directly in Ruby code:
|
|
36
|
+
|
|
37
|
+
```ruby
|
|
38
|
+
require 'rapitapir/ai/mcp'
|
|
39
|
+
|
|
40
|
+
# Load your endpoints
|
|
41
|
+
endpoints = [your_endpoint_list]
|
|
42
|
+
|
|
43
|
+
# Create exporter and generate context
|
|
44
|
+
exporter = RapiTapir::AI::MCP::Exporter.new(endpoints)
|
|
45
|
+
mcp_context = exporter.as_mcp_context
|
|
46
|
+
|
|
47
|
+
# Save to file
|
|
48
|
+
File.write('mcp-context.json', JSON.pretty_generate(mcp_context))
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Example Output
|
|
52
|
+
|
|
53
|
+
The generated MCP context includes:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"name": "RapiTapir API Context",
|
|
58
|
+
"version": "1.0.0",
|
|
59
|
+
"endpoints": [
|
|
60
|
+
{
|
|
61
|
+
"name": "get__users__id_",
|
|
62
|
+
"method": "GET",
|
|
63
|
+
"path": "/users/{id}",
|
|
64
|
+
"summary": "Retrieve a user by ID",
|
|
65
|
+
"description": "Fetches a single user record by their unique identifier",
|
|
66
|
+
"input_schema": {
|
|
67
|
+
"id": {
|
|
68
|
+
"type": "integer",
|
|
69
|
+
"kind": "path",
|
|
70
|
+
"required": true
|
|
71
|
+
}
|
|
72
|
+
},
|
|
73
|
+
"output_schema": {
|
|
74
|
+
"json": {
|
|
75
|
+
"type": {
|
|
76
|
+
"id": "integer",
|
|
77
|
+
"name": "string",
|
|
78
|
+
"email": "string"
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
},
|
|
82
|
+
"examples": []
|
|
83
|
+
}
|
|
84
|
+
]
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Use Cases
|
|
89
|
+
- LLM/agent tool discovery
|
|
90
|
+
- Automated API documentation for AI
|
|
91
|
+
- Integration with agent frameworks (LangChain, OpenAI, etc.)
|
|
92
|
+
|
|
93
|
+
See the AI integration plan for more details.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'bundler/setup'
|
|
4
|
+
|
|
5
|
+
# Add the project root to the load path for development
|
|
6
|
+
project_root = File.expand_path('../../', __dir__)
|
|
7
|
+
$LOAD_PATH.unshift(File.join(project_root, 'lib')) unless $LOAD_PATH.include?(File.join(project_root, 'lib'))
|
|
8
|
+
|
|
9
|
+
require 'rapitapir'
|
|
10
|
+
require 'rapitapir/ai/rag'
|
|
11
|
+
require 'json'
|
|
12
|
+
|
|
13
|
+
# Example: Knowledge Base API with RAG Support
|
|
14
|
+
module KnowledgeBaseAPI
|
|
15
|
+
extend RapiTapir::DSL
|
|
16
|
+
|
|
17
|
+
# Type alias for convenience
|
|
18
|
+
T = RapiTapir::Types
|
|
19
|
+
|
|
20
|
+
# Define schemas
|
|
21
|
+
ASK_SCHEMA = T.hash({
|
|
22
|
+
'question' => T.string,
|
|
23
|
+
'user_id' => T.string
|
|
24
|
+
}).freeze
|
|
25
|
+
|
|
26
|
+
ANSWER_SCHEMA = T.hash({
|
|
27
|
+
'answer' => T.string,
|
|
28
|
+
'sources' => T.array(T.string),
|
|
29
|
+
'timestamp' => T.string
|
|
30
|
+
}).freeze
|
|
31
|
+
|
|
32
|
+
CHAT_INPUT_SCHEMA = T.hash({
|
|
33
|
+
'message' => T.string
|
|
34
|
+
}).freeze
|
|
35
|
+
|
|
36
|
+
CHAT_OUTPUT_SCHEMA = T.hash({
|
|
37
|
+
'response' => T.string
|
|
38
|
+
}).freeze
|
|
39
|
+
|
|
40
|
+
# Ask a question using RAG
|
|
41
|
+
ASK_QUESTION = RapiTapir.post('/ask')
|
|
42
|
+
.json_body(ASK_SCHEMA)
|
|
43
|
+
.ok(ANSWER_SCHEMA)
|
|
44
|
+
.rag_inference(
|
|
45
|
+
llm: :openai,
|
|
46
|
+
retrieval: :memory,
|
|
47
|
+
context_fields: [:user_id],
|
|
48
|
+
config: {
|
|
49
|
+
llm: { api_key: 'mock' },
|
|
50
|
+
retrieval: {
|
|
51
|
+
documents: [
|
|
52
|
+
{ content: 'RapiTapir is a Ruby API framework that provides type-safe endpoints.' },
|
|
53
|
+
{ content: 'RAG combines document retrieval with LLM text generation.' },
|
|
54
|
+
{ content: 'This API demonstrates AI-powered question answering.' }
|
|
55
|
+
]
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
)
|
|
59
|
+
.summary('Ask a question about the knowledge base')
|
|
60
|
+
.mcp_export
|
|
61
|
+
|
|
62
|
+
# Simple chat
|
|
63
|
+
CHAT = RapiTapir.post('/chat')
|
|
64
|
+
.json_body(CHAT_INPUT_SCHEMA)
|
|
65
|
+
.ok(CHAT_OUTPUT_SCHEMA)
|
|
66
|
+
.rag_inference(
|
|
67
|
+
llm: :openai,
|
|
68
|
+
retrieval: :memory,
|
|
69
|
+
config: {
|
|
70
|
+
llm: { api_key: 'mock' },
|
|
71
|
+
retrieval: {
|
|
72
|
+
documents: [
|
|
73
|
+
{ content: 'RapiTapir supports MCP for AI agent integration.' }
|
|
74
|
+
]
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
)
|
|
78
|
+
.summary('Chat with AI')
|
|
79
|
+
.mcp_export
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
# Endpoints for CLI
|
|
83
|
+
knowledge_base_api = [KnowledgeBaseAPI::ASK_QUESTION, KnowledgeBaseAPI::CHAT]
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative '../../lib/rapitapir'
|
|
4
|
+
require_relative '../../lib/rapitapir/endpoint_registry'
|
|
5
|
+
|
|
6
|
+
# Example: User Management API with MCP Export
|
|
7
|
+
# This demonstrates how to mark endpoints for MCP export for AI/LLM consumption
|
|
8
|
+
|
|
9
|
+
class UserManagementAPI
|
|
10
|
+
include RapiTapir::DSL
|
|
11
|
+
|
|
12
|
+
# User schema for consistent typing
|
|
13
|
+
USER_SCHEMA = {
|
|
14
|
+
id: :integer,
|
|
15
|
+
name: :string,
|
|
16
|
+
email: :string,
|
|
17
|
+
created_at: :datetime
|
|
18
|
+
}.freeze
|
|
19
|
+
|
|
20
|
+
# Endpoint 1: Get user by ID - marked for MCP export
|
|
21
|
+
GET_USER = RapiTapir.get('/users/{id}')
|
|
22
|
+
.in(path_param(:id, :integer))
|
|
23
|
+
.out(json_body(USER_SCHEMA))
|
|
24
|
+
.summary('Retrieve a user by ID')
|
|
25
|
+
.description('Fetches a single user record by their unique identifier')
|
|
26
|
+
.mcp_export # Mark for MCP export
|
|
27
|
+
|
|
28
|
+
# Endpoint 2: Create new user - marked for MCP export
|
|
29
|
+
CREATE_USER = RapiTapir.post('/users')
|
|
30
|
+
.in(json_body({
|
|
31
|
+
name: :string,
|
|
32
|
+
email: :string
|
|
33
|
+
}))
|
|
34
|
+
.out(status_code(201))
|
|
35
|
+
.out(json_body(USER_SCHEMA))
|
|
36
|
+
.summary('Create a new user')
|
|
37
|
+
.description('Creates a new user account with name and email')
|
|
38
|
+
.mcp_export # Mark for MCP export
|
|
39
|
+
|
|
40
|
+
# Endpoint 3: Update user - NOT marked for MCP export
|
|
41
|
+
UPDATE_USER = RapiTapir.put('/users/{id}')
|
|
42
|
+
.in(path_param(:id, :integer))
|
|
43
|
+
.in(json_body({
|
|
44
|
+
name: :string,
|
|
45
|
+
email: :string
|
|
46
|
+
}))
|
|
47
|
+
.out(json_body(USER_SCHEMA))
|
|
48
|
+
.summary('Update an existing user')
|
|
49
|
+
.description('Updates user information')
|
|
50
|
+
# No .mcp_export - this endpoint won't be included in MCP context
|
|
51
|
+
|
|
52
|
+
# Endpoint 4: List users with pagination - marked for MCP export
|
|
53
|
+
LIST_USERS = RapiTapir.get('/users')
|
|
54
|
+
.in(query(:page, :integer, required: false))
|
|
55
|
+
.in(query(:limit, :integer, required: false))
|
|
56
|
+
.out(json_body({
|
|
57
|
+
users: [:array, USER_SCHEMA],
|
|
58
|
+
total: :integer,
|
|
59
|
+
page: :integer,
|
|
60
|
+
limit: :integer
|
|
61
|
+
}))
|
|
62
|
+
.summary('List all users')
|
|
63
|
+
.description('Retrieves a paginated list of all users')
|
|
64
|
+
.mcp_export # Mark for MCP export
|
|
65
|
+
|
|
66
|
+
# Store endpoints for export
|
|
67
|
+
ALL_ENDPOINTS = [GET_USER, CREATE_USER, UPDATE_USER, LIST_USERS].freeze
|
|
68
|
+
|
|
69
|
+
# Register endpoints in global registry
|
|
70
|
+
RapiTapir::EndpointRegistry.register_all(ALL_ENDPOINTS)
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
# Usage demonstration
|
|
74
|
+
if __FILE__ == $PROGRAM_NAME
|
|
75
|
+
puts "User Management API Example"
|
|
76
|
+
puts "==========================="
|
|
77
|
+
|
|
78
|
+
# Show which endpoints are marked for MCP export
|
|
79
|
+
mcp_endpoints = UserManagementAPI::ALL_ENDPOINTS.select(&:mcp_export?)
|
|
80
|
+
puts "\nEndpoints marked for MCP export:"
|
|
81
|
+
mcp_endpoints.each do |ep|
|
|
82
|
+
puts "- #{ep.method.upcase} #{ep.path} (#{ep.metadata[:summary]})"
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
# Generate MCP context
|
|
86
|
+
require_relative '../../lib/rapitapir/ai/mcp'
|
|
87
|
+
exporter = RapiTapir::AI::MCP::Exporter.new(UserManagementAPI::ALL_ENDPOINTS)
|
|
88
|
+
mcp_context = exporter.as_mcp_context
|
|
89
|
+
|
|
90
|
+
puts "\nGenerated MCP Context:"
|
|
91
|
+
puts JSON.pretty_generate(mcp_context)
|
|
92
|
+
end
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'bundler/setup'
|
|
4
|
+
|
|
5
|
+
# Add the project root to the load path for development
|
|
6
|
+
project_root = File.expand_path('../../', __dir__)
|
|
7
|
+
$LOAD_PATH.unshift(File.join(project_root, 'lib')) unless $LOAD_PATH.include?(File.join(project_root, 'lib'))
|
|
8
|
+
|
|
9
|
+
require 'rapitapir'
|
|
10
|
+
require 'rapitapir/ai/llm_instruction'
|
|
11
|
+
require 'json'
|
|
12
|
+
|
|
13
|
+
# Type alias for convenience (avoid warning if already defined)
|
|
14
|
+
T = RapiTapir::Types unless defined?(T)
|
|
15
|
+
|
|
16
|
+
module UserValidationAPI
|
|
17
|
+
# User creation validation schema
|
|
18
|
+
USER_INPUT_SCHEMA = T.hash({
|
|
19
|
+
'name' => T.string(min_length: 2, max_length: 50),
|
|
20
|
+
'email' => T.email,
|
|
21
|
+
'age' => T.integer(minimum: 18, maximum: 120),
|
|
22
|
+
'preferences' => T.optional(T.hash({
|
|
23
|
+
'newsletter' => T.boolean,
|
|
24
|
+
'notifications' => T.boolean
|
|
25
|
+
}))
|
|
26
|
+
}).freeze
|
|
27
|
+
|
|
28
|
+
USER_OUTPUT_SCHEMA = T.hash({
|
|
29
|
+
'id' => T.integer,
|
|
30
|
+
'name' => T.string,
|
|
31
|
+
'email' => T.string,
|
|
32
|
+
'status' => T.string,
|
|
33
|
+
'created_at' => T.datetime
|
|
34
|
+
}).freeze
|
|
35
|
+
|
|
36
|
+
VALIDATION_ERROR_SCHEMA = T.hash({
|
|
37
|
+
'error' => T.string,
|
|
38
|
+
'field_errors' => T.array(T.hash({
|
|
39
|
+
'field' => T.string,
|
|
40
|
+
'message' => T.string,
|
|
41
|
+
'code' => T.string
|
|
42
|
+
}))
|
|
43
|
+
}).freeze
|
|
44
|
+
|
|
45
|
+
# Data transformation schemas
|
|
46
|
+
LEGACY_USER_INPUT = T.hash({
|
|
47
|
+
'full_name' => T.string,
|
|
48
|
+
'email_address' => T.string,
|
|
49
|
+
'birth_year' => T.integer,
|
|
50
|
+
'settings' => T.optional(T.string) # JSON string in legacy format
|
|
51
|
+
}).freeze
|
|
52
|
+
|
|
53
|
+
# Analytics schema
|
|
54
|
+
USER_ANALYTICS_SCHEMA = T.hash({
|
|
55
|
+
'user_count' => T.integer,
|
|
56
|
+
'active_users' => T.integer,
|
|
57
|
+
'signup_rate' => T.float,
|
|
58
|
+
'demographics' => T.hash({
|
|
59
|
+
'avg_age' => T.float,
|
|
60
|
+
'age_distribution' => T.array(T.hash({
|
|
61
|
+
'range' => T.string,
|
|
62
|
+
'count' => T.integer
|
|
63
|
+
}))
|
|
64
|
+
})
|
|
65
|
+
}).freeze
|
|
66
|
+
|
|
67
|
+
# Validation endpoint with LLM instruction for input validation
|
|
68
|
+
CREATE_USER = RapiTapir.post('/users')
|
|
69
|
+
.json_body(USER_INPUT_SCHEMA)
|
|
70
|
+
.ok(USER_OUTPUT_SCHEMA)
|
|
71
|
+
.error_out(400, VALIDATION_ERROR_SCHEMA)
|
|
72
|
+
.llm_instruction(
|
|
73
|
+
purpose: :validation,
|
|
74
|
+
fields: [:body] # Focus on request body validation
|
|
75
|
+
)
|
|
76
|
+
.summary('Create a new user with validation')
|
|
77
|
+
.description('Creates a new user account with comprehensive input validation and business rule checking')
|
|
78
|
+
.mcp_export
|
|
79
|
+
|
|
80
|
+
# Transformation endpoint for legacy data migration
|
|
81
|
+
MIGRATE_LEGACY_USER = RapiTapir.post('/users/migrate')
|
|
82
|
+
.json_body(LEGACY_USER_INPUT)
|
|
83
|
+
.ok(USER_OUTPUT_SCHEMA)
|
|
84
|
+
.llm_instruction(
|
|
85
|
+
purpose: :transformation,
|
|
86
|
+
fields: :all
|
|
87
|
+
)
|
|
88
|
+
.summary('Migrate legacy user data to new format')
|
|
89
|
+
.description('Transforms legacy user data format to current schema with proper field mapping')
|
|
90
|
+
.mcp_export
|
|
91
|
+
|
|
92
|
+
# Analysis endpoint for user analytics
|
|
93
|
+
USER_ANALYTICS = RapiTapir.get('/users/analytics')
|
|
94
|
+
.query(:start_date, :date)
|
|
95
|
+
.query(:end_date, :date)
|
|
96
|
+
.query(:segment, T.optional(T.string))
|
|
97
|
+
.ok(USER_ANALYTICS_SCHEMA)
|
|
98
|
+
.llm_instruction(
|
|
99
|
+
purpose: :analysis,
|
|
100
|
+
fields: [:json] # Focus on analyzing the response data
|
|
101
|
+
)
|
|
102
|
+
.summary('Get user analytics and insights')
|
|
103
|
+
.description('Provides comprehensive user analytics including demographics and engagement metrics')
|
|
104
|
+
.mcp_export
|
|
105
|
+
|
|
106
|
+
# Documentation endpoint for API reference
|
|
107
|
+
USER_SEARCH = RapiTapir.get('/users/search')
|
|
108
|
+
.query(:q, T.string(min_length: 1))
|
|
109
|
+
.query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)))
|
|
110
|
+
.query(:offset, T.optional(T.integer(minimum: 0)))
|
|
111
|
+
.ok(T.hash({
|
|
112
|
+
'users' => T.array(USER_OUTPUT_SCHEMA),
|
|
113
|
+
'total_count' => T.integer,
|
|
114
|
+
'has_more' => T.boolean
|
|
115
|
+
}))
|
|
116
|
+
.llm_instruction(
|
|
117
|
+
purpose: :documentation,
|
|
118
|
+
fields: :all
|
|
119
|
+
)
|
|
120
|
+
.summary('Search for users')
|
|
121
|
+
.description('Full-text search across user profiles with pagination support')
|
|
122
|
+
.mcp_export
|
|
123
|
+
|
|
124
|
+
# Testing endpoint for comprehensive test generation
|
|
125
|
+
UPDATE_USER = RapiTapir.put('/users/:id')
|
|
126
|
+
.path_param(:id, :integer)
|
|
127
|
+
.json_body(T.hash({
|
|
128
|
+
'name' => T.optional(T.string(min_length: 2, max_length: 50)),
|
|
129
|
+
'email' => T.optional(T.email),
|
|
130
|
+
'preferences' => T.optional(T.hash({
|
|
131
|
+
'newsletter' => T.boolean,
|
|
132
|
+
'notifications' => T.boolean
|
|
133
|
+
}))
|
|
134
|
+
}))
|
|
135
|
+
.ok(USER_OUTPUT_SCHEMA)
|
|
136
|
+
.error_out(404, T.hash({'error' => T.string}))
|
|
137
|
+
.error_out(400, VALIDATION_ERROR_SCHEMA)
|
|
138
|
+
.llm_instruction(
|
|
139
|
+
purpose: :testing,
|
|
140
|
+
fields: :all
|
|
141
|
+
)
|
|
142
|
+
.summary('Update user information')
|
|
143
|
+
.description('Updates user profile with partial data and validation')
|
|
144
|
+
.mcp_export
|
|
145
|
+
|
|
146
|
+
# Completion endpoint for smart field suggestions
|
|
147
|
+
USER_PROFILE_COMPLETION = RapiTapir.post('/users/complete')
|
|
148
|
+
.json_body(T.hash({
|
|
149
|
+
'partial_profile' => T.hash({
|
|
150
|
+
'name' => T.optional(T.string),
|
|
151
|
+
'email' => T.optional(T.string),
|
|
152
|
+
'location' => T.optional(T.string),
|
|
153
|
+
'interests' => T.optional(T.array(T.string))
|
|
154
|
+
})
|
|
155
|
+
}))
|
|
156
|
+
.ok(T.hash({
|
|
157
|
+
'suggestions' => T.hash({
|
|
158
|
+
'name' => T.optional(T.array(T.string)),
|
|
159
|
+
'email' => T.optional(T.string),
|
|
160
|
+
'location' => T.optional(T.array(T.string)),
|
|
161
|
+
'interests' => T.optional(T.array(T.string))
|
|
162
|
+
}),
|
|
163
|
+
'confidence_scores' => T.hash({
|
|
164
|
+
'name' => T.optional(T.float),
|
|
165
|
+
'email' => T.optional(T.float),
|
|
166
|
+
'location' => T.optional(T.float),
|
|
167
|
+
'interests' => T.optional(T.float)
|
|
168
|
+
})
|
|
169
|
+
}))
|
|
170
|
+
.llm_instruction(
|
|
171
|
+
purpose: :completion,
|
|
172
|
+
fields: [:body]
|
|
173
|
+
)
|
|
174
|
+
.summary('Get smart profile completion suggestions')
|
|
175
|
+
.description('Provides intelligent suggestions for completing user profile data')
|
|
176
|
+
.mcp_export
|
|
177
|
+
end
|
|
178
|
+
|
|
179
|
+
# Endpoints for CLI
|
|
180
|
+
user_validation_api = [
|
|
181
|
+
UserValidationAPI::CREATE_USER,
|
|
182
|
+
UserValidationAPI::MIGRATE_LEGACY_USER,
|
|
183
|
+
UserValidationAPI::USER_ANALYTICS,
|
|
184
|
+
UserValidationAPI::USER_SEARCH,
|
|
185
|
+
UserValidationAPI::UPDATE_USER,
|
|
186
|
+
UserValidationAPI::USER_PROFILE_COMPLETION
|
|
187
|
+
]
|
|
@@ -1,163 +1,94 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
-
# This file demonstrates the
|
|
4
|
-
# well with Ruby's dynamic nature and lack of built-in type
|
|
3
|
+
# This file demonstrates the auto-derivation capabilities of RapiTapir's type
|
|
4
|
+
# system, working well with Ruby's dynamic nature and lack of built-in type
|
|
5
|
+
# declarations.
|
|
5
6
|
|
|
6
7
|
require_relative '../lib/rapitapir/types'
|
|
7
8
|
|
|
8
|
-
puts
|
|
9
|
+
puts '=== RapiTapir Auto-Derivation Examples ==='
|
|
9
10
|
puts
|
|
10
11
|
|
|
11
12
|
# 1. From Hash (most reliable for Ruby)
|
|
12
|
-
puts
|
|
13
|
+
puts '1. From Hash (recommended for Ruby)'
|
|
13
14
|
hash_data = {
|
|
14
|
-
name:
|
|
15
|
+
name: 'John Doe',
|
|
15
16
|
age: 30,
|
|
16
|
-
email:
|
|
17
|
+
email: 'john@example.com',
|
|
17
18
|
active: true,
|
|
18
19
|
score: 95.5,
|
|
19
|
-
tags: [
|
|
20
|
-
metadata: { role:
|
|
20
|
+
tags: ['developer', 'ruby'],
|
|
21
|
+
metadata: { role: 'senior', team: 'backend' }
|
|
21
22
|
}
|
|
22
23
|
|
|
23
24
|
schema = RapiTapir::Types.from_hash(hash_data)
|
|
24
|
-
puts
|
|
25
|
+
puts 'Schema from hash:'
|
|
25
26
|
puts schema.field_types.inspect
|
|
26
27
|
puts
|
|
27
28
|
|
|
28
29
|
# 2. From Hash with filtering
|
|
30
|
+
puts '2. From Hash with filtering'
|
|
29
31
|
filtered_schema = RapiTapir::Types.from_hash(hash_data, except: [:metadata])
|
|
30
32
|
puts "Schema with 'except' filtering:"
|
|
31
33
|
puts filtered_schema.field_types.inspect
|
|
32
34
|
puts
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
puts "
|
|
36
|
-
|
|
37
|
-
attr_accessor :name, :age, :email, :active
|
|
38
|
-
end
|
|
39
|
-
|
|
40
|
-
# Method 1: Via types parameter
|
|
41
|
-
person_schema = RapiTapir::Types.from_object(Person, types: {
|
|
42
|
-
name: :string,
|
|
43
|
-
age: :integer,
|
|
44
|
-
email: :string,
|
|
45
|
-
active: :boolean
|
|
46
|
-
})
|
|
47
|
-
puts "Person schema with explicit types:"
|
|
48
|
-
puts person_schema.field_types.inspect
|
|
49
|
-
puts
|
|
50
|
-
|
|
51
|
-
# 4. From instance (less reliable but convenient)
|
|
52
|
-
puts "3. From Instance (use with well-populated data)"
|
|
53
|
-
person = Person.new
|
|
54
|
-
person.name = "Jane Smith"
|
|
55
|
-
person.age = 28
|
|
56
|
-
person.email = "jane@example.com"
|
|
57
|
-
person.active = true
|
|
58
|
-
|
|
59
|
-
instance_schema = RapiTapir::Types.from_object(person)
|
|
60
|
-
puts "Schema from instance:"
|
|
61
|
-
puts instance_schema.field_types.inspect
|
|
36
|
+
filtered_only = RapiTapir::Types.from_hash(hash_data, only: [:name, :email])
|
|
37
|
+
puts "Schema with 'only' filtering:"
|
|
38
|
+
puts filtered_only.field_types.inspect
|
|
62
39
|
puts
|
|
63
40
|
|
|
64
|
-
#
|
|
65
|
-
puts
|
|
66
|
-
Point = Struct.new(:x, :y, :z) do
|
|
67
|
-
def distance_from_origin
|
|
68
|
-
Math.sqrt(x**2 + y**2 + z**2)
|
|
69
|
-
end
|
|
70
|
-
end
|
|
71
|
-
|
|
72
|
-
sample_point = Point.new(1.0, 2.0, 3.0)
|
|
73
|
-
point_schema = RapiTapir::Types.from_object(Point, sample: sample_point)
|
|
74
|
-
puts "Point schema from Struct:"
|
|
75
|
-
puts point_schema.field_types.inspect
|
|
76
|
-
puts
|
|
77
|
-
|
|
78
|
-
# 6. DSL approach (most Ruby-like)
|
|
79
|
-
puts "5. DSL Approach (Ruby-idiomatic)"
|
|
80
|
-
class User
|
|
81
|
-
include RapiTapir::Types::AutoDerivation::Annotated
|
|
82
|
-
|
|
83
|
-
attr_accessor :username, :email, :age, :admin
|
|
84
|
-
|
|
85
|
-
rapitapir_schema do
|
|
86
|
-
field :username, :string
|
|
87
|
-
field :email, :string
|
|
88
|
-
field :age, :integer
|
|
89
|
-
field :admin, :boolean
|
|
90
|
-
end
|
|
91
|
-
end
|
|
92
|
-
|
|
93
|
-
user_schema = RapiTapir::Types.from_object(User)
|
|
94
|
-
puts "User schema with DSL:"
|
|
95
|
-
puts user_schema.field_types.inspect
|
|
96
|
-
puts
|
|
97
|
-
|
|
98
|
-
# 7. OpenStruct (convenient for prototyping)
|
|
99
|
-
puts "6. From OpenStruct"
|
|
41
|
+
# 3. OpenStruct (convenient for prototyping)
|
|
42
|
+
puts '3. From OpenStruct'
|
|
100
43
|
require 'ostruct'
|
|
101
44
|
|
|
102
45
|
config = OpenStruct.new(
|
|
103
|
-
host:
|
|
46
|
+
host: 'localhost',
|
|
104
47
|
port: 3000,
|
|
105
48
|
ssl: false,
|
|
106
49
|
timeout: 30.5
|
|
107
50
|
)
|
|
108
51
|
|
|
109
52
|
config_schema = RapiTapir::Types.from_open_struct(config)
|
|
110
|
-
puts
|
|
53
|
+
puts 'Config schema from OpenStruct:'
|
|
111
54
|
puts config_schema.field_types.inspect
|
|
112
55
|
puts
|
|
113
56
|
|
|
114
|
-
#
|
|
115
|
-
puts
|
|
57
|
+
# 4. JSON Schema (for external APIs)
|
|
58
|
+
puts '4. From JSON Schema'
|
|
116
59
|
json_schema = {
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
60
|
+
'type' => 'object',
|
|
61
|
+
'properties' => {
|
|
62
|
+
'id' => { 'type' => 'integer' },
|
|
63
|
+
'name' => { 'type' => 'string', 'maxLength' => 100 },
|
|
64
|
+
'email' => { 'type' => 'string', 'format' => 'email' },
|
|
65
|
+
'created_at' => { 'type' => 'string', 'format' => 'date-time' },
|
|
66
|
+
'tags' => {
|
|
67
|
+
'type' => 'array',
|
|
68
|
+
'items' => { 'type' => 'string' }
|
|
126
69
|
}
|
|
127
70
|
},
|
|
128
|
-
|
|
71
|
+
'required' => ['id', 'name', 'email']
|
|
129
72
|
}
|
|
130
73
|
|
|
131
74
|
json_derived_schema = RapiTapir::Types.from_json_schema(json_schema)
|
|
132
|
-
puts
|
|
75
|
+
puts 'Schema from JSON Schema:'
|
|
133
76
|
puts json_derived_schema.field_types.inspect
|
|
134
77
|
puts
|
|
135
78
|
|
|
136
|
-
#
|
|
137
|
-
puts
|
|
138
|
-
|
|
139
|
-
class EmptyClass
|
|
140
|
-
end
|
|
141
|
-
|
|
79
|
+
# 5. Protobuf (when available)
|
|
80
|
+
puts '5. From Protobuf (if a protobuf descriptor is available)'
|
|
142
81
|
begin
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
rescue
|
|
146
|
-
puts
|
|
82
|
+
require 'google/protobuf' # rubocop:disable Lint/RequireRelativeSelfPath
|
|
83
|
+
puts ' google-protobuf is available — from_protobuf(Descriptor) is supported'
|
|
84
|
+
rescue LoadError
|
|
85
|
+
puts ' google-protobuf not installed — from_protobuf is available once it is'
|
|
147
86
|
end
|
|
148
|
-
|
|
149
|
-
begin
|
|
150
|
-
# This should also fail
|
|
151
|
-
RapiTapir::Types.from_object(Point) # Struct without sample
|
|
152
|
-
rescue ArgumentError => e
|
|
153
|
-
puts "Expected error for Struct without sample: #{e.message}"
|
|
154
|
-
end
|
|
155
|
-
|
|
156
87
|
puts
|
|
157
|
-
|
|
158
|
-
puts
|
|
159
|
-
puts
|
|
160
|
-
puts
|
|
161
|
-
puts
|
|
162
|
-
puts
|
|
163
|
-
puts
|
|
88
|
+
|
|
89
|
+
puts '=== Recommendations ==='
|
|
90
|
+
puts '1. Use from_hash() for parsed JSON or config data'
|
|
91
|
+
puts '2. Use from_open_struct() for prototyping'
|
|
92
|
+
puts '3. Use from_json_schema() for external API integration'
|
|
93
|
+
puts '4. Use from_protobuf() when wrapping protobuf messages'
|
|
94
|
+
puts '5. Avoid deriving from empty hashes or nil values'
|