aia 2.0.0.0.pre.beta2 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (227) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +152 -223
  3. data/README.md +41 -18
  4. data/bin/aia +8 -3
  5. data/lib/aia/aia_completion.bash +2 -3
  6. data/lib/aia/aia_completion.fish +6 -5
  7. data/lib/aia/aia_completion.zsh +2 -3
  8. data/lib/aia/chat_loop.rb +16 -14
  9. data/lib/aia/config/cli_parser.rb +123 -91
  10. data/lib/aia/config/defaults.yml +18 -40
  11. data/lib/aia/config/mcp_parser.rb +30 -36
  12. data/lib/aia/config/model_spec.rb +8 -14
  13. data/lib/aia/config/validator.rb +102 -103
  14. data/lib/aia/config/value_caster.rb +76 -0
  15. data/lib/aia/config.rb +70 -53
  16. data/lib/aia/crew.rb +29 -19
  17. data/lib/aia/debate_handler.rb +27 -10
  18. data/lib/aia/directives/configuration_directives.rb +55 -14
  19. data/lib/aia/directives/context_directives.rb +24 -12
  20. data/lib/aia/directives/execution_directives.rb +18 -23
  21. data/lib/aia/directives/model_directives.rb +41 -104
  22. data/lib/aia/directives/utility_directives.rb +16 -17
  23. data/lib/aia/directives/web_and_file_directives.rb +21 -14
  24. data/lib/aia/fact_asserter.rb +3 -3
  25. data/lib/aia/history_transfer.rb +64 -24
  26. data/lib/aia/logger.rb +14 -46
  27. data/lib/aia/mcp_config_normalizer.rb +27 -14
  28. data/lib/aia/mcp_connection_manager.rb +181 -184
  29. data/lib/aia/mcp_discovery.rb +43 -15
  30. data/lib/aia/mcp_grouper.rb +2 -1
  31. data/lib/aia/mcp_server_config.rb +20 -2
  32. data/lib/aia/mcp_utility.rb +24 -19
  33. data/lib/aia/mention_router.rb +15 -2
  34. data/lib/aia/modality_query.rb +36 -0
  35. data/lib/aia/model_alias_registry.rb +11 -11
  36. data/lib/aia/model_registry.rb +75 -0
  37. data/lib/aia/network_builder.rb +8 -7
  38. data/lib/aia/patches/mcp_stdio_stderr.rb +102 -0
  39. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  40. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  41. data/lib/aia/pipeline_orchestrator.rb +71 -38
  42. data/lib/aia/prompt_decomposer.rb +1 -1
  43. data/lib/aia/prompt_handler.rb +56 -29
  44. data/lib/aia/provider_registry.rb +105 -0
  45. data/lib/aia/robot_builder.rb +1 -1
  46. data/lib/aia/robot_factory.rb +67 -63
  47. data/lib/aia/robot_sync.rb +79 -0
  48. data/lib/aia/role_catalog.rb +89 -0
  49. data/lib/aia/session.rb +25 -11
  50. data/lib/aia/skill_utils.rb +60 -19
  51. data/lib/aia/spawn_handler.rb +16 -4
  52. data/lib/aia/spawn_spec_parser.rb +6 -7
  53. data/lib/aia/special_mode_handler.rb +28 -25
  54. data/lib/aia/speech.rb +70 -34
  55. data/lib/aia/startup_coordinator.rb +17 -92
  56. data/lib/aia/streaming_runner.rb +10 -2
  57. data/lib/aia/system_prompt_assembler.rb +12 -11
  58. data/lib/aia/task_board.rb +60 -0
  59. data/lib/aia/tool_approver.rb +205 -0
  60. data/lib/aia/tool_filter.rb +1 -10
  61. data/lib/aia/tool_filter_strategy.rb +12 -1
  62. data/lib/aia/tool_introspection.rb +9 -1
  63. data/lib/aia/tool_loader.rb +67 -33
  64. data/lib/aia/tool_utility.rb +6 -5
  65. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  66. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  67. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  68. data/lib/aia/tools/task_board_tool.rb +16 -16
  69. data/lib/aia/trakflow_bridge.rb +14 -8
  70. data/lib/aia/turn_state.rb +31 -8
  71. data/lib/aia/ui_presenter.rb +16 -0
  72. data/lib/aia/utility.rb +6 -24
  73. data/lib/aia/variable_input_collector.rb +0 -3
  74. data/lib/aia/verification_network.rb +9 -10
  75. data/lib/aia/version.rb +1 -9
  76. data/lib/aia.rb +34 -8
  77. metadata +20 -161
  78. data/.better-commits.json +0 -150
  79. data/.config/tocer/configuration.yml +0 -6
  80. data/.envrc +0 -19
  81. data/.loki +0 -11
  82. data/.reek.yml +0 -160
  83. data/.rubocop.yml +0 -116
  84. data/.rubocop_strict.yml +0 -15
  85. data/.version +0 -1
  86. data/COMMITS.md +0 -196
  87. data/IMPLEMENTATION_PLAN.md +0 -506
  88. data/Rakefile +0 -47
  89. data/_typos.toml +0 -10
  90. data/aia.gemspec +0 -92
  91. data/architecture_review.md +0 -314
  92. data/config/aia.yml +0 -13
  93. data/docs/AGENTS.md +0 -40
  94. data/docs/advanced-prompting.md +0 -814
  95. data/docs/assets/images/aia.png +0 -0
  96. data/docs/cli-reference.md +0 -1241
  97. data/docs/configuration.md +0 -747
  98. data/docs/contributing.md +0 -386
  99. data/docs/directives-reference.md +0 -1145
  100. data/docs/examples/index.md +0 -277
  101. data/docs/examples/mcp/index.md +0 -475
  102. data/docs/examples/prompts/analysis/index.md +0 -78
  103. data/docs/examples/prompts/automation/index.md +0 -109
  104. data/docs/examples/prompts/development/index.md +0 -125
  105. data/docs/examples/prompts/index.md +0 -333
  106. data/docs/examples/prompts/learning/index.md +0 -127
  107. data/docs/examples/prompts/writing/index.md +0 -62
  108. data/docs/examples/tools/index.md +0 -282
  109. data/docs/faq.md +0 -578
  110. data/docs/guides/available-models.md +0 -366
  111. data/docs/guides/basic-usage.md +0 -478
  112. data/docs/guides/chat.md +0 -680
  113. data/docs/guides/crew.md +0 -239
  114. data/docs/guides/executable-prompts.md +0 -331
  115. data/docs/guides/first-prompt.md +0 -454
  116. data/docs/guides/getting-started.md +0 -455
  117. data/docs/guides/image-generation.md +0 -507
  118. data/docs/guides/index.md +0 -48
  119. data/docs/guides/local-models.md +0 -306
  120. data/docs/guides/migrate-prompts.md +0 -335
  121. data/docs/guides/models.md +0 -1017
  122. data/docs/guides/shared-tools.md +0 -254
  123. data/docs/guides/tools.md +0 -831
  124. data/docs/index.md +0 -259
  125. data/docs/installation.md +0 -274
  126. data/docs/mcp-integration.md +0 -603
  127. data/docs/prompt_management.md +0 -665
  128. data/docs/security.md +0 -674
  129. data/docs/special_projects_guide.md +0 -386
  130. data/docs/tools-and-mcp-examples.md +0 -1211
  131. data/docs/workflows-and-pipelines.md +0 -636
  132. data/examples/.gitignore +0 -2
  133. data/examples/00_setup_aia.sh +0 -111
  134. data/examples/01_basic_usage.sh +0 -23
  135. data/examples/02_frontmatter.sh +0 -33
  136. data/examples/03_shell_integration.sh +0 -55
  137. data/examples/04_erb_templating.sh +0 -56
  138. data/examples/05_shell_then_erb.sh +0 -38
  139. data/examples/06_prompt_chaining.sh +0 -59
  140. data/examples/07_pipeline.sh +0 -46
  141. data/examples/08_context_files.sh +0 -43
  142. data/examples/09_roles.sh +0 -67
  143. data/examples/10_stdin_piping.sh +0 -49
  144. data/examples/11_multi_model.sh +0 -65
  145. data/examples/12_token_usage.sh +0 -52
  146. data/examples/13_cost_tracking.sh +0 -68
  147. data/examples/14_output_file.sh +0 -91
  148. data/examples/15_parameters.sh +0 -68
  149. data/examples/16_directives.sh +0 -113
  150. data/examples/17_require_and_conditionals.sh +0 -68
  151. data/examples/18_tools.sh +0 -61
  152. data/examples/19_local_tools.sh +0 -34
  153. data/examples/20_mcp_servers.sh +0 -102
  154. data/examples/21_executable_prompts.sh +0 -78
  155. data/examples/22_chat_mode.sh +0 -217
  156. data/examples/23_verify.sh +0 -139
  157. data/examples/24_decompose.sh +0 -139
  158. data/examples/25_spawn.sh +0 -139
  159. data/examples/26_debate.sh +0 -97
  160. data/examples/27_mention_routing.sh +0 -157
  161. data/examples/28_model_switching.sh +0 -106
  162. data/examples/29_agent_harness.sh +0 -177
  163. data/examples/README.md +0 -321
  164. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  165. data/examples/aia_config.yml +0 -22
  166. data/examples/aia_config_orchestrator.yml +0 -45
  167. data/examples/aia_config_with_mcp.yml +0 -21
  168. data/examples/common.sh +0 -39
  169. data/examples/context/project_goals.md +0 -6
  170. data/examples/context/tech_stack.md +0 -7
  171. data/examples/directives/timestamp_directive.rb +0 -22
  172. data/examples/mcp/filesystem.json +0 -9
  173. data/examples/prompts_dir/analyze.md +0 -2
  174. data/examples/prompts_dir/brainstorm.md +0 -2
  175. data/examples/prompts_dir/conditional.md +0 -17
  176. data/examples/prompts_dir/creative.md +0 -4
  177. data/examples/prompts_dir/erbinfo.md +0 -5
  178. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  179. data/examples/prompts_dir/evaluate.md +0 -2
  180. data/examples/prompts_dir/explain_joke.md +0 -1
  181. data/examples/prompts_dir/explain_recursion.md +0 -1
  182. data/examples/prompts_dir/fun_fact +0 -3
  183. data/examples/prompts_dir/greeting.md +0 -8
  184. data/examples/prompts_dir/greeting_required.md +0 -7
  185. data/examples/prompts_dir/hello.md +0 -1
  186. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  187. data/examples/prompts_dir/limerick.md +0 -1
  188. data/examples/prompts_dir/list_with_mcp.md +0 -3
  189. data/examples/prompts_dir/pick_best.md +0 -2
  190. data/examples/prompts_dir/project_summary +0 -12
  191. data/examples/prompts_dir/quiz_with_include.md +0 -6
  192. data/examples/prompts_dir/require_demo.md +0 -5
  193. data/examples/prompts_dir/roles/formal.md +0 -3
  194. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  195. data/examples/prompts_dir/roles/pirate.md +0 -3
  196. data/examples/prompts_dir/shell_then_erb.md +0 -6
  197. data/examples/prompts_dir/sort_compare.md +0 -2
  198. data/examples/prompts_dir/summarize_context.md +0 -2
  199. data/examples/prompts_dir/sysinfo.md +0 -5
  200. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  201. data/examples/prompts_dir/tagline.md +0 -1
  202. data/examples/prompts_dir/tell_joke.md +0 -1
  203. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  204. data/examples/prompts_dir/use_local_tool.md +0 -8
  205. data/examples/prompts_dir/use_tools.md +0 -8
  206. data/examples/prompts_dir/weather.md +0 -2
  207. data/examples/prompts_dir/whats_new.md +0 -2
  208. data/examples/prompts_dir/with_timestamp.md +0 -5
  209. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  210. data/examples/rules/01_classify_ruby.rb +0 -16
  211. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  212. data/examples/rules/03_gate_prompt_length.rb +0 -19
  213. data/examples/rules/04_tool_selection.rb +0 -41
  214. data/examples/rules/README.md +0 -30
  215. data/examples/run_all.sh +0 -294
  216. data/examples/tools/word_count_tool.rb +0 -30
  217. data/lib/AGENTS.md +0 -57
  218. data/lib/aia/model_switch_handler.rb +0 -100
  219. data/mcp_servers/README.md +0 -110
  220. data/mcp_servers/apple-mcp.json +0 -8
  221. data/mcp_servers/filesystem.json +0 -9
  222. data/mcp_servers/mcp_server_chart.json +0 -11
  223. data/mcp_servers/playwright_one.json +0 -8
  224. data/mcp_servers/playwright_server_definition.json +0 -9
  225. data/mcp_servers/playwright_two.json +0 -8
  226. data/mcp_servers/tavily_mcp_server.json +0 -8
  227. data/mkdocs.yml +0 -169
@@ -1,603 +0,0 @@
1
- <!-- Tocer[start]: Auto-generated, don't remove. -->
2
-
3
- ## Table of Contents
4
-
5
- - [MCP Integration](#mcp-integration)
6
- - [Understanding MCP](#understanding-mcp)
7
- - [What is MCP?](#what-is-mcp)
8
- - [MCP vs RubyLLM Tools](#mcp-vs-rubyllm-tools)
9
- - [Enabling MCP Support](#enabling-mcp-support)
10
- - [Configuration](#configuration)
11
- - [Command Line Usage](#command-line-usage)
12
- - [Available MCP Clients](#available-mcp-clients)
13
- - [GitHub Integration](#github-integration)
14
- - [File System Access](#file-system-access)
15
- - [Database Integration](#database-integration)
16
- - [Using MCP Clients in Prompts](#using-mcp-clients-in-prompts)
17
- - [GitHub Analysis](#github-analysis)
18
- - [File System Operations](#file-system-operations)
19
- - [Database Schema Analysis](#database-schema-analysis)
20
- - [Advanced MCP Integration](#advanced-mcp-integration)
21
- - [Multi-Client Workflows](#multi-client-workflows)
22
- - [Conditional MCP Usage](#conditional-mcp-usage)
23
- - [Custom MCP Client Development](#custom-mcp-client-development)
24
- - [Basic MCP Server Structure](#basic-mcp-server-structure)
25
- - [Node.js MCP Server](#nodejs-mcp-server)
26
- - [MCP Security and Best Practices](#mcp-security-and-best-practices)
27
- - [Access Control](#access-control)
28
- - [Server Configuration Security](#server-configuration-security)
29
- - [Parallel Connections](#parallel-connections)
30
- - [Troubleshooting MCP](#troubleshooting-mcp)
31
- - [Common Issues](#common-issues)
32
- - [Client Connection Failures](#client-connection-failures)
33
- - [Protocol Errors](#protocol-errors)
34
- - [MCP Examples Repository](#mcp-examples-repository)
35
- - [GitHub Repository Analysis](#github-repository-analysis)
36
- - [File System Audit](#file-system-audit)
37
- - [Related Documentation](#related-documentation)
38
-
39
- <!-- Tocer[finish]: Auto-generated, don't remove. -->
40
-
41
- # MCP Integration
42
-
43
- AIA supports Model Context Protocol (MCP) clients, enabling AI models to interact with external services, databases, and applications through standardized interfaces.
44
-
45
- ## Understanding MCP
46
-
47
- ### What is MCP?
48
- Model Context Protocol (MCP) is a standardized way for AI models to interact with external resources:
49
- - **Database Access**: Query and manipulate databases
50
- - **File System Operations**: Safe, sandboxed file operations
51
- - **API Integrations**: Structured access to web APIs
52
- - **Tool Extensions**: Custom functionality through protocol
53
- - **Service Integration**: Connect to external services and platforms
54
-
55
- ### MCP vs RubyLLM Tools
56
- | Feature | RubyLLM Tools | MCP Clients |
57
- |---------|---------------|-------------|
58
- | **Language** | Ruby only | Any language |
59
- | **Security** | Ruby sandbox | Protocol-level security |
60
- | **Distribution** | Ruby gems/files | Separate processes |
61
- | **Standardization** | AIA-specific | Industry standard |
62
- | **Performance** | Direct calls | IPC overhead |
63
-
64
- ## Enabling MCP Support
65
-
66
- ### Configuration
67
- ```yaml
68
- # ~/.config/aia/aia.yml
69
- mcp_servers:
70
- - name: github
71
- command: /path/to/github-mcp-server
72
- args: []
73
- env:
74
- GITHUB_TOKEN: "${GITHUB_TOKEN}"
75
- timeout: 8000
76
-
77
- - name: filesystem
78
- command: mcp-server-filesystem
79
- args:
80
- - /allowed/path1
81
- - /allowed/path2
82
-
83
- - name: database
84
- command: /path/to/db-mcp-server.py
85
- env:
86
- DATABASE_URL: "${DATABASE_URL}"
87
- ```
88
-
89
- ### Command Line Usage
90
- ```bash
91
- # Load MCP servers from JSON config files
92
- aia --mcp github.json --mcp filesystem.json my_prompt
93
-
94
- # List configured MCP servers
95
- aia --mcp-list
96
-
97
- # Use only specific MCP servers
98
- aia --mcp-use github,filesystem --chat
99
-
100
- # Skip specific MCP servers
101
- aia --mcp-skip playwright --chat
102
-
103
- # List all tools including MCP tools
104
- aia --mcp-list --list-tools
105
-
106
- # List tools from a specific MCP server
107
- aia --mcp-list --mcp-use github --list-tools
108
-
109
- # Debug MCP communication
110
- aia --debug --mcp github.json github_analysis
111
- ```
112
-
113
- ## Available MCP Clients
114
-
115
- ### GitHub Integration
116
- Connect to GitHub repositories and operations:
117
-
118
- ```bash
119
- # Install GitHub MCP server
120
- npm install -g @anthropic-ai/mcp-server-github
121
-
122
- # Configure in ~/.config/aia/aia.yml
123
- mcp_servers:
124
- - name: github
125
- command: npx
126
- args:
127
- - "@anthropic-ai/mcp-server-github"
128
- env:
129
- GITHUB_TOKEN: "${GITHUB_TOKEN}"
130
- ```
131
-
132
- **Capabilities**:
133
- - Repository analysis
134
- - Issue management
135
- - Pull request operations
136
- - File content access
137
- - Commit history analysis
138
-
139
- ### File System Access
140
- Safe file system operations with sandboxing:
141
-
142
- ```bash
143
- # Install filesystem MCP server
144
- npm install -g @anthropic-ai/mcp-server-filesystem
145
-
146
- # Configure in ~/.config/aia/aia.yml
147
- mcp_servers:
148
- - name: filesystem
149
- command: npx
150
- args:
151
- - "@anthropic-ai/mcp-server-filesystem"
152
- - /home/user/projects
153
- - /tmp/aia-workspace
154
- ```
155
-
156
- **Capabilities**:
157
- - Read files and directories
158
- - Write files (in allowed paths)
159
- - File metadata access
160
- - Directory traversal
161
- - Search operations
162
-
163
- ### Database Integration
164
- Connect to SQL databases:
165
-
166
- ```python
167
- # Example database MCP server (Python)
168
- #!/usr/bin/env python3
169
- import asyncio
170
- import os
171
- from mcp.server import Server
172
- from mcp.types import Resource, Tool
173
- import sqlite3
174
-
175
- server = Server("database-mcp")
176
-
177
- @server.list_tools()
178
- async def list_tools():
179
- return [
180
- Tool(name="query", description="Execute SQL query"),
181
- Tool(name="describe", description="Describe table structure")
182
- ]
183
-
184
- @server.call_tool()
185
- async def call_tool(name: str, arguments: dict):
186
- if name == "query":
187
- return execute_query(arguments["sql"])
188
- elif name == "describe":
189
- return describe_table(arguments["table"])
190
- ```
191
-
192
- ## Using MCP Clients in Prompts
193
-
194
- ### GitHub Analysis
195
- ```markdown
196
- # ~/.prompts/github_analysis.md
197
- # Requires MCP server "github" configured in ~/.config/aia/aia.yml
198
-
199
- # GitHub Repository Analysis
200
-
201
- Repository: <%= repo_url %>
202
-
203
- ## Repository Overview
204
- Use the GitHub MCP client to analyze:
205
- 1. Repository structure and organization
206
- 2. Recent commit activity and patterns
207
- 3. Open issues and their categories
208
- 4. Pull request status and reviews
209
- 5. Contributors and contribution patterns
210
-
211
- ## Code Quality Assessment
212
- Examine key files:
213
- - README and documentation quality
214
- - Code organization and structure
215
- - Testing coverage and practices
216
- - Dependency management
217
-
218
- Provide comprehensive analysis with actionable recommendations.
219
- ```
220
-
221
- ### File System Operations
222
- ```markdown
223
- # ~/.prompts/project_analysis.md
224
- # Requires MCP server "filesystem" configured in ~/.config/aia/aia.yml
225
-
226
- # Project Structure Analysis
227
-
228
- Project directory: <%= project_path %>
229
-
230
- ## Structure Analysis
231
- Use the filesystem MCP client to:
232
- 1. Map directory structure and organization
233
- 2. Identify configuration files and their purposes
234
- 3. Analyze code distribution across languages
235
- 4. Find documentation and README files
236
- 5. Locate test files and coverage
237
-
238
- ## Code Organization Review
239
- Examine:
240
- - Logical grouping of related files
241
- - Naming conventions consistency
242
- - Dependency organization
243
- - Build and deployment configurations
244
-
245
- Generate detailed project assessment with improvement suggestions.
246
- ```
247
-
248
- ### Database Schema Analysis
249
- ```markdown
250
- # ~/.prompts/database_analysis.md
251
- # Requires MCP server "database" configured in ~/.config/aia/aia.yml
252
-
253
- # Database Schema Analysis
254
-
255
- Database: <%= database_name %>
256
-
257
- ## Schema Overview
258
- Use the database MCP client to:
259
- 1. List all tables and their relationships
260
- 2. Analyze table structures and data types
261
- 3. Identify primary keys and foreign key relationships
262
- 4. Examine indexes and constraints
263
- 5. Review stored procedures and views
264
-
265
- ## Data Quality Assessment
266
- Check for:
267
- - Naming convention consistency
268
- - Normalization level appropriateness
269
- - Index optimization opportunities
270
- - Data integrity constraints
271
- - Performance bottlenecks
272
-
273
- Provide recommendations for schema improvements and optimizations.
274
- ```
275
-
276
- ## Advanced MCP Integration
277
-
278
- ### Multi-Client Workflows
279
- ```markdown
280
- # ~/.prompts/full_project_audit.md
281
- # Requires MCP server "github" configured in ~/.config/aia/aia.yml,filesystem,database
282
-
283
- # Comprehensive Project Audit
284
-
285
- Project: <%= project_name %>
286
- Repository: <%= repo_url %>
287
- Database: <%= db_name %>
288
-
289
- ## Phase 1: Code Repository Analysis
290
- Using GitHub MCP client:
291
- - Repository health and activity
292
- - Code quality and organization
293
- - Issue and PR management
294
- - Developer productivity metrics
295
-
296
- ## Phase 2: File System Structure
297
- Using filesystem MCP client:
298
- - Local project organization
299
- - Configuration management
300
- - Documentation completeness
301
- - Build and deployment setup
302
-
303
- ## Phase 3: Database Architecture
304
- Using database MCP client:
305
- - Schema design and integrity
306
- - Performance optimization
307
- - Data governance compliance
308
- - Migration and versioning
309
-
310
- ## Integration Assessment
311
- Cross-analyze findings to identify:
312
- - Consistency across repository and local files
313
- - Database schema alignment with application code
314
- - Documentation accuracy and completeness
315
- - Deployment and configuration coherence
316
-
317
- Generate comprehensive audit report with prioritized recommendations.
318
- ```
319
-
320
- ### Conditional MCP Usage
321
-
322
- Use `--mcp-use` on the command line to select which MCP servers to activate:
323
-
324
- ```bash
325
- # Use only specific MCP servers for a prompt
326
- aia --mcp-use github,filesystem my_prompt
327
-
328
- # Skip specific servers
329
- aia --mcp-skip database my_prompt
330
- ```
331
-
332
- Within prompts, you can document which MCP servers are expected:
333
-
334
- ```markdown
335
- # ~/.prompts/adaptive_analysis.md
336
- # Requires MCP servers: github, filesystem, database
337
- # Run with: aia --mcp-use github,filesystem,database adaptive_analysis
338
-
339
- # Adaptive Project Analysis
340
-
341
- Project type: <%= project_type %>
342
-
343
- Perform comprehensive analysis using available MCP clients to provide insights specific to this project type.
344
- ```
345
-
346
- ## Custom MCP Client Development
347
-
348
- ### Basic MCP Server Structure
349
- ```python
350
- # custom_mcp_server.py
351
- import asyncio
352
- from mcp.server import Server
353
- from mcp.types import Resource, Tool, TextContent
354
-
355
- server = Server("custom-service")
356
-
357
- @server.list_resources()
358
- async def list_resources():
359
- return [
360
- Resource(
361
- uri="service://data/users",
362
- name="User Data",
363
- description="Access to user information"
364
- )
365
- ]
366
-
367
- @server.list_tools()
368
- async def list_tools():
369
- return [
370
- Tool(
371
- name="get_user",
372
- description="Retrieve user information by ID",
373
- inputSchema={
374
- "type": "object",
375
- "properties": {
376
- "user_id": {"type": "string"}
377
- },
378
- "required": ["user_id"]
379
- }
380
- )
381
- ]
382
-
383
- @server.call_tool()
384
- async def call_tool(name: str, arguments: dict):
385
- if name == "get_user":
386
- user_data = fetch_user(arguments["user_id"])
387
- return TextContent(type="text", text=str(user_data))
388
-
389
- def fetch_user(user_id):
390
- # Custom logic to fetch user data
391
- return {"id": user_id, "name": "Example User"}
392
-
393
- if __name__ == "__main__":
394
- asyncio.run(server.run())
395
- ```
396
-
397
- ### Node.js MCP Server
398
- ```javascript
399
- // custom-mcp-server.js
400
- const { Server } = require('@anthropic-ai/mcp-sdk/server');
401
-
402
- const server = new Server('custom-service', '1.0.0');
403
-
404
- server.setRequestHandler('tools/list', async () => {
405
- return {
406
- tools: [
407
- {
408
- name: 'process_data',
409
- description: 'Process custom data',
410
- inputSchema: {
411
- type: 'object',
412
- properties: {
413
- data: { type: 'string' },
414
- format: { type: 'string', enum: ['json', 'csv', 'xml'] }
415
- },
416
- required: ['data']
417
- }
418
- }
419
- ]
420
- };
421
- });
422
-
423
- server.setRequestHandler('tools/call', async (request) => {
424
- const { name, arguments: args } = request.params;
425
-
426
- if (name === 'process_data') {
427
- const result = processData(args.data, args.format || 'json');
428
- return { content: [{ type: 'text', text: result }] };
429
- }
430
-
431
- throw new Error(`Unknown tool: ${name}`);
432
- });
433
-
434
- function processData(data, format) {
435
- // Custom processing logic
436
- return `Processed data in ${format} format: ${data}`;
437
- }
438
-
439
- server.connect();
440
- ```
441
-
442
- ## MCP Security and Best Practices
443
-
444
- ### Access Control
445
-
446
- Control which MCP servers are available using CLI flags:
447
-
448
- ```bash
449
- # Allow only specific MCP servers
450
- aia --mcp-use github,filesystem --chat
451
-
452
- # Skip specific MCP servers
453
- aia --mcp-skip database --chat
454
-
455
- # Use --allowed-tools and --rejected-tools to filter MCP tools
456
- aia --mcp-use github --allowed-tools "github_*" --chat
457
- ```
458
-
459
- ### Server Configuration Security
460
-
461
- Limit what each MCP server can access through its own configuration:
462
-
463
- ```yaml
464
- # ~/.config/aia/aia.yml
465
- mcp_servers:
466
- - name: filesystem
467
- command: mcp-server-filesystem
468
- args:
469
- - /safe/path/only # Restrict to specific directories
470
-
471
- - name: database
472
- command: database-mcp-server
473
- env:
474
- DB_READ_ONLY: "true" # Use server-level env vars for restrictions
475
- DATABASE_URL: "${DATABASE_URL}"
476
- timeout: 8000
477
- ```
478
-
479
- ### Parallel Connections
480
-
481
- When multiple MCP servers are configured, AIA connects to them in parallel using fiber-based concurrency (via the `simple_flow` gem) for faster startup.
482
-
483
- ## Troubleshooting MCP
484
-
485
- ### Common Issues
486
-
487
- #### Client Connection Failures
488
- ```bash
489
- # Debug MCP client connections
490
- aia --debug --mcp github.json test_prompt
491
-
492
- # List configured servers to verify setup
493
- aia --mcp-list
494
-
495
- # List MCP server tools to verify connectivity
496
- aia --mcp-list --list-tools
497
- ```
498
-
499
- #### Protocol Errors
500
-
501
- Enable detailed MCP logging via the logger configuration:
502
-
503
- ```yaml
504
- # ~/.config/aia/aia.yml
505
- logger:
506
- mcp:
507
- file: /tmp/aia-mcp.log
508
- level: debug
509
- flush: true
510
- ```
511
-
512
- Or via CLI:
513
- ```bash
514
- aia --debug my_prompt # Sets all loggers to debug level
515
- ```
516
-
517
- ## MCP Examples Repository
518
-
519
- ### GitHub Repository Analysis
520
- ```markdown
521
- # ~/.prompts/mcp_examples/github_repo_health.md
522
- # Requires MCP server "github" configured in ~/.config/aia/aia.yml
523
-
524
- # GitHub Repository Health Check
525
-
526
- Repository: <%= repository %>
527
-
528
- ## Comprehensive Health Analysis
529
- 1. **Activity Metrics**
530
- - Commit frequency and patterns
531
- - Contributor activity and distribution
532
- - Issue resolution time and patterns
533
- - Pull request merge rates
534
-
535
- 2. **Code Quality Indicators**
536
- - Documentation coverage
537
- - Test file presence and organization
538
- - Dependency management practices
539
- - Security vulnerability reports
540
-
541
- 3. **Community Engagement**
542
- - Issue discussion quality
543
- - Response times to community contributions
544
- - Maintainer activity levels
545
- - Project governance clarity
546
-
547
- 4. **Technical Debt Assessment**
548
- - Outstanding bugs and technical issues
549
- - Code review thoroughness
550
- - Deprecated dependency usage
551
- - Architecture evolution patterns
552
-
553
- Generate detailed health score with specific improvement recommendations.
554
- ```
555
-
556
- ### File System Audit
557
- ```markdown
558
- # ~/.prompts/mcp_examples/filesystem_audit.md
559
- # Requires MCP server "filesystem" configured in ~/.config/aia/aia.yml
560
-
561
- # File System Security and Organization Audit
562
-
563
- Target directory: <%= target_path %>
564
-
565
- ## Security Assessment
566
- 1. **Permission Analysis**
567
- - File and directory permissions
568
- - Ownership consistency
569
- - Sensitive file exposure
570
- - Configuration file security
571
-
572
- 2. **Organization Review**
573
- - Directory structure logic
574
- - File naming consistency
575
- - Duplicate file detection
576
- - Orphaned file identification
577
-
578
- 3. **Compliance Check**
579
- - Standard directory compliance
580
- - Required file presence
581
- - Documentation completeness
582
- - License file availability
583
-
584
- 4. **Optimization Opportunities**
585
- - Large file identification
586
- - Unused file detection
587
- - Archive opportunities
588
- - Cleanup recommendations
589
-
590
- Provide prioritized action plan for security and organization improvements.
591
- ```
592
-
593
- ## Related Documentation
594
-
595
- - [Tools Integration](guides/tools.md) - RubyLLM tools vs MCP comparison
596
- - [Advanced Prompting](advanced-prompting.md) - Complex MCP integration patterns
597
- - [Configuration](configuration.md) - MCP configuration options
598
- - [Security Best Practices](security.md) - MCP security guidelines
599
- - [Examples](examples/mcp/index.md) - Real-world MCP examples
600
-
601
- ---
602
-
603
- MCP integration extends AIA's capabilities beyond Ruby tools, providing standardized access to external services and enabling complex, multi-system workflows. Start with simple integrations and gradually build more sophisticated MCP-based solutions!