aia 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07ebe0842c8ba2a8d1a24a072066564fe83954157b272b3c02ba07f86ce6e8c9
-  data.tar.gz: 8e0e9f0b7963bed6db571e0670cedc38e4c540efca48c2b0d8ffe69545c4ba48
+  metadata.gz: b583dae0c86c40fc70dc5d71e39cc6781283e93af38a5773bfcfe92fbbdb9c65
+  data.tar.gz: ed7b710bee9a484c1f25bf450a2bcfb7ed1db701a5962a9829bc7f9404c0b370
 SHA512:
-  metadata.gz: e248f19290dc0f2b0cb132c952e1d6a3e50cc3bf8435a2cfad5a8f7e342790a0bb23a958eee2c50bb993a0943f273b30df1e72be03ca29b929789f3885c27e17
-  data.tar.gz: 18985b3f3348e6ed359bd5920ef44b675976ca09c40aa6e9abb17950b9260f682df0fb16a15f673e958b0cc6f2300669e92ba90b925ec73fc0620a7577863baa
+  metadata.gz: c00641d58b7feda9cb3930561857fd203fa7f623137e4758e87193e3528106a173a0faf1e12a57fe2dd326d6506ba4e26d4d7c33c1eda90e58ee6bd3fca4d947
+  data.tar.gz: b9707f94782fc48566da722b1144a7e60d90f6a8b1507e4ccb5148cd84cccbe088b066e176893500caf052cf295cfe3c20a1c80415eb2623d42180b270ae7e52

data/.envrc

@@ -2,3 +2,10 @@ source_up
 
 export RR=`pwd`
 # PATH_add $RR/bin
+
+# see aia --help for --model option
+#   The format of a "model" is [provider/]model_name[=roll_id]
+#   where provider and roll_id are optional
+#   Use a comma to seperate the models in a multi-model setup
+#
+# export AIA_MODEL=claude-haiku-4-5,gpt-4o-mini

data/.version

@@ -1 +1 @@
-0.10.2
+0.11.0

data/CHANGELOG.md

@@ -1,4 +1,53 @@
 # Changelog
+## [0.11.0] - 2026-02-02
+
+### New Features
+- **`--list-tools` CLI Option**: List all available tools and exit
+  - Shows tools loaded via `--require` and `--tools` options
+  - Dual-mode output: plain text (word-wrapped, 3-sentence summaries) for terminal, full markdown with nested headings when STDOUT is redirected to a file or pipe
+  - Combine with `--mcp-list` to also initialize and list tools from MCP servers, grouped by source
+  - Example: `aia --require shared_tools --list-tools > tools.md`
+
+- **`--mcp-list` Filtering**: `--mcp-list` now respects `--mcp-use` and `--mcp-skip` filters
+  - When filters are active, header changes from "Configured MCP Servers" to "Active MCP Servers"
+  - Shows only the servers that would actually be connected during a session
+
+- **`--mcp-use` and `--mcp-skip` Server Selection**: Select or exclude specific MCP servers by name
+  - `--mcp-use server1,server2` - whitelist specific servers (takes precedence)
+  - `--mcp-skip server3` - blacklist specific servers
+
+- **Multi-Model Environment Variable Support**: `AIA_MODEL` now supports inline role syntax
+  - Example: `export AIA_MODEL="gpt-4o=architect,claude=security"`
+
+### Breaking Changes
+- **Removed `--adapter` CLI Option**: The LLM adapter configuration has been removed
+  - AIA now exclusively uses `ruby_llm` as its AI interface layer
+  - The `ai_client` adapter option is no longer available
+
+### Improvements
+- **CLI Refactoring**: Streamlined CLI option names and improved help text
+  - Cleaner option grouping and descriptions in `--help` output
+
+### Documentation
+- **`--list-tools` and `--mcp-list`**: Added comprehensive documentation to `docs/cli-reference.md` with examples, output format tables, and usage patterns
+- **README.md**: Added `--mcp-list` and `--list-tools` to Key Command-Line Options table
+- **MCP Integration Guide**: Updated `docs/mcp-integration.md` with current CLI syntax and examples
+- **Shared Tools Guide**: Created dedicated `docs/guides/shared-tools.md` with all 17 tools organized by category (Data & Analysis, Database, File & System Operations, Web & Network, Code Execution, Documents, Scheduling & Time, Workflow & Weather, Development & Reference)
+- **MkDocs Navigation**: Added Shared Tools guide to site navigation
+
+### Technical Changes
+- Added `list_tools` attribute to `AIA::Config` for runtime flag storage
+- Added `--list-tools` option to CLI parser in `setup_tool_options`
+- Added `handle_list_tools` to `ConfigValidator` with dual-mode output (terminal vs redirected)
+- Added `load_local_tools` with gem activation and Zeitwerk lazy-loading support for `--require` libraries
+- Added `load_mcp_tools_grouped` returning tools organized by server name
+- Added `quiet_mcp_logger` to suppress MCP connection noise during tool listing
+- Added `filter_mcp_servers` and `mcp_filter_active?` to `ConfigValidator` for `--mcp-use`/`--mcp-skip` support
+- Added `nest_markdown_headings` to properly nest markdown headings in tool descriptions under parent heading level
+- Added `first_sentences` helper for terminal-mode description truncation
+- Uses `word_wrapper` gem for terminal word wrapping
+- Removed adapter selection logic and `--adapter` CLI option
+
 ## [0.10.2] - 2025-12-25
 
 **Merry Christmas!**

data/README.md

@@ -7,15 +7,17 @@
 
 ---
 
-> ## ⚠️ BREAKING CHANGES IN v0.10.0 ⚠️
+> ## ⚠️ BREAKING CHANGES IN v0.10.* ⚠️
 >
-> **Version 0.10.0 will introduce breaking changes affecting:**
+> **Version 0.10.0 introduces breaking changes affecting:**
 >
-> - **Environment Variables** — Naming conventions for system environment variables will change
-> - **Configuration Files** — Both the content format and structure of configuration files will be updated
-> - **File Locations** — Expected locations for configuration files will change
+> - **Environment Variables** — Naming conventions now use double underscore (`__`) for nested config sections (e.g., `AIA_LLM__TEMPERATURE`, `AIA_FLAGS__DEBUG`). See [Environment Variables](https://madbomber.github.io/aia/configuration/#environment-variables) for the complete list.
 >
-> **Please review the migration guide (coming soon) before upgrading to v0.10.0.**
+> - **Configuration Files** — Configuration now uses a nested YAML structure with sections like `llm:`, `prompts:`, `output:`, `flags:`, etc. The [defaults.yml](lib/aia/config/defaults.yml) file is the single source of truth for all configuration options. See [Configuration Guide](https://madbomber.github.io/aia/configuration/) for details.
+>
+> - **File Locations** — Configuration files now follow the XDG Base Directory Specification. The default config file location is `~/.config/aia/aia.yml`. See [Installation Guide](https://madbomber.github.io/aia/installation/) for setup instructions.
+>
+> **Review the [Configuration Guide](https://madbomber.github.io/aia/configuration/) before upgrading to v0.10.0.**
 
 ---
 
@@ -268,6 +270,8 @@ aia --fuzzy
 | `--fuzzy` | Use fuzzy search for prompts | `aia --fuzzy` |
 | `--tokens` | Display token usage in chat mode | `aia --chat --tokens` |
 | `--cost` | Include cost calculations with token usage | `aia --chat --cost` |
+| `--mcp-list` | List configured MCP servers and exit | `aia --mcp-list` |
+| `--list-tools` | List available tools and exit | `aia --require shared_tools --list-tools` |
 | `--help` | Show complete help | `aia --help` |
 
 ### Directory Structure
@@ -380,6 +384,8 @@ Your prompt content here...
 | tool_paths | --tools | [] | AIA_TOOLS__PATHS |
 | allowed_tools | --at, --allowed-tools | nil | AIA_TOOLS__ALLOWED |
 | rejected_tools | --rt, --rejected-tools | nil | AIA_TOOLS__REJECTED |
+| mcp_use | --mu, --mcp-use | ~ | AIA_MCP_USE |
+| mcp_skip | --ms, --mcp-skip | ~ | AIA_MCP_SKIP |
 | top_p | --top-p | 1.0 | AIA_LLM__TOP_P |
 | transcription_model | --tm, --transcription-model | whisper-1 | AIA_TRANSCRIPTION__MODEL |
 | verbose | -v, --verbose | false | AIA_FLAGS__VERBOSE |

data/docs/cli-reference.md

@@ -66,6 +66,102 @@ aia --chat --cost --model gpt-4,claude-3-sonnet
 
 **Note**: `--cost` implies `--tokens`, so you don't need to specify both.
 
+### `--mcp FILE`
+Load an MCP (Model Context Protocol) server from a JSON configuration file. MCP servers provide additional tools and context to AI models. Multiple `--mcp` options can be used to load multiple servers.
+
+```bash
+# Load a single MCP server
+aia --mcp ~/.config/aia/mcp/github.json my_prompt
+
+# Load multiple MCP servers
+aia --mcp github.json --mcp filesystem.json my_prompt
+
+# Combine with chat mode
+aia --chat --mcp ~/mcp-servers/memory.json
+```
+
+**JSON file format**:
+```json
+{
+  "name": "github",
+  "command": "github-mcp-server",
+  "args": ["stdio"],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
+  },
+  "timeout": 8000
+}
+```
+
+### `--no-mcp`
+Disable all MCP server processing, including servers defined in the configuration file.
+
+```bash
+# Disable MCP server processing
+aia --no-mcp my_prompt
+```
+
+**Use cases**:
+- Use `--no-mcp` when you want faster responses without MCP tool overhead
+- Use `--no-mcp` to temporarily bypass MCP servers configured in your config file
+
+### `--mcp-list`
+List configured MCP servers and exit. Shows the server name and command for each server. Useful for verifying which servers are loaded from config files and `--mcp` options.
+
+When combined with `--mcp-use` or `--mcp-skip`, only the servers that pass the filter are shown. The header changes from "Configured" to "Active" to reflect this.
+
+When combined with `--list-tools`, MCP servers are started and their tools are included in the tool listing (see `--list-tools`).
+
+```bash
+# List all servers from config file
+aia --mcp-list
+
+# List servers loaded from specific MCP JSON files
+aia --mcp github.json --mcp filesystem.json --mcp-list
+
+# List only the servers that would be active after filtering
+aia --mcp-list --mcp-use github,filesystem
+
+# List all configured servers except those skipped
+aia --mcp-list --mcp-skip playwright
+
+# Combine with --list-tools to show MCP tools grouped by server
+aia --mcp-list --list-tools
+aia --mcp-list --list-tools --mcp-use redis
+```
+
+### `--mu`, `--mcp-use NAMES`
+Only connect to the named MCP servers (whitelist). Server names are comma-separated and must match the `name` field in the server configuration.
+
+```bash
+# Only use the github server
+aia --mcp-use github --chat
+
+# Only use github and filesystem servers
+aia --mcp-use github,filesystem --chat
+
+# Can be specified multiple times
+aia --mu github --mu filesystem --chat
+```
+
+**Precedence**: `--no-mcp` overrides `--mcp-use`. If both `--mcp-use` and `--mcp-skip` are specified, `--mcp-use` takes precedence.
+
+### `--ms`, `--mcp-skip NAMES`
+Skip the named MCP servers (blacklist). All other configured servers will still be connected.
+
+```bash
+# Skip the playwright server
+aia --mcp-skip playwright --chat
+
+# Skip multiple servers
+aia --mcp-skip playwright,filesystem --chat
+
+# Can be specified multiple times
+aia --ms playwright --ms filesystem --chat
+```
+
+**Precedence**: `--no-mcp` overrides `--mcp-skip`. If `--mcp-use` is also specified, `--mcp-skip` is ignored.
+
 ## Adapter Options
 
 ### `--adapter ADAPTER`
@@ -483,6 +579,80 @@ aia --rejected-tools "file_writer,system_command" my_prompt
 aia --rt "network_access" secure_prompt
 ```
 
+### `--list-tools`
+List available tools and exit. Loads tools from `--require` and `--tools` options, then displays each tool's name and description.
+
+When combined with `--mcp-list`, MCP servers are also started and their tools are included in the output, grouped by server.
+
+**Output format depends on where stdout is directed:**
+
+| Output | Format | Descriptions |
+|--------|--------|-------------|
+| Terminal | Plain text, word-wrapped | First 3 sentences |
+| File/pipe | Markdown with headings | Full description |
+
+The markdown output uses `#` for the title, `##` for source sections (Local Tools, MCP server groups), and `###` for individual tool names. Any markdown headings within a tool's description are automatically adjusted to nest under the tool's heading level.
+
+```bash
+# List local tools loaded via --require
+aia --require shared_tools --list-tools
+
+# List local tools loaded from a file path
+aia --tools ./my_tools/ --list-tools
+
+# Combine --require and --tools
+aia --require shared_tools --tools ./extras/ --list-tools
+
+# Include MCP server tools (requires --mcp-list)
+aia --require shared_tools --mcp-list --list-tools
+
+# Include only specific MCP servers
+aia --require shared_tools --mcp-list --mcp-use redis --list-tools
+
+# Redirect to a markdown file
+aia --require shared_tools --mcp-list --list-tools > tools.md
+
+# Pipe to a markdown renderer
+aia --require shared_tools --list-tools | glow -
+```
+
+**Example terminal output:**
+```
+Local Tools:
+
+  calculator
+    Perform advanced mathematical calculations with comprehensive
+    error handling and validation. This tool supports basic arithmetic
+    operations, parentheses, and common mathematical functions.
+
+  weather_tool
+    Retrieve comprehensive current weather information for any city
+    worldwide using the OpenWeatherMap API. This tool provides real-time
+    weather data including temperature, atmospheric conditions, humidity,
+    and wind information.
+```
+
+**Example markdown output (when redirected):**
+```markdown
+# Available Tools
+
+> 20 tools from 2 sources
+
+## Local Tools (15)
+
+### `calculator`
+
+Perform advanced mathematical calculations with comprehensive error
+handling and validation. This tool supports basic arithmetic operations,
+parentheses, and common mathematical functions. ...full description...
+
+## MCP: redis (5)
+
+### `set`
+
+Set a Redis string value with an optional expiration time. ...full description...
+```
+
 ## Utility Options
 
 ### Log Level Options
@@ -675,28 +845,48 @@ Many CLI options have corresponding environment variables with the `AIA_` prefix
 Use double underscore (`__`) for nested configuration sections:
 
 ```bash
-# Model configuration (top-level)
+# Model configuration (top-level, supports MODEL=ROLE syntax)
 export AIA_MODEL="gpt-4"
-
-# Model with inline role syntax
 export AIA_MODEL="gpt-4o=architect"
-
-# Multiple models with roles
 export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"
 
 # LLM settings (nested under llm:)
+export AIA_LLM__ADAPTER="ruby_llm"
 export AIA_LLM__TEMPERATURE="0.8"
+export AIA_LLM__MAX_TOKENS="2048"
 
 # Prompts settings (nested under prompts:)
 export AIA_PROMPTS__DIR="/custom/prompts"
+export AIA_PROMPTS__ROLES_PREFIX="roles"
+
+# Output settings (nested under output:)
+export AIA_OUTPUT__FILE="./output.md"
+export AIA_OUTPUT__APPEND="true"
+export AIA_OUTPUT__HISTORY_FILE="~/.prompts/_prompts.log"
+
+# Audio settings (nested under audio:)
+export AIA_AUDIO__VOICE="alloy"
+export AIA_AUDIO__SPEECH_MODEL="tts-1"
+
+# Image settings (nested under image:)
+export AIA_IMAGE__SIZE="1024x1024"
+export AIA_IMAGE__QUALITY="hd"
 
 # Flags (nested under flags:)
+export AIA_FLAGS__CHAT="true"
 export AIA_FLAGS__VERBOSE="true"
 export AIA_FLAGS__DEBUG="false"
-export AIA_FLAGS__CHAT="true"
+export AIA_FLAGS__TOKENS="true"
+export AIA_FLAGS__COST="true"
+export AIA_FLAGS__NO_MCP="false"
+export AIA_FLAGS__CONSENSUS="true"
 
-# Output settings (nested under output:)
-export AIA_OUTPUT__FILE="./output.md"
+# Registry settings (nested under registry:)
+export AIA_REGISTRY__REFRESH="7"
+
+# Paths settings (nested under paths:)
+export AIA_PATHS__AIA_DIR="~/.config/aia"
+export AIA_PATHS__CONFIG_FILE="~/.config/aia/aia.yml"
 ```
 
 **Note**: The `AIA_MODEL` environment variable supports the same inline `MODEL=ROLE` syntax as the `--model` CLI option.