vector_mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f97bb6519db2c4d1b5e7cbac2a47954714aaa8e65f3cf797054c43cfc782255c
+  data.tar.gz: 5188e19bed4e4114729d6ea482361a0ad5adffddf0c400dd6081e7370037eb73
+SHA512:
+  metadata.gz: 04af736a5887198f5d4d24e16d37689dce473872fc3a4c6448f0bdc8aaf49ff06a1f076827725978ad4f71f8a89906a9ab1dc336a91d2d176302a91a8726183d
+  data.tar.gz: 1386b745783db291622c0aec7b8108c966089e40c114b37386b2fc9e041df100ba19b927353edcac7ece880f0682cc8c37457e51e35d842936fef3dc4aa5447c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Sergio Bayona
+
+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,210 @@
+# VectorMCP
+
+<!-- Badges (Add URLs later) -->
+[![Gem Version](https://badge.fury.io/rb/vector_mcp.svg)](https://badge.fury.io/rb/vector_mcp)
+[![Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://sergiobayona.github.io/vector_mcp/)
+[![Build Status](https://github.com/sergiobayona/VectorMCP/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sergiobayona/vector_mcp/actions/workflows/ruby.yml)
+[![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 provides server-side tools for implementing the [Model Context Protocol (MCP)](https://modelcontext.dev/) in Ruby applications. MCP is a specification for how Large Language Models (LLMs) can discover and interact with external tools, resources, and prompts provided by separate applications (MCP Servers).
+
+This library allows you to easily create MCP servers that expose your application's capabilities (like functions, data sources, or predefined prompt templates) to compatible LLM clients (e.g., Claude Desktop App, custom clients).
+
+## Features
+
+*   **MCP Specification Adherence:** Implements core server-side aspects of the MCP specification.
+*   **Tools:** Define and register custom tools (functions) that the LLM can invoke.
+*   **Resources:** Expose data sources (files, database results, API outputs) for the LLM to read.
+*   **Prompts:** Provide structured prompt templates the LLM can request and use.
+*   **Transport:**
+    *   **Stdio (stable):** Simple transport using standard input/output, ideal for process-based servers.
+    *   **SSE (work-in-progress):** Server-Sent Events support is under active development and currently unavailable.
+*   **Extensible Handlers:** Provides default handlers for core MCP methods, which can be overridden.
+*   **Clear Error Handling:** Custom error classes mapping to JSON-RPC/MCP error codes.
+*   **Ruby-like API:** Uses blocks for registering handlers, following idiomatic Ruby patterns.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'vector_mcp'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install vector_mcp
+```
+
+> ⚠️  **Heads-up:** SSE transport is not yet supported in the released gem. When it lands it will require additional gems (`async`, `async-http`, `falcon`, `rack`).
+
+## Quick Start
+
+This example creates a simple server that runs over standard input/output and provides one tool.
+
+```ruby
+require 'vector_mcp'
+
+# Create a server
+server = VectorMCP.new('Echo Server')
+
+# Register a single "echo" tool
+server.register_tool(
+  name: 'echo',
+  description: 'Returns whatever message you send.',
+  input_schema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message']
+  }
+) { |args, _session| args['message'] }
+
+# Start listening on STDIN/STDOUT (default transport)
+server.run
+```
+
+**To run this:**
+
+1.  Save it as `my_server.rb`.
+2.  Run `ruby my_server.rb`.
+3.  The server now waits for **newline-delimited JSON-RPC objects** on **STDIN** and writes responses to **STDOUT**.
+
+   You have two easy ways to talk to it:
+
+   **a. Interactive (paste a line, press Enter)**
+
+   ```bash
+   $ ruby my_server.rb
+   # paste the JSON below, press ↵, observe the response
+   {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
+   {"jsonrpc":"2.0","method":"initialized"}
+   # etc.
+   ```
+
+   **b. Scripted (pipe a series of echo / printf commands)**
+
+   ```bash
+   { 
+     printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"CLI","version":"0.1"}}}';
+     printf '%s\n' '{"jsonrpc":"2.0","method":"initialized"}';
+     printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}';
+     printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello VectorMCP!"}}}';
+   } | ruby my_server.rb | jq  # jq formats the JSON responses
+   ```
+
+   Each request **must be on a single line and terminated by a newline** so the server knows where the message ends.
+
+   Below are the same requests shown individually:
+
+```jsonc
+// 1. Initialize (client → server)
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ManualClient","version":"0.1"}}}
+
+// 2. Initialized notification (client → server, no id)
+{"jsonrpc":"2.0","method":"initialized"}
+
+// 3. List available tools (client → server)
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+
+// 4. Call the echo tool (client → server)
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello VectorMCP!"}}}
+```
+
+## Usage
+
+### Creating a Server
+
+Instantiate the server using the factory method:
+
+```ruby
+require 'vector_mcp'
+
+server = VectorMCP.new(
+  name: "MyAwesomeServer",
+  version: "2.1.0",
+  log_level: Logger::DEBUG # Optional: Default is INFO
+)
+```
+
+### Registering Tools
+
+Tools are functions your server exposes. Use `register_tool` with a block.
+
+```ruby
+server.register_tool(
+  name: "calculate_sum",
+  description: "Adds two numbers together.",
+  input_schema: {
+    type: "object",
+    properties: {
+      a: { type: "number", description: "First number" },
+      b: { type: "number", description: "Second number" }
+    },
+    required: ["a", "b"]
+  }
+) do |args, session|
+  # args is a hash like { "a" => 10, "b" => 5 }
+  # session object provides session context (e.g., session.initialized?)
+  sum = (args["a"] || 0) + (args["b"] || 0)
+  "The sum is: #{sum}" # Return value is converted to {type: "text", text: ...}
+end
+```
+
+*   The input_schema must be a Hash representing a valid JSON Schema object describing the tool's expected arguments.
+*   The block receives the arguments hash and the VectorMCP::Session object.
+*   The **session** object represents the client connection that invoked the tool. It lets you:
+    * Inspect the client's `clientInfo` and declared `capabilities` (e.g. `session.client_info['name']`).
+    * Store or look up per-connection state (authentication, rate-limiting, feature flags).
+    * Send follow-up notifications or streaming updates back only to that client.
+    * Check whether the session is already `initialized?` before doing expensive work.
+
+    Passing `session` up-front means tool authors can make use of this context today; if you don't need it, simply ignore the parameter (Ruby will accept extra block parameters).
+*   The block's return value is automatically converted into the MCP `content` array format by `VectorMCP::Util.convert_to_mcp_content`. You can return:
+    *   A `String`: Becomes `{ type: 'text', text: '...' }`.
+    *   A `Hash` matching the MCP content structure (`{ type: 'text', ... }`, `{ type: 'image', ... }`, etc.): Used as is.
+    *   Other `Hash` objects: JSON-encoded into `{ type: 'text', text: '...', mimeType: 'application/json' }`.
+    *   Binary String (`Encoding::ASCII_8BIT`): Base64-encoded into `{ type: 'blob', blob: '...', mimeType: 'application/octet-stream' }`.
+    *   An `Array` of the above: Each element is converted and combined.
+    *   Other objects: Converted using `to_s` into `{ type: 'text', text: '...' }`.
+
+### Registering Resources
+
+Resources provide data that the client can read.
+
+```ruby
+server.register_resource(
+  uri: "memory://status", # Unique URI for this resource
+  name: "Server Status",
+  description: "Provides the current server status.",
+  mime_type: "application/json" # Optional: Defaults to text/plain
+) do |session|
+  # Handler block receives the session object
+  {
+    status: "OK",
+    uptime: Time.now - server_start_time, # Example value
+    initialized: session.initialized?
+  } # Hash will be JSON encoded due to mime_type
+end
+
+# Resource returning binary data
+server.register_resource(
+  uri: "file://logo.png",
+  name: "Logo Image",
+  description: "The server's logo.",
+  mime_type: "image/png"
+) do |session|
+  # IMPORTANT: Return binary data as a string with ASCII-8BIT encoding
+  File.binread("path/to/logo.png")
+end
+```
+
+*   The block receives the `VectorMCP::Session` object.
+*   Return `String` for text, or a binary `

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "vector_mcp"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/vector_mcp/definitions.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module VectorMCP
+  # This module contains Struct definitions for Tools, Resources, and Prompts
+  # that a VectorMCP::Server can provide.
+  module Definitions
+    # Represents a tool that can be executed by the AI model.
+    #
+    # @!attribute name [rw] String
+    #   The unique name of the tool.
+    # @!attribute description [rw] String
+    #   A human-readable description of what the tool does.
+    # @!attribute input_schema [rw] Hash
+    #   A JSON Schema object describing the expected input for the tool.
+    # @!attribute handler [rw] Proc
+    #   A callable (e.g., a Proc or lambda) that executes the tool's logic.
+    #   It receives the tool input (a Hash) as its argument.
+    #   The input hash structure should match the input_schema.
+    Tool = Struct.new(:name, :description, :input_schema, :handler) do
+      # Converts the tool to its MCP definition hash.
+      # @return [Hash] A hash representing the tool in MCP format.
+      def as_mcp_definition
+        {
+          name: name,
+          description: description,
+          inputSchema: input_schema # Expected to be a Hash representing JSON Schema
+        }.compact # Remove nil values
+      end
+    end
+
+    # Represents a resource (context or data) that can be provided to the AI model or user.
+    #
+    # @!attribute uri [rw] URI, String
+    #   The unique URI identifying the resource.
+    # @!attribute name [rw] String
+    #   A human-readable name for the resource.
+    # @!attribute description [rw] String
+    #   A description of the resource content.
+    # @!attribute mime_type [rw] String
+    #   The MIME type of the resource content (e.g., "text/plain", "application/json").
+    # @!attribute handler [rw] Proc
+    #   A callable that returns the content of the resource. It may receive parameters from the request (e.g., for dynamic resources).
+    Resource = Struct.new(:uri, :name, :description, :mime_type, :handler) do
+      # Converts the resource to its MCP definition hash.
+      # @return [Hash] A hash representing the resource in MCP format.
+      def as_mcp_definition
+        {
+          uri: uri.to_s,
+          name: name,
+          description: description,
+          mimeType: mime_type
+        }.compact
+      end
+    end
+
+    # Represents a prompt or templated message workflow for users or AI models.
+    #
+    # @!attribute name [rw] String
+    #   The unique name of the prompt.
+    # @!attribute description [rw] String
+    #   A human-readable description of the prompt.
+    # @!attribute arguments [rw] Array<Hash>
+    #   An array of argument definitions for the prompt, where each hash can contain
+    #   `:name`, `:description`, and `:required` (Boolean).
+    # @!attribute handler [rw] Proc
+    #   A callable that generates the prompt content. It receives a hash of arguments, validated against the prompt's argument definitions.
+    Prompt = Struct.new(:name, :description, :arguments, :handler) do
+      # Converts the prompt to its MCP definition hash.
+      # @return [Hash] A hash representing the prompt in MCP format.
+      def as_mcp_definition
+        {
+          name: name,
+          description: description,
+          arguments: arguments # Expected to be an array of { name:, description:, required: } hashes
+        }.compact
+      end
+    end
+  end
+end

data/lib/vector_mcp/errors.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  # Base error class for all VectorMCP specific errors.
+  class Error < StandardError; end
+
+  # Base class for **all** JSON-RPC 2.0 errors that the VectorMCP library can
+  # emit.  It mirrors the structure defined by the JSON-RPC spec and adds a
+  # flexible `details` field that implementers may use to attach structured,
+  # implementation-specific metadata to an error payload.
+  #
+  # @!attribute [r] code
+  #   @return [Integer] The JSON-RPC error code.
+  # @!attribute [r] message
+  #   @return [String] A short description of the error.
+  # @!attribute [rw] request_id
+  #   @return [String, Integer, nil] The ID of the request that caused this error, if applicable.
+  # @!attribute [r] details
+  #   @return [Hash, nil] Additional implementation-specific details for the error (optional).
+  class ProtocolError < Error
+    attr_accessor :request_id
+    attr_reader :code, :message, :details
+
+    # Initializes a new ProtocolError.
+    #
+    # @param message [String] The error message.
+    # @param code [Integer] The JSON-RPC error code.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message, code: -32_600, details: nil, request_id: nil)
+      VectorMCP.logger.debug("Initializing ProtocolError with code: #{code}")
+      @code = code
+      @message = message
+      @details = details # NOTE: `data` in JSON-RPC is often used for this purpose.
+      @request_id = request_id
+      super(message)
+    end
+  end
+
+  # Standard JSON-RPC error classes
+
+  # Represents a JSON-RPC Parse error (-32700).
+  # Indicates invalid JSON was received by the server.
+  class ParseError < ProtocolError
+    # @param message [String] The error message.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Parse error", details: nil, request_id: nil)
+      super(message, code: -32_700, details: details, request_id: request_id)
+    end
+  end
+
+  # Represents a JSON-RPC Invalid Request error (-32600).
+  # Indicates the JSON sent is not a valid Request object.
+  class InvalidRequestError < ProtocolError
+    # @param message [String] The error message.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Invalid Request", details: nil, request_id: nil)
+      super(message, code: -32_600, details: details, request_id: request_id)
+    end
+  end
+
+  # Represents a JSON-RPC Method Not Found error (-32601).
+  # Indicates the method does not exist or is not available.
+  class MethodNotFoundError < ProtocolError
+    # @param method [String] The name of the method that was not found.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(method, details: nil, request_id: nil)
+      details ||= { method_name: method }
+      super("Method not found: #{method}", code: -32_601, details: details, request_id: request_id)
+    end
+  end
+
+  # Represents a JSON-RPC Invalid Params error (-32602).
+  # Indicates invalid method parameter(s).
+  class InvalidParamsError < ProtocolError
+    # @param message [String] The error message.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Invalid params", details: nil, request_id: nil)
+      super(message, code: -32_602, details: details, request_id: request_id)
+    end
+  end
+
+  # Represents a JSON-RPC Internal error (-32603).
+  # Indicates an internal error in the JSON-RPC server.
+  class InternalError < ProtocolError
+    # @param message [String] The error message.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Internal error", details: nil, request_id: nil)
+      super(message, code: -32_603, details: details, request_id: request_id)
+    end
+  end
+
+  # Represents a JSON-RPC server-defined error (codes -32000 to -32099).
+  class ServerError < ProtocolError
+    # @param message [String] The error message.
+    # @param code [Integer] The server-defined error code. Must be between -32099 and -32000. If the
+    #   supplied value falls outside this range it will be coerced to **-32000** in order to comply
+    #   with the JSON-RPC 2.0 specification.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Server error", code: -32_000, details: nil, request_id: nil)
+      VectorMCP.logger.debug("Initializing ServerError with code: #{code}")
+      unless (-32_099..-32_000).cover?(code)
+        warn "Server error code #{code} is outside of the reserved range (-32099 to -32000). Using -32000 instead."
+        code = -32_000
+      end
+      super
+    end
+  end
+
+  # Represents an error indicating a request was received before server initialization completed (-32002).
+  class InitializationError < ServerError
+    # @param message [String] The error message.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Server not initialized", details: nil, request_id: nil)
+      super(message, code: -32_002, details: details, request_id: request_id)
+    end
+  end
+
+  # Represents an error indicating a requested resource or entity was not found (-32001).
+  # Note: This uses a code typically outside the strict JSON-RPC server error range,
+  # but is common in practice for "Not Found" scenarios.
+  class NotFoundError < ProtocolError
+    # @param message [String] The error message.
+    # @param details [Hash, nil] Additional details for the error (optional).
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Not Found", details: nil, request_id: nil)
+      VectorMCP.logger.debug("Initializing NotFoundError with code: -32001")
+      super(message, code: -32_001, details: details, request_id: request_id)
+    end
+  end
+end