vsm 0.1.0 → 0.2.0

data/lib/vsm/ports/mcp/server_stdio.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+require "json"
+require "async"
+
+module VSM
+  module Ports
+    module MCP
+      # Exposes the capsule's tools as an MCP server over stdio (NDJSON JSON-RPC).
+      # Implemented methods: tools/list, tools/call.
+      class ServerStdio < VSM::Port
+        def initialize(capsule:)
+          super(capsule: capsule)
+          @waiters = {}
+          @waiters_mutex = Mutex.new
+        end
+
+        def egress_subscribe
+          # Single subscriber that resolves tool_result waiters by corr_id
+          @capsule.bus.subscribe do |m|
+            next unless m.kind == :tool_result
+            q = nil
+            @waiters_mutex.synchronize { q = @waiters.delete(m.corr_id.to_s) }
+            q&.enqueue(m)
+          end
+          super
+        end
+
+        def loop
+          $stdout.sync = true
+          while (line = $stdin.gets)
+            begin
+              req = JSON.parse(line)
+            rescue => e
+              write_err(nil, code: -32700, message: "Parse error: #{e.message}")
+              next
+            end
+
+            id = req["id"]
+            method = req["method"]
+            params = req["params"] || {}
+            case method
+            when "tools/list"
+              write_ok(id, { tools: list_tools })
+            when "tools/call"
+              name = params["name"].to_s
+              args = params["arguments"] || {}
+              res = call_local_tool(id, name, args)
+              write_ok(id, { content: [{ type: "text", text: res.to_s }] })
+            else
+              write_err(id, code: -32601, message: "Method not found: #{method}")
+            end
+          end
+        end
+
+        private
+
+        def list_tools
+          ops = @capsule.bus.context[:operations_children] || {}
+          ops.values
+             .select { _1.respond_to?(:tool_descriptor) }
+             .map { to_mcp_descriptor(_1.tool_descriptor) }
+        end
+
+        def to_mcp_descriptor(desc)
+          {
+            "name" => desc.name,
+            "description" => desc.description,
+            "input_schema" => desc.schema
+          }
+        end
+
+        def call_local_tool(req_id, name, args)
+          corr = req_id.to_s
+          q = Async::Queue.new
+          @waiters_mutex.synchronize { @waiters[corr] = q }
+          @capsule.bus.emit VSM::Message.new(
+            kind: :tool_call,
+            payload: { tool: name, args: args },
+            corr_id: corr,
+            meta: { session_id: "mcp:stdio" },
+            path: [:mcp, :server, name]
+          )
+          msg = q.dequeue
+          msg.payload
+        ensure
+          @waiters_mutex.synchronize { @waiters.delete(corr) }
+        end
+
+        def write_ok(id, result)
+          puts JSON.dump({ jsonrpc: "2.0", id: id, result: result })
+          $stdout.flush
+        end
+
+        def write_err(id, code:, message:)
+          puts JSON.dump({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
+          $stdout.flush
+        end
+      end
+    end
+  end
+end

data/lib/vsm/roles/intelligence.rb

@@ -12,7 +12,9 @@ module VSM
   #   - system_prompt(session_id) -> String
   #   - offer_tools?(session_id, descriptor) -> true/false (filter tools)
   class Intelligence
-    def initialize(driver:, system_prompt: nil)
+    attr_reader :driver
+
+    def initialize(driver: nil, system_prompt: nil)
       @driver         = driver
       @system_prompt  = system_prompt
       @sessions       = Hash.new { |h,k| h[k] = new_session_state }
@@ -21,6 +23,9 @@ module VSM
     def observe(bus); end
 
     def handle(message, bus:, **)
+      # If no driver is configured, the base implementation is inert.
+      # Subclasses can override #handle to implement non-LLM behavior.
+      return false if @driver.nil?
       case message.kind
       when :user
         sid = message.meta&.dig(:session_id)
@@ -165,4 +170,3 @@ module VSM
     end
   end
 end
-

data/lib/vsm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vsm
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/vsm.rb

@@ -20,6 +20,8 @@ require_relative "vsm/tool/descriptor"
 require_relative "vsm/tool/acts_as_tool"
 require_relative "vsm/tool/capsule"
 
+require_relative "vsm/meta"
+
 require_relative "vsm/executors/fiber_executor"
 require_relative "vsm/executors/thread_executor"
 
@@ -35,6 +37,14 @@ require_relative "vsm/drivers/family"
 
 require_relative "vsm/lens"
 
+# Optional/built-in ports and MCP integration
+require_relative "vsm/ports/chat_tty"
+require_relative "vsm/ports/mcp/server_stdio"
+require_relative "vsm/mcp/jsonrpc"
+require_relative "vsm/mcp/client"
+require_relative "vsm/mcp/remote_tool_capsule"
+require_relative "vsm/dsl_mcp"
+
 module Vsm
   class Error < StandardError; end
   # Your code goes here...

data/mcp_update.md

@@ -0,0 +1,162 @@
+# MCP Integration Plan and Built‑In Ports
+
+This document proposes minimal, practical support to:
+- Expose any VSM capsule as an MCP server over stdio (JSON‑RPC) implementing `tools/list` and `tools/call`.
+- Add two reusable ports to VSM: a generic, customizable Chat TTY port and an MCP stdio server port.
+- Dynamically reflect tools from external MCP servers and wrap them as VSM tool capsules.
+
+The design uses Ruby’s dynamic capabilities and integrates cleanly with existing VSM roles (Operations, Intelligence, Governance, etc.).
+
+## Scope (Phase 1)
+- MCP methods: `tools/list`, `tools/call` only.
+- Transport: JSON‑RPC over stdio (NDJSON framing to start; can evolve to LSP framing without API changes).
+- No additional MCP features (Prompts/Resources/Logs) in this phase.
+
+## Components
+- `VSM::Ports::ChatTTY` — Generic, customizable chat terminal port.
+- `VSM::Ports::MCP::ServerStdio` — MCP server over stdio exposing capsule tools.
+- `VSM::MCP::Client` — Thin stdio JSON‑RPC client for MCP reflection and calls.
+- `VSM::MCP::RemoteToolCapsule` — Wraps a remote MCP tool as a local VSM `ToolCapsule`.
+- `VSM::DSL::ChildrenBuilder#mcp_server` — Reflect and register remote tools with include/exclude/prefix controls.
+- (Tiny core tweak) Inject `bus` into children that accept `bus=` to allow rich observability from wrappers.
+
+## Design Overview
+- Client reflection: spawn an MCP server process, call `tools/list`, build `RemoteToolCapsule`s per tool, and add them as children. Include/exclude/prefix options shape the local tool namespace.
+- Server exposure: reflect local tools via `tools/list`; on `tools/call`, emit a normal VSM `:tool_call` and await matching `:tool_result` (corr_id = JSON‑RPC id) to reply.
+- Operations routing: unchanged for Phase 1. Reflected tools register as regular children; prefixing avoids collisions. (Optional namespacing router can be added later.)
+- Observability: all bridges emit events into the bus so Lens shows clear lanes (client: `[:mcp, :client, server, tool]`; server: `[:mcp, :server, tool]`).
+- Coexistence: ChatTTY targets the user’s real TTY (e.g., `IO.console`) or stderr; MCP server uses stdio exclusively. They can run together without interfering.
+
+## File Layout (proposed)
+- `lib/vsm/ports/chat_tty.rb`
+- `lib/vsm/ports/mcp/server_stdio.rb`
+- `lib/vsm/mcp/jsonrpc.rb` (shared stdio JSON‑RPC util)
+- `lib/vsm/mcp/client.rb`
+- `lib/vsm/mcp/remote_tool_capsule.rb`
+- `lib/vsm/dsl_mcp.rb` (adds `mcp_server` to the DSL ChildrenBuilder)
+- (Core) optional `bus` injection in `lib/vsm/capsule.rb`
+
+## APIs and Usage
+
+### Expose a Capsule via CLI and MCP (simultaneously)
+```ruby
+require "vsm"
+require "vsm/ports/chat_tty"
+require "vsm/ports/mcp/server_stdio"
+
+cap = VSM::DSL.define(:demo) do
+  identity     klass: VSM::Identity,    args: { identity: "demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: VSM::Drivers::OpenAI::AsyncDriver.new(api_key: ENV["OPENAI_API_KEY"], model: "gpt-4o-mini") }
+  monitoring   klass: VSM::Monitoring
+  operations do
+    # local tools …
+  end
+end
+
+ports = [
+  VSM::Ports::MCP::ServerStdio.new(capsule: cap),               # machine IO (stdio)
+  VSM::Ports::ChatTTY.new(capsule: cap)                          # human IO (TTY/console)
+]
+VSM::Runtime.start(cap, ports: ports)
+```
+
+### Mount a Remote MCP Server (dynamic reflection)
+```ruby
+require "vsm"
+require "vsm/dsl_mcp"
+
+cap = VSM::DSL.define(:with_remote) do
+  identity     klass: VSM::Identity,    args: { identity: "with_remote", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: VSM::Drivers::Anthropic::AsyncDriver.new(api_key: ENV["ANTHROPIC_API_KEY"], model: "claude-sonnet-4.0") }
+  monitoring   klass: VSM::Monitoring
+  operations do
+    mcp_server :smith, cmd: "smith-server --stdio", include: %w[search read], prefix: "smith_", env: { "SMITH_TOKEN" => ENV["SMITH_TOKEN"] }
+  end
+end
+
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap)])
+```
+
+### Filter Tools Offered to the Model (optional)
+```ruby
+class GuardedIntel < VSM::Intelligence
+  def offer_tools?(sid, descriptor)
+    descriptor.name.start_with?("smith_") # only offer smith_* tools
+  end
+end
+```
+
+## Customization (ChatTTY)
+- Constructor options: `input:`, `output:`, `banner:`, `prompt:`, `theme:`.
+- Defaults: reads/writes to `IO.console` if available; otherwise reads are disabled and output goes to a safe stream (stderr/console). Never interferes with MCP stdio.
+- Override points: subclass and override `banner(io)` and/or `render_out(message)` while reusing the main input loop.
+
+Example (options only):
+```ruby
+tty = VSM::Ports::ChatTTY.new(
+  capsule: cap,
+  banner: ->(io) { io.puts "\e[96mMy App\e[0m — welcome!" },
+  prompt: "Me> "
+)
+```
+
+Example (subclass):
+```ruby
+class FancyTTY < VSM::Ports::ChatTTY
+  def banner(io)
+    io.puts "\e[95m\n ███  MY APP  ███\n\e[0m"
+  end
+  def render_out(m)
+    super
+    @out.puts("\e[92m✓ #{m.payload.to_s.slice(0,200)}\e[0m") if m.kind == :tool_result
+  end
+end
+```
+
+## Coexistence and IO Routing
+- MCP stdio server: reads `$stdin`, writes `$stdout` with strict JSON (one message per line). No TTY assumptions.
+- ChatTTY: prefers `IO.console` for both input and output; falls back to `$stderr` for output and disables input if no TTY is present.
+- Result: Both ports can run in the same process without corrupting MCP stdio.
+
+## Observability
+- Client wrapper emits `:progress`/`:audit` with `path: [:mcp, :client, server, tool]` around calls.
+- Server port emits `:audit` and wraps `tools/call` into standard `:tool_call`/`:tool_result` with `corr_id` mirrored to JSON‑RPC id.
+- Lens will show clear lanes and full payloads, subject to Governance redaction (if any).
+
+## Governance and Operations
+- Operations: unchanged; executes capsules for `:tool_call` and emits `:tool_result`.
+- Governance: gate by name/prefix/regex; apply timeouts/rate limits/confirmations; redact args/results in Lens if needed.
+- Execution mode: remote wrappers default to `:thread` to avoid blocking the reactor on stdio I/O.
+
+## Configuration and Authentication
+- Default via ENV (e.g., tokens/keys). Per‑mount overrides available through `mcp_server env: { … }`.
+- CLI flags can be introduced later in a helper script if needed.
+
+## Backward Compatibility
+- No changes to `airb`. `VSM::Ports::ChatTTY` is a reusable, minimal alternative for new apps.
+
+## Future Extensions (not in Phase 1)
+- Namespaced mounts (`smith.search`) with a tiny router enhancement in Operations.
+- Code generation flow (`vsm mcp import …`) to create durable wrappers.
+- Additional MCP features (prompts/resources/logs) and WebSocket transport.
+- Web interaction port: HTTP chat with customizable UI surfaces.
+
+## Milestones
+1) Implement ports and client/wrapper (files above), plus optional `bus` injection.
+2) Add small README/usage and example snippet in `examples/`.
+3) Manual tests: 
+   - Start capsule with both ChatTTY and MCP ports; verify no IO collision.
+   - Reflect a known MCP server; verify tool listing and calls.
+   - Lens shows client/server lanes with corr_id continuity.
+4) Optional: DSL include/exclude/prefix validation and guardrails.
+
+## Acceptance Criteria
+- Starting a capsule with `VSM::Ports::MCP::ServerStdio` exposes working `tools/list` and `tools/call` on stdio.
+- Starting a capsule with `VSM::Ports::ChatTTY` provides a working chat loop; banner/prompt are overridable without re‑implementing the loop.
+- Running both ports concurrently does not corrupt MCP stdio.
+- Reflecting a remote MCP server via `mcp_server` registers local tool capsules that work with `Intelligence` tool‑calling.
+- Lens displays meaningful events for both client and server paths.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vsm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Scott Werner
@@ -79,20 +79,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.17'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.79'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.79'
 description: |
   VSM is a small Ruby framework for building agentic systems using a
   Viable System Model–style architecture. It gives you Capsules: self‑contained components
@@ -100,13 +86,13 @@ description: |
   Identity) plus an async runtime so many capsules can run concurrently.
 email:
 - scott@sublayer.com
-executables: []
+executables:
+- vsm
 extensions: []
 extra_rdoc_files: []
 files:
 - ".claude/settings.local.json"
 - ".rspec"
-- ".rubocop.yml"
 - CLAUDE.md
 - LICENSE.txt
 - README.md
@@ -118,25 +104,58 @@ files:
 - examples/03_openai_tools.rb
 - examples/03b_anthropic_tools.rb
 - examples/03c_gemini_tools.rb
+- examples/05_mcp_server_and_chattty.rb
+- examples/06_mcp_mount_reflection.rb
+- examples/07_connect_claude_mcp.rb
+- examples/08_custom_chattty.rb
+- examples/09_mcp_with_llm_calls.rb
+- examples/10_meta_read_only.rb
+- exe/vsm
 - lib/vsm.rb
 - lib/vsm/async_channel.rb
 - lib/vsm/capsule.rb
+- lib/vsm/cli.rb
 - lib/vsm/drivers/anthropic/async_driver.rb
 - lib/vsm/drivers/family.rb
 - lib/vsm/drivers/gemini/async_driver.rb
 - lib/vsm/drivers/openai/async_driver.rb
 - lib/vsm/dsl.rb
+- lib/vsm/dsl_mcp.rb
 - lib/vsm/executors/fiber_executor.rb
 - lib/vsm/executors/thread_executor.rb
+- lib/vsm/generator/new_project.rb
+- lib/vsm/generator/templates/Gemfile.erb
+- lib/vsm/generator/templates/README_md.erb
+- lib/vsm/generator/templates/Rakefile.erb
+- lib/vsm/generator/templates/bin_console.erb
+- lib/vsm/generator/templates/bin_setup.erb
+- lib/vsm/generator/templates/exe_name.erb
+- lib/vsm/generator/templates/gemspec.erb
+- lib/vsm/generator/templates/gitignore.erb
+- lib/vsm/generator/templates/lib_name_rb.erb
+- lib/vsm/generator/templates/lib_organism_rb.erb
+- lib/vsm/generator/templates/lib_ports_chat_tty_rb.erb
+- lib/vsm/generator/templates/lib_tools_read_file_rb.erb
+- lib/vsm/generator/templates/lib_version_rb.erb
 - lib/vsm/homeostat.rb
 - lib/vsm/lens.rb
 - lib/vsm/lens/event_hub.rb
 - lib/vsm/lens/server.rb
 - lib/vsm/lens/stats.rb
 - lib/vsm/lens/tui.rb
+- lib/vsm/mcp/client.rb
+- lib/vsm/mcp/jsonrpc.rb
+- lib/vsm/mcp/remote_tool_capsule.rb
 - lib/vsm/message.rb
+- lib/vsm/meta.rb
+- lib/vsm/meta/snapshot_builder.rb
+- lib/vsm/meta/snapshot_cache.rb
+- lib/vsm/meta/support.rb
+- lib/vsm/meta/tools.rb
 - lib/vsm/observability/ledger.rb
 - lib/vsm/port.rb
+- lib/vsm/ports/chat_tty.rb
+- lib/vsm/ports/mcp/server_stdio.rb
 - lib/vsm/roles/coordination.rb
 - lib/vsm/roles/governance.rb
 - lib/vsm/roles/identity.rb
@@ -148,6 +167,7 @@ files:
 - lib/vsm/tool/descriptor.rb
 - lib/vsm/version.rb
 - llms.txt
+- mcp_update.md
 - sig/vsm.rbs
 homepage: https://github.com/sublayerapp/vsm
 licenses:
@@ -169,7 +189,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: 'Async, recursive agent framework for Ruby (Viable System Model): capsules,
   tools-as-capsules, streaming tool calls, and observability.'

data/.rubocop.yml

@@ -1,8 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.1
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes