aia 0.9.22 → 0.9.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e34cfc1092812c76266e11c14b10c7df0d06268e57945ad984ea28b2bebd4ac2
-  data.tar.gz: a1f3bb8530c55fae801aae161173f61a0902d183db3f77bbb04440c7e4bb2204
+  metadata.gz: f9592d9ea1bbbbdc04f92dc822cfbdae91c1e04084530583e50f6cdb8a90460d
+  data.tar.gz: 897e53ec02de0fcc46a0e5ddcf15ca13a462b7cc20e4f355950f5872e5b04f00
 SHA512:
-  metadata.gz: 7a91f8b0fbaad8d2bcbe476aacd37d894746bb1773a1c8fe2a3c8fec28ecea5c577ed002f42a7f34278a0ab1163ee9dc63385f083d018ac87ad9179d8f2bdcfc
-  data.tar.gz: 2ebba9e5b65df0caf6acab01dc6fe4740e8671a4a522dbced54f411356d4cea94e0459a5f446a040228929574c79e898267c8ee42bd0cf8c21444e3ac37c7233
+  metadata.gz: 5e8b63a8ca892346e4dd1090ef487e4fc6dc6b9395238ecc6208128d8908a5dca87d730a9193a15b05dbb005b8d9eb84e2bb7f63100982130eeec69e0bb9483d
+  data.tar.gz: 660c1c40117300223a7bd88c67ec826225a44ada72d459ee6c8fd3e3c015e81a7874a9618220c4dc7caf3de930ee140d29ef1c7c8dfc205ecfeedef8e629b36a

data/.version

@@ -1 +1 @@
-0.9.22
+0.9.24

data/CHANGELOG.md

@@ -1,6 +1,66 @@
 # Changelog
 ## [Unreleased]
 
+## [0.9.24] 2025-12-17
+### Fixes
+- Ran into a problem with the `shared_tools` gem and the --require parameter of AIA which required changes to both gems.
+
+### Improvements
+- **`//tools` Directive Filter**: Added optional filter parameter to the `//tools` directive
+  - Filter tools by name substring (case-insensitive)
+  - Example: `//tools error` lists only tools with "error" in the name
+  - Shows "No tools match the filter: [filter]" when no matches found
+  - Header indicates when filtering is active: "Available Tools (filtered by 'filter')"
+
+## [0.9.23] 2025-12-06
+
+### New Features
+- **MCP Server Configuration**: Added native support for defining MCP (Model Context Protocol) servers in the config file
+  - Configure MCP servers in `~/.aia/config.yml` under the `mcp_servers` key
+  - Supports `name`, `command`, `args`, `env`, and `timeout` options per server
+  - Automatic PATH resolution for commands (no absolute paths required)
+  - Configurable timeouts for slow-starting servers (default: 8000ms)
+  - Environment variable support for MCP server processes
+
+### Improvements
+- **Robot Display**: Added MCP server names to the robot ASCII art display
+  - Shows "MCP: server1, server2, ..." when MCP servers are configured
+
+### Technical Changes
+- Added `load_mcp_servers` method to `lib/aia/config/base.rb` for automatic MCP client registration
+- Added `resolve_command_path` method for PATH-based command resolution
+- Added `mcp_servers?` and `mcp_server_names` helper methods to `lib/aia/utility.rb`
+- Fixed `OpenStruct.merge` to skip nil values, preventing config file values from being overwritten
+- Added `mcp_servers: nil` default to prevent merge issues with empty arrays
+
+### Configuration Example
+```yaml
+# ~/.aia/config.yml
+:mcp_servers:
+  - name: "my-server"
+    command: "my_mcp_server.rb"
+    args: ["stdio"]
+    timeout: 30000
+    env:
+      MY_VAR: "value"
+```
+
+## [0.9.22] 2025-11-12
+
+### Bug Fixes
+- **TEST SUITE**: Fixed all Mocha test isolation issues causing stub contamination between tests
+  - Added proper teardown methods with `super` calls to 13 test files to ensure Mocha cleanup
+  - Fixed PromptHandlerTest missing teardown and config fields (erb, shell, roles_dir)
+  - Fixed ModelsDirectiveTest to use consistent stubbing approach instead of mixing real and stubbed config
+  - Fixed MultiModelIsolationTest to use stubs instead of direct instance variable manipulation
+  - Fixed AIAIntegrationTest, ChatProcessorServiceTest, ContextManagerTest, DirectiveProcessorTest, RubyLLMAdapterTest, SessionTest, LocalProvidersTest, UtilityTest, AIAMockingTest, and AIAPropertyBasedTest to include proper Mocha cleanup
+  - Test results improved from 2 failures, 2 errors to 0 failures, 0 errors (325 runs, 1018 assertions)
+
+### Technical Changes
+- Enhanced test isolation by ensuring all tests using Mocha stubs properly clean up via `super` in teardown
+- Standardized stub usage pattern across test suite for consistency
+- Eliminated stub leakage that caused "unexpected invocation" and "AIA was instantiated in one test but receiving invocations in another" errors
+
 ## [0.9.21] 2025-10-08
 ### Bug Fixes
 - **Checkpoint Directive Output**: Fixed `//checkpoint` directive to return empty string instead of status message (lib/aia/directives/configuration.rb:155)

data/README.md

@@ -100,6 +100,7 @@ For more information on AIA visit these locations:
       - [Example Workflow](#example-workflow)
     - [Roles and System Prompts](#roles-and-system-prompts)
     - [RubyLLM::Tool Support](#rubyllmtool-support)
+    - [MCP Server Configuration](#mcp-server-configuration)
   - [Examples & Tips](#examples--tips)
     - [Practical Examples](#practical-examples)
       - [Code Review Prompt](#code-review-prompt)
@@ -350,7 +351,7 @@ Directives are special commands in prompt files that begin with `//` and provide
 | `//help` | Show available directives | `//help` |
 | `//model` | Show current model configuration | `//model` |
 | `//available_models` | List available models | `//available_models` |
-| `//tools` | Show a list of available tools and their description | `//tools` |
+| `//tools` | Show available tools (optional filter by name) | `//tools` or `//tools file` |
 | `//review` | Review current context with checkpoint markers | `//review` |
 
 Directives can also be used in the interactive chat sessions.
@@ -922,6 +923,177 @@ aia --tools examples/tools/mcp/imcp.rb --chat
 
 These MCP clients require the `ruby_llm-mcp` gem and provide access to external services and data sources through the Model Context Protocol.
 
+### MCP Server Configuration
+
+AIA supports defining MCP (Model Context Protocol) servers directly in your configuration file. This allows MCP tools to be automatically loaded at startup without needing to specify them on the command line each time.
+
+#### Configuration Format
+
+Add MCP servers to your `~/.aia/config.yml` file:
+
+```yaml
+:mcp_servers:
+  - name: "server-name"
+    command: "server_command"
+    args: ["arg1", "arg2"]
+    timeout: 30000  # milliseconds (default: 8000)
+    env:
+      ENV_VAR: "value"
+```
+
+#### Configuration Options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `name` | Yes | - | Unique identifier for the MCP server |
+| `command` | Yes | - | Executable command (absolute path or found in PATH) |
+| `args` | No | `[]` | Array of command-line arguments |
+| `timeout` | No | `8000` | Connection timeout in milliseconds |
+| `env` | No | `{}` | Environment variables for the server process |
+
+#### Example: GitHub MCP Server
+
+The GitHub MCP server provides access to GitHub repositories, issues, pull requests, and more:
+
+```yaml
+# ~/.aia/config.yml
+:mcp_servers:
+  - name: "github"
+    command: "github-mcp-server"
+    args: ["stdio"]
+    timeout: 15000
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_token_here"
+```
+
+**Setup:**
+```bash
+# Install GitHub MCP server (macOS)
+brew install github-mcp-server
+
+# Or via npm
+npm install -g @anthropic/github-mcp-server
+
+# Set your GitHub token (recommended: use environment variable instead of config)
+export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"
+```
+
+#### Example: Hierarchical Temporal Memory (HTM)
+
+```shell
+gem install htm
+```
+
+See the [full HTM documentation](https://madbomber.github.io/htm) for database configuration and system environment variable usage.
+
+A custom Ruby-based MCP server for accessing database-backed long term memory:
+
+```yaml
+# ~/.aia/config.yml
+:mcp_servers:
+  - name: "htm"
+    command: "htm_mcp.rb"
+    args: ["stdio"]
+    timeout: 30000
+    env:
+      HTM_DBURL: "postgres://localhost:5432/htm_development"
+      ...
+```
+
+**Notes:**
+- The `command` can be just the executable name if it's in your PATH
+- AIA automatically resolves command paths, so you don't need absolute paths
+- Environment variables in the `env` section are passed only to that MCP server process
+
+#### Example: Multiple MCP Servers
+
+You can configure multiple MCP servers to provide different capabilities:
+
+```yaml
+# ~/.aia/config.yml
+:mcp_servers:
+  - name: "github"
+    command: "github-mcp-server"
+    args: ["stdio"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_token_here"
+
+  - name: "htm"
+    command: "htm_mcp.rb"
+    args: ["stdio"]
+    timeout: 30000
+    env:
+      HTM_DBURL: "postgres://localhost:5432/htm_development"
+
+  - name: "filesystem"
+    command: "filesystem-mcp-server"
+    args: ["stdio", "--root", "/Users/me/projects"]
+```
+
+#### Verifying MCP Server Configuration
+
+When MCP servers are configured, AIA displays them in the startup robot:
+
+```
+       ,      ,
+       (\____/) AI Assistant (v0.9.23) is Online
+        (_oo_)   gpt-4o-mini (supports tools)
+         (O)       using ruby_llm (v1.9.0 MCP v0.6.1)
+       __||__    \) model db was last refreshed on
+     [/______\]  /    2025-06-03
+    / \__AI__/ \/      You can share my tools
+   /    /__\              MCP: github, htm
+  (\   /____\
+```
+
+Use the `//tools` directive in chat mode to see all available tools including those from MCP servers:
+
+```bash
+aia --chat
+> //tools
+
+Available Tools:
+- github_create_issue: Create a new GitHub issue
+- github_list_repos: List repositories for the authenticated user
+- htm_query: Execute a query against the HTM database
+- htm_insert: Insert a record into HTM
+...
+
+# Filter tools by name (case-insensitive)
+> //tools github
+
+Available Tools (filtered by 'github')
+- github_create_issue: Create a new GitHub issue
+- github_list_repos: List repositories for the authenticated user
+```
+
+#### Troubleshooting MCP Servers
+
+If an MCP server fails to load, AIA will display a warning:
+
+```
+WARNING: MCP server 'github' command not found: github-mcp-server
+WARNING: MCP server entry missing name or command: {...}
+ERROR: Failed to load MCP server 'htm': Connection timeout
+```
+
+**Common Issues:**
+
+| Problem | Solution |
+|---------|----------|
+| Command not found | Ensure the command is in your PATH or use absolute path |
+| Connection timeout | Increase the `timeout` value |
+| Missing environment variables | Add required env vars to the `env` section |
+| Server hangs on startup | Check that all required environment variables are set |
+
+**Debug Mode:**
+
+Enable debug mode to see detailed MCP server loading information:
+
+```bash
+aia --debug --chat
+```
+
 **Shared Tools Collection:**
 AIA can use the [shared_tools gem](https://github.com/madbomber/shared_tools) which provides a curated collection of commonly-used  tools (aka functions) via the --require option.
 

data/docs/directives-reference.md

@@ -214,11 +214,21 @@ Speak text using system text-to-speech (macOS/Linux).
 ## Utility Directives
 
 ### `//tools`
-Display available RubyLLM tools.
+Display available RubyLLM tools with optional filtering.
 
-**Syntax**: `//tools`
+**Syntax**: `//tools [filter]`
 
-**Example Output**:
+**Parameters**:
+- `filter` (optional) - Case-insensitive substring to filter tool names
+
+**Examples**:
+```markdown
+//tools           # List all available tools
+//tools file      # List tools with "file" in the name
+//tools analyzer  # List tools with "analyzer" in the name
+```
+
+**Example Output** (unfiltered):
 ```
 Available Tools
 ===============
@@ -234,6 +244,21 @@ WebScraper
     selectors and filters.
 ```
 
+**Example Output** (filtered with `//tools file`):
+```
+Available Tools (filtered by 'file')
+====================================
+
+FileReader
+----------
+    Read and analyze file contents with support for multiple formats
+    including text, JSON, YAML, and CSV files.
+```
+
+**Notes**:
+- When no tools match the filter, displays "No tools match the filter: [filter]"
+- Filtering is case-insensitive (e.g., "File", "FILE", and "file" all match)
+
 ### `//next`
 Set the next prompt to execute in a workflow.
 
@@ -509,11 +534,6 @@ SyntaxError: unexpected token
 ERROR: PUREMD_API_KEY is required in order to include a webpage
 ```
 
-**Missing Context Manager**:
-```
-Error: Context manager not available for //clear directive.
-```
-
 ### Custom Directives
 
 You can extend AIA with custom directives by creating Ruby files that define new directive methods:

data/docs/index.md

@@ -126,13 +126,13 @@ graph TD
 - **AIA::PromptHandler** - Main prompt processing orchestrator
 - **AIA::ChatProcessorService** - Interactive chat session management
 - **AIA::DirectiveProcessor** - Processes embedded directives (`//command params`)
-- **AIA::ContextManager** - Manages conversation context and history
-- **AIA::RubyLLMAdapter** - Interfaces with the ruby_llm gem for AI model communication
+- **AIA::RubyLLMAdapter** - Interfaces with the ruby_llm gem for AI model communication (manages conversation history via RubyLLM's Chat.@messages)
 - **AIA::ShellCommandExecutor** - Executes shell commands safely within prompts
 - **AIA::HistoryManager** - Manages prompt parameter history and user input
 - **AIA::UIPresenter** - Terminal output formatting and presentation
 - **AIA::Session** - Manages chat sessions and state
 - **AIA::Fzf** - Fuzzy finder integration for prompt selection
+- **AIA::Directives::Checkpoint** - Manages conversation checkpoints, restore, clear, and review operations
 
 ### External Dependencies
 

data/lib/aia/config/base.rb

@@ -140,6 +140,7 @@ module AIA
           config = tailor_the_config(config)
           load_libraries(config)
           load_tools(config)
+          load_mcp_servers(config)
 
           if config.dump_file
             dump_config(config, config.dump_file)
@@ -156,6 +157,9 @@ module AIA
           config.require_libs.each do |library|
             begin
               require(library)
+              # Check if the library provides tools that need eager loading
+              # Convert library name to module constant (e.g., 'shared_tools' -> 'SharedTools')
+              eager_load_tools_from_library(library)
             rescue => e
               STDERR.puts "Error loading library '#{library}' #{e.message}"
             exit_on_error = true
@@ -167,6 +171,23 @@ module AIA
           config
         end
 
+        # Attempt to eager load tools from a required library
+        # Libraries that use Zeitwerk need their tools eager loaded so they
+        # appear in ObjectSpace for AIA's tool discovery
+        def eager_load_tools_from_library(library)
+          # Convert library name to module constant (e.g., 'shared_tools' -> 'SharedTools')
+          module_name = library.split('/').first.split('_').map(&:capitalize).join
+
+          begin
+            mod = Object.const_get(module_name)
+            if mod.respond_to?(:load_all_tools)
+              mod.load_all_tools
+            end
+          rescue NameError
+            # Module doesn't exist with expected name, skip
+          end
+        end
+
         def load_tools(config)
           return if config.tool_paths.empty?
 
@@ -192,6 +213,64 @@ module AIA
           exit(1) if exit_on_error
         end
 
+        def load_mcp_servers(config)
+          servers = config.mcp_servers
+
+          return config if servers.nil? || (servers.respond_to?(:empty?) && servers.empty?)
+
+          servers.each do |server|
+            name    = server[:name]    || server["name"]
+            command = server[:command] || server["command"]
+            args    = server[:args]    || server["args"] || []
+            env     = server[:env]     || server["env"]  || {}
+            timeout = server[:timeout] || server["timeout"] || 8000  # default 8 seconds in ms
+
+            unless name && command
+              STDERR.puts "WARNING: MCP server entry missing name or command: #{server.inspect}"
+              next
+            end
+
+            # Resolve command path if not absolute
+            resolved_command = resolve_command_path(command)
+            unless resolved_command
+              STDERR.puts "WARNING: MCP server '#{name}' command not found: #{command}"
+              next
+            end
+
+            begin
+              RubyLLM::MCP.add_client(
+                name:            name,
+                transport_type:  :stdio,
+                request_timeout: timeout,
+                config: {
+                  command:  resolved_command,
+                  args:     args,
+                  env:      env
+                }
+              )
+            rescue => e
+              STDERR.puts "ERROR: Failed to load MCP server '#{name}': #{e.message}"
+            end
+          end
+
+          config
+        end
+
+        def resolve_command_path(command)
+          # If already absolute path, verify it exists
+          if command.start_with?('/')
+            return File.executable?(command) ? command : nil
+          end
+
+          # Search in PATH
+          ENV['PATH'].split(File::PATH_SEPARATOR).each do |dir|
+            full_path = File.join(dir, command)
+            return full_path if File.executable?(full_path)
+          end
+
+          nil
+        end
+
         # envar values are always String object so need other config
         # layers to know the prompter type for each key's value
         def envar_options(default, cli_config)

data/lib/aia/config/defaults.rb

@@ -82,6 +82,9 @@ module AIA
 
         # Ruby libraries to require for Ruby binding
         require_libs: [],
+
+        # MCP Servers (nil means not configured, set in config file)
+        mcp_servers: nil,
       }).freeze
     end
   end