plasma-mcp 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: acc716872cb9b5f8f874e0b29c1f9e26a5cec5ec82c8a527a5cb1c1a3d1d3ab8
+  data.tar.gz: aab888a1298721434f6f89faa11540c06417cba3d2e4adb349f828defff87bf0
+SHA512:
+  metadata.gz: 96d837ef33358f0896cc23262823688dd6bc83c92626d434185a32c5084af411848bf3ba63fff3d94c9b11a535af153520879858e882b956c42dfe8117e9a1a9
+  data.tar.gz: a13232228c0136175ce1efa6051b965590a8d6a91901bf6a1615493d04a80536426b74831940e5a4c37c70c4ec7ab75f09665d9a5e869b2bcfa5fda6724f1e21

data/.rubocop.yml

@@ -0,0 +1,16 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Layout/TrailingEmptyLines:
+  EnforcedStyle: final_newline

data/.ruby-version

@@ -0,0 +1 @@
+3.4.3

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release
+
+### Changed
+- None
+
+### Deprecated
+- None
+
+### Removed
+- None
+
+### Fixed
+- None
+
+### Security
+- None

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jacob Foster Heimark
+
+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,207 @@
+# Plasma
+
+[![Join our Discord](https://img.shields.io/discord/1338362937550573643?color=7289DA&label=Discord&logo=discord&logoColor=white)](https://discord.gg/B6NPUAgYmH)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/plasma-mcp/plasma/actions/workflows/main.yml/badge.svg)](https://github.com/plasma-mcp/plasma/actions/workflows/main.yml)
+
+The **P**ractical **L**aunchpad **A**ssisting with **M**CP **A**bstraction.
+
+![Plasma Logo](assets/ruby-plasma-mcp-300x300.png)
+
+Plasma is a Ruby-based SDK that provides a Rails-inspired, convention-over-configuration approach to building Model Context Protocol servers. Like a plasma engine powering a spacecraft, Plasma provides the fundamental infrastructure to power your MCP services with minimal resistance.
+
+> [🚀 Getting Started](#getting-started) • [📖 Usage Guide](#usage-guide) • [⚙️ Development](#development)
+
+> ⚠️ **Warning**: Plasma is currently in pre-alpha development (0.0.1-pre). Until version 0.1.0 is released, all versions (including patch updates) may contain breaking changes. This allows us to rapidly iterate and improve the API based on early feedback. See our [roadmap](docs/ROADMAP.md) for more details.
+
+## Features
+
+- ✅ Rails-inspired project and component generation (tools, prompts, and resources)
+- ✅ Storage system for persistent data (variables and records)
+- 🚧 Local authentication system via Omniauth (coming soon - partially implemented)
+
+## Getting Started
+
+### Requirements
+
+- Ruby `3.4` or higher (tested on `3.4.2+`)
+- Bundler
+- Docker (optional, for containerized deployment)
+
+### Installation
+
+Install Plasma:
+
+```bash
+gem install plasma-mcp
+```
+
+### Quick Start
+
+1. Create a new project:
+```bash
+plasma new my_server
+cd my_server
+```
+
+2. Generate your first tool:
+```bash
+plasma g tool greeting name:string
+```
+
+
+4. Start your plasma server (in STDIN/STDOUT mode)
+```bash
+plasma server
+```
+
+5. Pass it some JSON to try it out:
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"greeting","arguments":{"name":"Jean-Luc Picard"}}}
+```
+
+You will get the output:
+```json
+{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Hello from GreetingTool with params: Jean-Luc Picard "}],"isError":false}}
+```
+
+Congratulations. We have liftoff! 🚀
+
+## Usage Guide
+
+### Project Structure
+```
+my_server/
+├── app/
+│   ├── prompts/        # MCP prompts
+│   ├── resources/      # MCP resources
+│   ├── tools/          # MCP tools
+│   ├── variables/      # Per-sesion variables (e.g. `current_user_email_variable`)
+│   └── records/        # Stored objects (e.g. `task_records`)
+├── config/
+│   ├── initializers/   # Preload configuration
+│   ├── application.rb  # MCP server configuration
+│   └── boot.rb         # Launch ignition sequence
+└── .env                # Environment variables
+```
+
+### Creating Tools
+
+Generate a new tool using the CLI:
+
+```bash
+plasma g tool greeting name:string
+```
+
+This will generate a tool file in `app/tools/greeting_tool.rb` that follows this structure:
+
+```ruby
+# app/tools/greeting_tool.rb
+module MyServer
+  module Tools
+    # A friendly space station greeting system
+    class GreetingTool < Plasma::Tool
+      param :name,
+            type: :string,
+            description: "Name of the space traveler to welcome"
+
+      def call
+        respond_with(:text,
+          text: <<~GREETING
+            Welcome aboard, #{params[:name]}!
+            Your presence has been registered in our stellar database. 🚀
+          GREETING
+        )
+      end
+    end
+  end
+end
+```
+
+The tool's description is automatically extracted from the comment above the class. Parameters are defined using the `param` class method, which supports:
+- `type`: The parameter type (`:string`, `:number`, `:float`, `:boolean`, or `:array`)
+- `description`: A description of the parameter
+- `required`: Whether the parameter is required (defaults to false)
+
+Parameters are accessed in the `call` method via the `params` hash.
+
+The `respond_with` method supports several response types: `:text`, `:image`, `:resource` and `:error`
+
+### Configuration
+
+Configure your application in `config/application.rb`:
+
+```ruby
+module MyServer
+  class Application < Plasma::Application
+    self.initialize! do |config|
+      config.name = "My Custom Server Name"
+  end
+end
+```
+
+## Deployment
+
+### Traditional `STDIN/STDOUT` Deployment
+
+1. Set up your environment variables
+2. Run the server:
+```bash
+plasma server
+```
+
+### Docker `STDIN/STDOUT` Deployment (coming soon)
+
+Docker deployment support is currently under development. This feature will provide:
+- Pre-built Docker images for easy deployment
+- Containerized environment for consistent execution
+- Integration with popular container orchestration platforms
+
+Stay tuned for updates in our upcoming releases!
+
+### SSE Deployment (coming soon)
+
+Server-Sent Events (SSE) deployment is planned for version 0.2.0. This feature will include:
+- Real-time event streaming capabilities
+- WebSocket support for bidirectional communication
+- Enhanced monitoring and debugging tools
+- Improved error handling and recovery mechanisms
+
+Stay tuned for updates in our upcoming releases!
+
+## Development
+
+### Getting Started with Development
+
+After git cloning, run `bin/setup` to install dependencies. Then, run `rake test` to run the diagnostics. You can also run `bin/console` for a low level command terminal.
+
+To start an interactive console for your project (similar to `rails console`):
+
+```bash
+plasma console
+```
+
+This will give you access to your project's environment where you can interact with your components, storage variables, and other features:
+
+```ruby
+# Example console session
+> MyTool.new.call
+=> "Tool execution result"
+```
+
+### Roadmap
+For detailed information about our development status, versioning strategy, and roadmap, please see [ROADMAP.md](docs/ROADMAP.md).
+
+## Community & Contributing
+
+Join our Discord community to connect with other developers, get help, and stay updated on the latest developments:
+
+[![Join our Discord](https://img.shields.io/discord/1338362937550573643?color=7289DA&label=Discord&logo=discord&logoColor=white)](https://discord.gg/B6NPUAgYmH)
+
+## Contributing
+
+Improvements and bug reports are welcome on GitHub at https://github.com/plasma-mcp/plasma
+
+## License
+
+This project is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_globs = ["test/test_helper.rb", "test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/docs/ROADMAP.md

@@ -0,0 +1,46 @@
+# Plasma Development Roadmap
+
+## Versioning Strategy
+
+**Until version 0.1.0 is released, all versions (including patch updates) may contain breaking changes.** This allows us to rapidly iterate and improve the API based on early feedback. After version 0.1.0, we will strictly follow semantic versioning:
+
+- **Major version** (1.0.0, 2.0.0): Breaking changes
+- **Minor version** (1.1.0, 1.2.0): New features, no breaking changes
+- **Patch version** (1.0.1, 1.0.2): Bug fixes and minor improvements, no breaking changes
+
+## Current Status
+
+Plasma is currently in alpha development (0.0.x). The project is actively being developed with the following planned milestones:
+
+- Version 0.0.1: Initial alpha release with basic functionality
+- Version 0.1.0: Beta release with core features
+- Version 0.2.0: First stable release
+
+## Development Focus
+
+### 0.1 Development Focus
+
+- [x] Storage system for persistent data
+- [x] Component generation for prompts, resources, and tools
+- [x] Improved tool response mechanics (i.e. `respond_with`-ish rails pattern on response)
+- [x] Improved tool ergonomics with type hints and Ruby magic
+- [x] Draft authentication system implementation
+- [x] Docker file template as part of new generation (and commands to upload)
+- [x] Including docker usage in readme
+- [x] First pass at authentication system with Sinatra
+- [ ] Reference servers with example usage
+- [ ] Gem & executable as part of new generation
+- [ ] CLI command to get json for Claude (docker and gem versions)
+
+### 0.2 Development Focus
+- Complete authentication system implementation
+- Update to include features from latest MCP version (`2025-03-27`)
+- Server-Sent Events (SSE) support for real-time updates
+- Enhanced OAuth integration with latest MCP authentication patterns
+- Improved error handling and recovery mechanisms
+- Performance optimizations for high-concurrency scenarios
+- Generate rspec tests and test framework on `plasma new`
+- Migrate to rspec for plasma-mcp itself
+- Expand test coverage and CI/CD pipeline improvements
+- Testing framework improvements with helper methods and fixtures for common MCP patterns
+- Wiki / improved documentation

data/exe/plasma

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "plasma"
+
+Plasma::CLI.start(ARGV)

data/lib/plasma/application.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/introspection"
+require "active_support/core_ext/class/subclasses"
+require "model_context_protocol"
+require "zeitwerk"
+require "sinatra/base"
+require "omniauth"
+require "securerandom"
+
+module Plasma
+  # Base application class for PLASMA applications
+  class Application
+    class << self
+      attr_accessor :config, :registry, :server
+
+      # Initialize the application
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      def initialize!
+        # Set up configuration
+        @config ||= Configuration.new
+        yield @config if block_given?
+
+        # Set default name based on module name if not explicitly set
+        if @config.name.nil?
+          module_name = to_s.split("::").first
+          @config.name = "#{module_name} MCP Server"
+        end
+
+        # Set up autoloading
+        module_name = module_parent.name
+        loader = Zeitwerk::Loader.new
+        loader.push_dir("./app", namespace: Object.const_get(module_name))
+        loader.push_dir(File.expand_path("../plasma", __dir__), namespace: Plasma)
+        loader.setup
+
+        # Load prompts, resources, and tools
+        load_all_components
+
+        # Load the plasma auth server in case it is subclassed
+        require "plasma/auth_server"
+
+        # Create the server
+        @server = ModelContextProtocol::Server.new do |config|
+          config.name = @config.name || "PLASMA MCP Server"
+          config.version = @config.version || "1.0.0"
+          config.enable_log = @config.enable_log
+
+          # Apply environment variables
+          @config.required_env_vars.each do |var|
+            config.require_environment_variable(var)
+          end
+
+          @config.env_vars.each do |key, value|
+            config.set_environment_variable(key, value)
+          end
+        end
+
+        # Set up the registry
+        setup_registry
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+      # Start the MCP server
+      def start_server
+        @server.start
+      end
+
+      # Load all the application's components
+      def load_all_components
+        load_prompts
+        load_resources
+        load_tools
+        load_variables
+        load_records
+      end
+
+      # Find all prompt classes
+      def prompts
+        descendants_of("Prompts")
+      end
+
+      # Find all resource classes
+      def resources
+        descendants_of("Resources")
+      end
+
+      # Find all tool classes
+      def tools
+        descendants_of("Tools")
+      end
+
+      private
+
+      # Set up the MCP registry with all components
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def setup_registry
+        @registry = ModelContextProtocol::Server::Registry.new do
+          prompts list_changed: true do
+            Plasma::Prompt.descendants.each do |prompt_class|
+              register prompt_class
+            end
+          end
+
+          resources list_changed: true, subscribe: true do
+            Plasma::Resource.descendants.each do |resource_class|
+              register resource_class
+            end
+          end
+
+          tools list_changed: true do
+            Plasma::Tool.descendants.each do |tool_class|
+              register tool_class
+            end
+          end
+        end
+
+        # Set the registry on the server
+        @server.configuration.registry = registry
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      # Find all descendants of a particular module
+      def descendants_of(module_name)
+        # Get the application module
+        app_module = to_s.split("::").first.constantize
+
+        # Find all classes that are defined in the specified module
+        ObjectSpace.each_object(Class).select do |klass|
+          klass.name&.start_with?("#{app_module}::#{module_name}::") &&
+            klass != app_module.const_get(module_name)
+        end
+      end
+
+      # Load all prompt files
+      def load_prompts
+        Dir[File.join(app_root, "app/prompts/**/*.rb")].each { |f| require f }
+      end
+
+      # Load all resource files
+      def load_resources
+        Dir[File.join(app_root, "app/resources/**/*.rb")].each { |f| require f }
+      end
+
+      # Load all tool files
+      def load_tools
+        Dir[File.join(app_root, "app/tools/**/*.rb")].each { |f| require f }
+      end
+
+      # Load all variable files
+      def load_variables
+        Dir[File.join(app_root, "app/variables/**/*.rb")].each { |f| require f }
+      end
+
+      # Load all record files
+      def load_records
+        Dir[File.join(app_root, "app/records/**/*.rb")].each { |f| require f }
+      end
+
+      # Get the application root directory
+      def app_root
+        # Default to the current directory
+        Dir.pwd
+      end
+    end
+
+    # Configuration class for PLASMA applications
+    class Configuration
+      attr_accessor :name, :version, :enable_log, :module_name, :auth_port, :auth_host, :omniauth_provider_args
+      attr_reader :required_env_vars, :env_vars
+
+      def initialize
+        @name = nil
+        @version = nil
+        @enable_log = true
+        @module_name = nil
+        @required_env_vars = []
+        @env_vars = {}
+        @auth_port = 4567
+        @auth_host = "localhost"
+        @omniauth_provider_args = {}
+      end
+
+      def require_environment_variable(name)
+        @required_env_vars << name
+      end
+
+      def set_environment_variable(name, value)
+        @env_vars[name] = value
+      end
+    end
+  end
+end

data/lib/plasma/auth.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "puma"
+
+module Plasma
+  # Handles authentication operations
+  class Auth
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = options
+    end
+
+    def start
+      puts "Starting authentication server..."
+
+      return error_not_plasma_project unless plasma_project?
+
+      application = Plasma::Loader.load_project
+      config = application.config
+
+      port, host = resolve_port_and_host(config)
+      auth_server_class = resolve_auth_server_class(application)
+      puma_auth_server = Puma::Server.new(auth_server_class.new)
+      puma_auth_server.add_tcp_listener(host, port)
+
+      run_and_wait_for_shutdown(puma_auth_server, auth_server_class)
+
+      # TODO: check if the config vars have actually been set
+      puts "Authentication server succesfully shutdown."
+    end
+
+    private
+
+    def error_not_plasma_project
+      puts "Error: Not a PLASMA project directory. Please run this command from the root of a PLASMA project."
+      false
+    end
+
+    def resolve_port_and_host(config)
+      [
+        @options[:port] || config.auth_port || 4567,
+        @options[:host] || config.auth_host || "localhost"
+      ]
+    end
+
+    def resolve_auth_server_class(application)
+      application.module_parent.const_get("AuthServer")
+    end
+
+    def run_and_wait_for_shutdown(puma_auth_server, auth_server_class)
+      puma_auth_server.run
+      Timeout.timeout(300) do
+        sleep 0.1 until auth_server_class.ready_to_shutdown?
+      rescue Timeout::Error
+        puts "Authentication server did not shutdown in time. Forcing shutdown."
+      end
+      puma_auth_server.halt
+    end
+
+    def plasma_project?
+      File.exist?("config/application.rb") &&
+        File.exist?("config/boot.rb") &&
+        Dir.exist?("app/prompts") &&
+        Dir.exist?("app/resources") &&
+        Dir.exist?("app/tools")
+    end
+
+    def start_auth_server
+      puts "Starting authentication server on #{options[:host]}:#{options[:port]}..."
+      puts "This is a placeholder for the actual authentication server."
+      puts "In a real implementation, this would start a server with OAuth endpoints."
+
+      # This is a placeholder for the actual authentication server implementation
+      loop do
+        sleep 1
+      end
+    rescue Interrupt
+      puts "\nShutting down authentication server..."
+    end
+  end
+end

data/lib/plasma/auth_server.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "omniauth"
+require "sinatra/base"
+require "rack/protection"
+
+module Plasma
+  # Handles OAuth authentication for PLASMA applications
+  class AuthServer < Sinatra::Base
+    use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET") { SecureRandom.hex(32) }
+    use Rack::Protection::AuthenticityToken
+
+    app = Plasma::Loader.load_project
+
+    use OmniAuth::Builder do
+      provider(*app.config.omniauth_provider_args)
+    end
+
+    def self.mark_ready_to_shutdown
+      @ready_to_shutdown = true
+    end
+
+    def self.ready_to_shutdown?
+      @ready_to_shutdown ||= false
+    end
+
+    get "/" do
+      raise NotImplementedError, "This endpoint is not implemented, you must implement it in your auth_server.rb"
+    end
+
+    configure :development do
+      set :show_exceptions, true
+    end
+
+    get "/callback" do
+      token = request.env.dig("omniauth.auth", :credentials, :token)
+      if token
+        self.class.mark_ready_to_shutdown
+        "token: #{token}"
+      else
+        "No token found, request.env: #{request.env.inspect}"
+      end
+    end
+  end
+end