vector_mcp 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64b4dac9a0a1e9c782d3b5d693e7582803621ac81555f992031f9edbdd3f5b6b
-  data.tar.gz: 571e540ac540859b1fefaadc5e2b3cda39a1415c3496af38cee46cb839316c85
+  metadata.gz: de0f694bd85fb9d217c352fc907f7d77c27ee3837eea3512c8ca1791c53313c2
+  data.tar.gz: 86f0a7ab8c95e744ef8d80cb77faddaa195cef6636ea9fe175631b01bc0b0982
 SHA512:
-  metadata.gz: cc7c13562e31070ce7aef3d0d20801e4a7368a44b22ea58d01ec872f7f9191e7b70d96e72c3cdcd42b9ecc40dc9b7ea30e63ce12b5b54987734a933402269b71
-  data.tar.gz: 6f989302cbd97c00aa5f2dfe28950cffb5c2c53c204c3ab10eb886a9dc680e0db6a704fef54229488910c837ebe3857c7e493ae5aa8729d8d6677fe048c223e1
+  metadata.gz: c0f1f384fd9d654cc3385a87937c656dee9beaf38e0aeed6f0e92542366c17051615b774b58d1ecc2eb89dd23e6a6737e85e1dcdfb6d4c239a182d0d3c98f31f
+  data.tar.gz: 8d0047290e1033266498f197b94b3d51eb88b700c46e44f15229de985a74eb57889f8381887beb92b0007883244de8f0c53b652a9a8939963f30d3c81fecb406

data/CHANGELOG.md

@@ -1,3 +1,83 @@
+## [Unreleased]
+
+## [0.4.0] – 2026-04-10
+
+### Added
+
+* **Declarative Tool DSL**: Added `VectorMCP::Tool` for class-based tool definitions.
+  - Define tools with `tool_name`, `description`, and `param`
+  - Register one or more tool classes with `server.register(MyTool, OtherTool)`
+  - Added `:date` and `:datetime` param types with automatic coercion to `Date` and `Time`
+
+* **Rack and Rails Integration**: Added first-class mounting support for Rack-based applications.
+  - `Server#rack_app` returns a Rack-compatible MCP endpoint without starting Puma
+  - Added `VectorMCP::Rails::Tool` for ActiveRecord-backed tools
+  - Added `docs/rails-setup-guide.md` with a full Rails integration guide
+
+* **Expanded Middleware Lifecycle Hooks**: Middleware can now observe and shape more of the request lifecycle.
+  - Added `before_auth`, `after_auth`, and `on_auth_error` hooks
+  - Added transport-level `before_request`, `after_response`, and `on_transport_error` hooks
+  - Middleware can now mutate params before handlers execute
+
+### Changed
+
+* **MCP Protocol Version**: VectorMCP now advertises MCP protocol `2025-11-25` by default.
+  - `MCP-Protocol-Version` headers for `2025-11-25`, `2025-03-26`, and `2024-11-05` are accepted for compatibility
+
+* **Streamable HTTP Compliance**: HttpStream was updated to align with the MCP 2025-11-25 transport requirements.
+  - POST bodies must contain a single JSON-RPC request, notification, or response
+  - POST `Accept` validation now enforces `application/json` plus `text/event-stream` when the header is present
+  - Notifications now return `202 Accepted`
+  - SSE streams now send priming events, retry hints, and comment-based heartbeats
+  - Event replay and outbound routing are now scoped to the originating stream
+
+* **Ruby Requirement**: Minimum supported Ruby version is now `3.2`.
+
+### Removed
+
+* **Stdio Transport**: Removed stdio transport support entirely.
+  - Deleted `lib/vector_mcp/transport/stdio.rb` and `lib/vector_mcp/transport/stdio_session_manager.rb`
+  - `Server#run` now defaults to `transport: :http_stream`
+
+* **Standalone SSE Transport**: Removed the legacy SSE transport implementation.
+  - Deleted `lib/vector_mcp/transport/sse.rb`, `lib/vector_mcp/transport/sse_session_manager.rb`, and `lib/vector_mcp/transport/sse/`
+  - HttpStream is now the only built-in transport
+
+* **Broadcast APIs**: Removed `broadcast_message` and `broadcast_notification` to comply with the no-broadcast delivery rules in the MCP streamable HTTP specification.
+
+### Security
+
+* **Safer Origin Defaults**: Default allowed origins are now restricted to localhost and loopback addresses.
+  - Explicit wildcard origin configuration still works, but now emits a security warning
+
+* **Stronger Path Validation**: `ImageUtil` now canonicalizes file paths and blocks traversal attempts even when no `base_directory` is provided.
+
+### Fixed
+
+* **Stream Routing and Replay**: Multiple active SSE streams in the same session now replay and deliver messages to the correct logical stream.
+* **Authorization Context Propagation**: Resolved security context is now stored on the session so middleware and handlers can inspect authenticated state consistently.
+
+## [0.3.4] – 2026-03-17
+
+### Added
+
+* **Batch JSON-RPC Support**: Added batch request dispatch on POST endpoint for processing multiple JSON-RPC requests in a single HTTP call
+* **SSE Response Mode for POST**: POST requests can now receive responses via Server-Sent Events streaming
+* **Accept Header Validation**: Added proper Accept header validation on POST and GET endpoints per MCP specification
+
+### Security
+
+* **Constant-Time API Key Comparison** (SECURITY-001): Replaced direct string comparison with `Rack::Utils.secure_compare` to prevent timing attacks
+* **Disable Query Parameter Token Extraction** (SECURITY-002): Token extraction from query parameters now disabled by default to prevent token leakage via URL logging and browser history
+* **Path Traversal Protection for ImageUtil** (SECURITY-004): Added path traversal validation to `ImageUtil` file operations to prevent unauthorized file access
+* **Sensitive Data Filtering in Debug Logs** (SECURITY-005): Debug log output now filters sensitive fields (tokens, keys, credentials) to prevent accidental credential exposure
+* **Cross-Session Event Leakage Prevention**: Fixed EventStore to prevent events from one session being accessible to another session
+* **Session ID Validation on POST**: Fixed session fixation vulnerability where unknown session IDs were silently accepted; server now returns 404 for invalid sessions
+
+### Fixed
+
+* **Code Quality**: RuboCop style fixes and cleanup of unnecessary files
+
 ## [0.3.3] – 2025-07-29
 
 ### Fixed

data/README.md

@@ -6,441 +6,231 @@
 [![Maintainability](https://qlty.sh/badges/fdb143b3-148a-4a86-8e3b-4ccebe993528/maintainability.svg)](https://qlty.sh/gh/sergiobayona/projects/vector_mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-VectorMCP is a Ruby gem implementing the Model Context Protocol (MCP) server-side specification. It provides a framework for creating MCP servers that expose tools, resources, prompts, and roots to LLM clients.
+VectorMCP is a Ruby implementation of the Model Context Protocol (MCP) server-side specification. It gives you a framework for exposing tools, resources, prompts, roots, sampling, middleware, and security over the MCP streamable HTTP transport.
 
-## Why VectorMCP?
+## Highlights
 
-- **🛡️ Security-First**: Built-in input validation and schema checking prevent injection attacks
-- **⚡ Production-Ready**: Robust error handling, comprehensive test suite, and proven reliability  
-- **🔌 Multiple Transports**: stdio for CLI tools, SSE for web applications
-- **📦 Zero Configuration**: Works out of the box with sensible defaults
-- **🔄 Fully Compatible**: Implements the complete MCP specification
+- Streamable HTTP is the built-in transport, with session management, resumability, and MCP 2025-11-25 compliance
+- Class-based tools via `VectorMCP::Tool`, plus the original block-based `register_tool` API
+- Rack and Rails mounting through `server.rack_app`
+- Opt-in authentication and authorization, structured logging, and middleware hooks
+- Image-aware tools/resources/prompts, roots, and server-initiated sampling
 
-## Quick Start
+## Requirements
+
+- Ruby 3.2+
+
+## Installation
 
 ```bash
 gem install vector_mcp
 ```
 
 ```ruby
-require 'vector_mcp'
-
-# Create a server
-server = VectorMCP.new(name: 'MyApp', version: '1.0.0')
-
-# Add a tool
-server.register_tool(
-  name: 'greet',
-  description: 'Says hello to someone',
-  input_schema: {
-    type: 'object',
-    properties: { name: { type: 'string' } },
-    required: ['name']
-  }
-) { |args| "Hello, #{args['name']}!" }
-
-# Start the server
-server.run  # Uses stdio transport by default
+gem "vector_mcp"
 ```
 
-**That's it!** Your MCP server is ready to connect with Claude Desktop, custom clients, or any MCP-compatible application.
-
-## Transport Options
-
-### Command Line Tools (stdio)
-
-Perfect for desktop applications and process-based integrations:
+## Quick Start
 
 ```ruby
-server.run  # Default: stdio transport
-```
+require "vector_mcp"
 
-### Web Applications (HTTP + SSE)
+class Greet < VectorMCP::Tool
+  description "Say hello to someone"
+  param :name, type: :string, desc: "Name to greet", required: true
 
-Ideal for web apps and browser-based clients:
+  def call(args, _session)
+    "Hello, #{args["name"]}!"
+  end
+end
 
-```ruby
-server.run(transport: :sse, port: 8080)
+server = VectorMCP::Server.new(name: "MyApp", version: "1.0.0")
+server.register(Greet)
+server.run(port: 8080)
 ```
 
-Connect via Server-Sent Events at `http://localhost:8080/sse`
-
-## Core Features
-
-### Tools (Functions)
-
-Expose functions that LLMs can call:
+The class-based DSL is optional. The existing block-based API still works:
 
 ```ruby
 server.register_tool(
-  name: 'calculate',
-  description: 'Performs basic math',
+  name: "echo",
+  description: "Echo back the supplied text",
   input_schema: {
-    type: 'object',
-    properties: {
-      operation: { type: 'string', enum: ['add', 'subtract', 'multiply'] },
-      a: { type: 'number' },
-      b: { type: 'number' }
-    },
-    required: ['operation', 'a', 'b']
+    type: "object",
+    properties: { text: { type: "string" } },
+    required: ["text"]
   }
-) do |args|
-  case args['operation']
-  when 'add' then args['a'] + args['b']
-  when 'subtract' then args['a'] - args['b']
-  when 'multiply' then args['a'] * args['b']
-  end
-end
+) { |args| args["text"] }
 ```
 
-### Resources (Data Sources)
+## Rack and Rails
 
-Provide data that LLMs can read:
+VectorMCP can run as a standalone HTTP server or be mounted inside an existing Rack app:
 
 ```ruby
-server.register_resource(
-  uri: 'file://config.json',
-  name: 'App Configuration',
-  description: 'Current application settings'
-) { File.read('config.json') }
-```
-
-### Prompts (Templates)
+require "vector_mcp"
 
-Create reusable prompt templates:
+server = VectorMCP::Server.new(name: "MyApp", version: "1.0.0")
+server.register(Greet)
 
-```ruby
-server.register_prompt(
-  name: 'code_review',
-  description: 'Reviews code for best practices',
-  arguments: [
-    { name: 'language', description: 'Programming language', required: true },
-    { name: 'code', description: 'Code to review', required: true }
-  ]
-) do |args|
-  {
-    messages: [{
-      role: 'user',
-      content: {
-        type: 'text',
-        text: "Review this #{args['language']} code:\n\n#{args['code']}"
-      }
-    }]
-  }
-end
+MCP_APP = server.rack_app
 ```
 
-## Security Features
-
-VectorMCP provides comprehensive, **opt-in security** for production applications:
-
-### Built-in Input Validation
-
-All inputs are automatically validated against your schemas:
+In Rails, mount it in `config/routes.rb`:
 
 ```ruby
-# This tool is protected against invalid inputs
-server.register_tool(
-  name: 'process_user',
-  input_schema: {
-    type: 'object',
-    properties: {
-      email: { type: 'string', format: 'email' },
-      age: { type: 'integer', minimum: 0, maximum: 150 }
-    },
-    required: ['email']
-  }
-) { |args| "Processing #{args['email']}" }
-
-# Invalid inputs are automatically rejected:
-# ❌ { email: "not-an-email" }     -> Validation error
-# ❌ { age: -5 }                   -> Missing required field
-# ✅ { email: "user@example.com" } -> Passes validation
+mount MCP_APP => "/mcp"
 ```
 
-### Authentication & Authorization
-
-Secure your MCP server with flexible authentication strategies:
+For ActiveRecord-backed tools, opt into `VectorMCP::Rails::Tool`:
 
 ```ruby
-# API Key Authentication
-server.enable_authentication!(
-  strategy: :api_key,
-  keys: ["your-secret-key", "another-key"]
-)
-
-# JWT Token Authentication  
-server.enable_authentication!(
-  strategy: :jwt,
-  secret: ENV["JWT_SECRET"]
-)
+require "vector_mcp/rails/tool"
 
-# Custom Authentication Logic
-server.enable_authentication!(strategy: :custom) do |request|
-  api_key = request[:headers]["X-API-Key"]
-  User.find_by(api_key: api_key) ? { user_id: user.id } : false
-end
-```
+class FindUser < VectorMCP::Rails::Tool
+  description "Find a user by id"
+  param :id, type: :integer, required: true
 
-### Fine-Grained Authorization
-
-Control access to tools, resources, and prompts:
-
-```ruby
-server.enable_authorization! do
-  # Tool-level access control
-  authorize_tools do |user, action, tool|
-    case user[:role]
-    when "admin" then true
-    when "user" then !tool.name.start_with?("admin_")
-    else false
-    end
-  end
-  
-  # Resource-level permissions
-  authorize_resources do |user, action, resource|
-    user[:tenant_id] == resource.tenant_id
+  def call(args, _session)
+    user = find!(User, args[:id])
+    { id: user.id, email: user.email }
   end
 end
 ```
 
-### Transport Security
-
-Security works seamlessly across all transport layers:
-
-- **Stdio**: Header simulation for desktop applications
-- **SSE**: Full HTTP header and query parameter support
-- **Request Pipeline**: Automatic authentication and authorization checking
-
-**👉 [Complete Security Guide →](./security/README.md)**
+See [docs/rails-setup-guide.md](./docs/rails-setup-guide.md) for a full setup guide.
 
-Our comprehensive security documentation covers authentication strategies, authorization policies, session management, and real-world examples.
+## Tools, Resources, and Prompts
 
-## Real-World Examples
-
-### File System Server
+Expose callable tools:
 
 ```ruby
 server.register_tool(
-  name: 'read_file',
-  description: 'Reads a text file',
+  name: "calculate",
+  description: "Performs basic math",
   input_schema: {
-    type: 'object',
-    properties: { path: { type: 'string' } },
-    required: ['path']
-  }
-) { |args| File.read(args['path']) }
-```
-
-### Database Query Tool
-
-```ruby
-server.register_tool(
-  name: 'search_users',
-  description: 'Searches users by name',
-  input_schema: {
-    type: 'object',
-    properties: { 
-      query: { type: 'string', minLength: 1 },
-      limit: { type: 'integer', minimum: 1, maximum: 100 }
+    type: "object",
+    properties: {
+      operation: { type: "string", enum: ["add", "subtract", "multiply"] },
+      a: { type: "number" },
+      b: { type: "number" }
     },
-    required: ['query']
+    required: ["operation", "a", "b"]
   }
 ) do |args|
-  User.where('name ILIKE ?', "%#{args['query']}%")
-      .limit(args['limit'] || 10)
-      .to_json
+  case args["operation"]
+  when "add" then args["a"] + args["b"]
+  when "subtract" then args["a"] - args["b"]
+  when "multiply" then args["a"] * args["b"]
+  end
 end
 ```
 
-### API Integration
+Expose readable resources:
 
 ```ruby
-server.register_tool(
-  name: 'get_weather',
-  description: 'Gets current weather for a city',
-  input_schema: {
-    type: 'object',
-    properties: { city: { type: 'string' } },
-    required: ['city']
-  }
-) do |args|
-  response = HTTP.get("https://api.weather.com/current", params: { city: args['city'] })
-  response.parse
-end
+server.register_resource(
+  uri: "file://config.json",
+  name: "App Configuration",
+  description: "Current application settings"
+) { File.read("config.json") }
 ```
 
----
-
-## Advanced Usage
-
-<details>
-<summary><strong>Filesystem Roots & Security</strong></summary>
-
-Define secure filesystem boundaries:
+Define prompt templates:
 
 ```ruby
-# Register allowed directories
-server.register_root_from_path('./src', name: 'Source Code')
-server.register_root_from_path('./docs', name: 'Documentation')
-
-# Tools can safely operate within these bounds
-server.register_tool(
-  name: 'list_files',
-  input_schema: {
-    type: 'object', 
-    properties: { root_uri: { type: 'string' } },
-    required: ['root_uri']
-  }
+server.register_prompt(
+  name: "code_review",
+  description: "Reviews code for best practices",
+  arguments: [
+    { name: "language", description: "Programming language", required: true },
+    { name: "code", description: "Code to review", required: true }
+  ]
 ) do |args|
-  root = server.roots[args['root_uri']]
-  raise 'Invalid root' unless root
-  Dir.entries(root.path).reject { |f| f.start_with?('.') }
-end
-```
-
-</details>
-
-<details>
-<summary><strong>LLM Sampling (Server → Client)</strong></summary>
-
-Make requests to the connected LLM:
-
-```ruby
-server.register_tool(
-  name: 'generate_summary',
-  input_schema: {
-    type: 'object',
-    properties: { text: { type: 'string' } },
-    required: ['text']
+  {
+    messages: [{
+      role: "user",
+      content: {
+        type: "text",
+        text: "Review this #{args["language"]} code:\n\n#{args["code"]}"
+      }
+    }]
   }
-) do |args, session|
-  result = session.sample(
-    messages: [{ 
-      role: 'user', 
-      content: { type: 'text', text: "Summarize: #{args['text']}" }
-    }],
-    max_tokens: 100
-  )
-  result.text_content
 end
 ```
 
-</details>
+`VectorMCP::Tool` also supports `type: :date` and `type: :datetime`, which are validated as strings in JSON Schema and coerced to `Date` and `Time` before `#call` runs.
 
-<details>
-<summary><strong>Custom Error Handling</strong></summary>
+## Security and Middleware
 
-Use proper MCP error types:
+VectorMCP keeps security opt-in, but the primitives are built in:
 
 ```ruby
-server.register_tool(name: 'risky_operation') do |args|
-  if args['dangerous']
-    raise VectorMCP::InvalidParamsError.new('Dangerous operation not allowed')
-  end
-  
-  begin
-    perform_operation(args)
-  rescue SomeError => e
-    raise VectorMCP::InternalError.new('Operation failed')
+server.enable_authentication!(
+  strategy: :api_key,
+  keys: ["your-secret-key"]
+)
+
+server.enable_authorization! do
+  authorize_tools do |user, _action, tool|
+    user[:role] == "admin" || !tool.name.start_with?("admin_")
   end
 end
 ```
 
-</details>
-
-<details>
-<summary><strong>Session Information</strong></summary>
-
-Access client context:
+Custom authentication works too:
 
 ```ruby
-server.register_tool(name: 'client_info') do |args, session|
-  {
-    client: session.client_info&.dig('name'),
-    capabilities: session.client_capabilities,
-    initialized: session.initialized?
-  }
+server.enable_authentication!(strategy: :custom) do |request|
+  api_key = request[:headers]["X-API-Key"]
+  user = User.find_by(api_key: api_key)
+  user ? { user_id: user.id, role: user.role } : false
 end
 ```
 
-</details>
-
----
+Middleware can hook into tool, resource, prompt, sampling, auth, and transport events, including `before_auth`, `after_auth`, `on_auth_error`, `before_request`, `after_response`, and `on_transport_error`.
 
-## Integration Examples
+See [security/README.md](./security/README.md) for the full security guide.
 
-### Claude Desktop
+## Transport Notes
 
-Add to your Claude Desktop configuration:
+- VectorMCP ships with streamable HTTP as its built-in transport
+- `POST /mcp` accepts a single JSON-RPC request, notification, or response; batch arrays are rejected
+- `GET /mcp` opens an SSE stream for server-initiated messages
+- `DELETE /mcp` terminates the session
+- The server advertises MCP protocol `2025-11-25` and accepts `2025-03-26` and `2024-11-05` headers for compatibility
+- Default allowed origins are restricted to localhost and loopback addresses
 
-```json
-{
-  "mcpServers": {
-    "my-ruby-server": {
-      "command": "ruby",
-      "args": ["path/to/my_server.rb"]
-    }
-  }
-}
-```
+Initialize a session with curl:
 
-### Web Applications
-
-```javascript
-// Connect to SSE endpoint
-const eventSource = new EventSource('http://localhost:8080/sse');
-
-eventSource.addEventListener('endpoint', (event) => {
-  const { uri } = JSON.parse(event.data);
-  
-  // Send MCP requests
-  fetch(uri, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      jsonrpc: '2.0',
-      id: 1,
-      method: 'tools/call',
-      params: { name: 'greet', arguments: { name: 'World' } }
-    })
-  });
-});
+```bash
+curl -X POST http://localhost:8080/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
 ```
 
-## Why Choose VectorMCP?
-
-**🏆 Battle-Tested**: Used in production applications serving thousands of requests
-
-**⚡ Performance**: Optimized for low latency and high throughput
-
-**🛡️ Secure by Default**: Comprehensive input validation prevents common attacks  
+## More Features
 
-**📖 Well-Documented**: Extensive examples and clear API documentation
+- Roots via `register_root` and `register_root_from_path`
+- Image resources and image-aware tools/prompts
+- Structured logging with component loggers
+- Server-initiated sampling with streaming/tool-call support
+- Middleware-driven request shaping and observability
 
-**🔧 Extensible**: Easy to customize and extend for your specific needs
+## Documentation
 
-**🤝 Community**: Active development and responsive maintainer
-
-## Examples & Resources
-
-- **[Examples Directory](./examples/)** - Complete working examples
-- **[File System MCP](https://github.com/sergiobayona/file_system_mcp)** - Real-world implementation
-- **[MCP Specification](https://modelcontext.dev/)** - Official protocol documentation
-
-## Installation & Setup
-
-```bash
-gem install vector_mcp
-
-# Or in your Gemfile
-gem 'vector_mcp'
-```
+- [CHANGELOG.md](./CHANGELOG.md)
+- [examples/](./examples/)
+- [docs/rails-setup-guide.md](./docs/rails-setup-guide.md)
+- [docs/streamable-http-spec-compliance.md](./docs/streamable-http-spec-compliance.md)
+- [security/README.md](./security/README.md)
+- [MCP Specification](https://modelcontextprotocol.io/)
 
 ## Contributing
 
-Bug reports and pull requests welcome on [GitHub](https://github.com/sergiobayona/vector_mcp).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/sergiobayona/vector_mcp).
 
 ## License
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).