aios-core 3.4.0 → 3.5.0

package/.aios-core/development/tasks/add-mcp.md

@@ -166,11 +166,47 @@ docker mcp catalog info {mcp-name}
 ### 3. Add MCP Server
 
 ```bash
-# Add the server
-docker mcp server add {mcp-name}
+# Enable the server
+docker mcp server enable {mcp-name}
+```
+
+### 3.1 Configure Credentials (CRITICAL - Known Bug Workaround)
+
+⚠️ **BUG:** Docker MCP Toolkit's secrets store and template interpolation (`{{...}}`) do NOT work properly. Credentials set via `docker mcp secret set` are not passed to containers.
+
+**WORKAROUND:** Edit the catalog file directly to hardcode env values.
+
+```yaml
+# Edit: ~/.docker/mcp/catalogs/docker-mcp.yaml
+# Find your MCP entry and add/modify the env section:
+
+{mcp-name}:
+  # ... other config ...
+  env:
+    - name: {ENV_VAR_NAME}
+      value: '{actual-api-key-value}'
+    - name: TOOLS
+      value: 'tool1,tool2,tool3'
+```
+
+**Example for Apify:**
+```yaml
+apify-mcp-server:
+  env:
+    - name: TOOLS
+      value: 'actors,docs,apify/rag-web-browser'
+    - name: APIFY_TOKEN
+      value: 'apify_api_xxxxxxxxxxxxx'
+```
 
-# With environment variable
-docker mcp server add {mcp-name} --env NOTION_API_KEY=${NOTION_API_KEY}
+**Security Note:** This exposes credentials in a local file. Ensure:
+1. `~/.docker/mcp/catalogs/` is not committed to any repo
+2. File permissions restrict access to current user only
+
+**Alternative (if secrets work in future):**
+```bash
+# Set secret (currently NOT working)
+docker mcp secret set {mcp-name}.{credential_name}={value}
 ```
 
 ### 4. Update Gordon Config (Optional)
@@ -208,6 +244,50 @@ docker mcp preset update {preset-name} --add-server {mcp-name}
 docker mcp preset create {new-preset} --servers fs,github,{mcp-name}
 ```
 
+### 7. Update AIOS Documentation (REQUIRED)
+
+Add the new MCP to `.claude/rules/mcp-usage.md`:
+
+```markdown
+## {MCP-Name} MCP Usage (via Docker)
+
+### Use {MCP-Name} for:
+1. [Primary use case 1]
+2. [Primary use case 2]
+
+### Access pattern:
+\`\`\`
+mcp__docker-gateway__{tool-name-1}
+mcp__docker-gateway__{tool-name-2}
+\`\`\`
+```
+
+Also update the table in "Inside Docker Desktop (via docker-gateway)" section.
+
+### 8. Notify User About Session Restart (CRITICAL)
+
+⚠️ **The user MUST restart their Claude Code session** for new MCP tools to be available.
+
+```text
+IMPORTANT: New MCP tools will NOT be available until you:
+1. Close this Claude Code session
+2. Open a new Claude Code session: `claude`
+
+The docker-gateway caches tools at startup. New tools only appear after restart.
+```
+
+### 9. Verify Tools Available in New Session
+
+After user restarts Claude Code, verify tools are accessible:
+
+```bash
+# In new Claude Code session, ask an agent to use the new MCP
+@analyst Use the {mcp-name} tool to [perform some action]
+
+# Expected: Agent should see and use mcp__docker-gateway__{tool-name}
+# If not visible: Check docker mcp server list and docker mcp tools ls
+```
+
 ---
 
 ## Post-Conditions
@@ -220,13 +300,27 @@ post-conditions:
     validacao: docker mcp server list includes new MCP
     error_message: "MCP addition failed"
 
-  - [ ] Tools available
+  - [ ] Tools available in Docker MCP
     tipo: post-condition
     blocker: true
     validacao: docker mcp tools ls shows MCP tools
     error_message: "MCP tools not available - check credentials"
+
+  - [ ] AIOS documentation updated
+    tipo: post-condition
+    blocker: true
+    validacao: .claude/rules/mcp-usage.md includes new MCP
+    error_message: "Update mcp-usage.md with new MCP documentation"
+
+  - [ ] User notified about session restart
+    tipo: post-condition
+    blocker: true
+    validacao: User informed to restart Claude Code session
+    error_message: "Notify user: tools only available after session restart"
 ```
 
+**CRITICAL NOTE:** Tools added to Docker MCP Toolkit are NOT immediately available to AIOS agents. The docker-gateway caches tools at Claude Code startup. User MUST restart their Claude Code session for new tools to appear.
+
 ---
 
 ## Error Handling
@@ -240,13 +334,19 @@ Resolution:
 3. Check if MCP is in the registry: https://github.com/modelcontextprotocol/registry
 ```
 
-### Error: Credentials Missing
+### Error: Credentials Missing / Tools Not Loading
 
-```
-Resolution:
-1. Set environment variable: export NOTION_API_KEY=your_key
-2. Add to .env file: NOTION_API_KEY=your_key
-3. Pass directly: docker mcp server add notion --env NOTION_API_KEY=key
+```text
+Resolution (Due to Known Bug):
+1. Edit catalog directly: ~/.docker/mcp/catalogs/docker-mcp.yaml
+2. Add hardcoded env values in the MCP's env section
+3. Verify with: docker mcp tools ls --verbose
+4. Check output shows "(N tools)" not "(N prompts)"
+
+If still showing only prompts:
+- Token may be invalid
+- TOOLS env var may be wrong
+- MCP may need specific configuration
 ```
 
 ### Error: MCP Fails to Start
@@ -302,7 +402,7 @@ Next steps:
 
 ```yaml
 task: add-mcp
-version: 1.1.0
+version: 1.3.0
 story: Story 6.14 - MCP Governance Consolidation
 dependencies:
   - Docker MCP Toolkit
@@ -313,10 +413,21 @@ tags:
   - docker
   - dynamic
 created_at: 2025-12-08
-updated_at: 2025-12-17
+updated_at: 2025-12-23
 agents:
   - devops
 changelog:
+  1.3.0:
+    - Added: Step 3.1 documenting Docker MCP secrets/template bug
+    - Added: Workaround using catalog file direct edit
+    - Updated: Error handling for credentials issues
+    - Fixed: Apify MCP now working with 7 tools
+    - Note: Bug affects all MCPs requiring authentication
+  1.2.0:
+    - Added: Steps 7-9 for AIOS documentation and session restart
+    - Added: Post-conditions for documentation update and user notification
+    - Added: Critical note about docker-gateway tool caching
+    - Fixed: Tools not appearing in AIOS agents after MCP addition
   1.1.0:
     - Changed: DevOps Agent now exclusive responsible (Story 6.14)
     - Removed: Dev Agent from agents list

package/.aios-core/development/tasks/setup-mcp-docker.md

@@ -1,9 +1,9 @@
 # Setup Docker MCP Toolkit
 
 **Task ID:** setup-mcp-docker
-**Version:** 2.1.0
+**Version:** 2.2.0
 **Created:** 2025-12-08
-**Updated:** 2025-12-17
+**Updated:** 2025-12-23
 **Agent:** @devops (Gage)
 
 ---
@@ -369,12 +369,47 @@ docker mcp server enable exa
 # Set user home directory for desktop-commander
 docker mcp config write "desktop-commander:
   paths:
-    - ${HOME}
+    - ${HOME}"
+```
+
+### 4.1 Configure API Keys (CRITICAL - Known Bug Workaround)
+
+⚠️ **BUG:** Docker MCP Toolkit's secrets store and template interpolation do NOT work properly. Credentials set via `docker mcp secret set` or `config.yaml apiKeys` are not passed to containers for MCPs with strict config schemas.
+
+**WORKAROUND:** Edit the catalog file directly to hardcode env values.
+
+```yaml
+# Edit: ~/.docker/mcp/catalogs/docker-mcp.yaml
+# Find the MCP entry and add/modify the env section:
+
+# Example for EXA (already working via apiKeys - no change needed):
 exa:
   apiKeys:
-    EXA_API_KEY: \${EXA_API_KEY}"
+    EXA_API_KEY: your-actual-api-key
+
+# Example for Apify (requires catalog edit):
+apify-mcp-server:
+  env:
+    - name: TOOLS
+      value: 'actors,docs,apify/rag-web-browser'
+    - name: APIFY_TOKEN
+      value: 'your-actual-apify-token'
 ```
 
+**Security Note:** This exposes credentials in a local file. Ensure:
+1. `~/.docker/mcp/catalogs/` is not committed to any repo
+2. File permissions restrict access to current user only
+
+**Alternative config.yaml (works for some MCPs like EXA):**
+```yaml
+# ~/.docker/mcp/config.yaml
+exa:
+  apiKeys:
+    EXA_API_KEY: your-api-key
+```
+
+See `*add-mcp` task (Step 3.1) for detailed instructions.
+
 ### 5. Configure Claude Code (HTTP Transport)
 
 **IMPORTANT:** Use HTTP type, NOT stdio!
@@ -557,7 +592,7 @@ token_usage: ~500-1,000 tokens (this task only)
 
 ```yaml
 story: Story 6.14 - MCP Governance Consolidation
-version: 2.1.0
+version: 2.2.0
 dependencies:
   - Docker Desktop 4.50+
   - Docker MCP Toolkit
@@ -569,10 +604,15 @@ tags:
   - setup
   - http-transport
 created_at: 2025-12-08
-updated_at: 2025-12-17
+updated_at: 2025-12-23
 agents:
   - devops
 changelog:
+  2.2.0:
+    - Added: Step 4.1 documenting Docker MCP secrets bug
+    - Added: Workaround using catalog file direct edit
+    - Updated: Clarified which MCPs need catalog edit vs config.yaml
+    - Fixed: Apify and similar MCPs now configurable
   2.1.0:
     - Changed: DevOps Agent now exclusive responsible (Story 6.14)
     - Removed: Dev Agent from agents list

package/.aios-core/development/tasks/squad-creator-download.md

@@ -3,63 +3,165 @@ task: Download Squad
 responsavel: "@squad-creator"
 responsavel_type: agent
 atomic_layer: task
-status: placeholder
+status: active
 sprint: 8
+story: SQS-6
 Entrada: |
-  - name: Nome do squad para baixar
-  - source: Fonte (aios-squads | synkra-api)
+  - squad_name: Nome do squad para baixar (obrigatório)
+  - version: Versão específica (opcional, default: latest)
+  - list: Flag para listar squads disponíveis (--list)
+  - overwrite: Flag para sobrescrever squad existente (--overwrite)
 Saida: |
   - squad_path: Caminho do squad baixado
-  - status: Sucesso ou erro
+  - manifest: Manifest do squad
+  - validation_result: Resultado da validação
 Checklist:
-  - "[ ] Implementar em Sprint 8 (SQS-5)"
+  - "[ ] Verificar se já existe localmente"
+  - "[ ] Buscar no registry.json"
+  - "[ ] Baixar arquivos do GitHub"
+  - "[ ] Extrair para ./squads/{name}/"
+  - "[ ] Validar squad baixado"
+  - "[ ] Exibir próximos passos"
 ---
 
 # *download-squad
 
-> **PLACEHOLDER** - Implementation scheduled for Sprint 8 (Story SQS-5)
+Downloads public squads from the aios-squads GitHub repository to use in your project.
 
-## Planned Functionality
+## Usage
 
-Downloads a public squad from the aios-squads repository or Synkra API marketplace.
+```bash
+@squad-creator
+
+# List available squads
+*download-squad --list
+
+# Download a squad
+*download-squad etl-squad
 
-## Planned Usage
+# Download specific version
+*download-squad etl-squad@2.0.0
 
+# Overwrite existing
+*download-squad etl-squad --overwrite
 ```
-@squad-creator
 
+## Examples
+
+### List Available Squads
+
+```
+*download-squad --list
+
+Available Squads (from aios-squads):
+
+Official:
+  ├── etl-squad@1.0.0 - ETL pipeline automation
+  ├── api-squad@1.2.0 - REST API development
+  └── devops-squad@1.0.0 - CI/CD automation
+
+Community:
+  ├── data-viz-squad@0.5.0 - Data visualization
+  └── ml-squad@0.3.0 - Machine learning pipelines
+```
+
+### Download Squad
+
+```
 *download-squad etl-squad
-# → Downloads from github.com/SynkraAI/aios-squads
 
-*download-squad premium-pack --source synkra-api
-# → Downloads from api.synkra.dev/squads (requires auth)
+Downloading: etl-squad@1.0.0
+  Source: github.com/SynkraAI/aios-squads/packages/etl-squad
+  Target: ./squads/etl-squad/
+
+✓ Downloaded 12 files
+✓ Validated successfully
+
+Squad installed! Next steps:
+  1. Review: cat squads/etl-squad/squad.yaml
+  2. Activate: @squad-creator *activate etl-squad
 ```
 
-## Planned Features
+## Options
 
-1. **Repository Source (Default)**
-   - Clone from github.com/SynkraAI/aios-squads
-   - Support specific versions via tags
-   - Validate squad before installation
+| Option | Description |
+|--------|-------------|
+| `--list` | List all available squads from registry |
+| `--version` | Download specific version (e.g., @2.0.0) |
+| `--overwrite` | Overwrite if squad already exists locally |
+| `--verbose` | Show detailed download progress |
 
-2. **Synkra API Source**
-   - Download from api.synkra.dev/squads
-   - Support premium/paid squads
-   - Require authentication
+## How It Works
 
-3. **Installation**
-   - Install to ./squads/{name}/
-   - Run validation after download
-   - Show usage instructions
+```
+1. Fetch registry.json from aios-squads
+   ├── Contains official and community squads
+   └── Includes version and metadata
 
-## Related Story
+2. Find requested squad
+   ├── Search official squads first
+   └── Then community squads
 
-- **SQS-5:** SquadSyncService (Sprint 8)
-- **SQS-6:** Registry Integration (Sprint 8)
+3. Download via GitHub API
+   ├── Get directory listing
+   └── Download each file recursively
 
-## Current Status
+4. Validate downloaded squad
+   ├── Run SquadValidator
+   └── Report warnings/errors
+
+5. Load manifest
+   └── Confirm installation
+```
+
+## Registry Structure
+
+The registry.json in aios-squads contains:
+
+```json
+{
+  "version": "1.0.0",
+  "squads": {
+    "official": [
+      {
+        "name": "etl-squad",
+        "version": "1.0.0",
+        "description": "ETL pipeline automation",
+        "author": "SynkraAI"
+      }
+    ],
+    "community": [
+      {
+        "name": "data-viz-squad",
+        "version": "0.5.0",
+        "description": "Data visualization",
+        "author": "community-member"
+      }
+    ]
+  }
+}
+```
 
-This task is a placeholder. The full implementation will be done in Sprint 8.
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `SQUAD_NOT_FOUND` | Squad not in registry | Check available squads with --list |
+| `SQUAD_EXISTS` | Already downloaded | Use --overwrite flag |
+| `REGISTRY_FETCH_ERROR` | Network issue | Check connection |
+| `RATE_LIMIT` | GitHub API limit | Set GITHUB_TOKEN env var |
+
+## Implementation
+
+Uses `SquadDownloader` class from:
+- `.aios-core/development/scripts/squad/squad-downloader.js`
+
+## Related Tasks
+
+- `*validate-squad` - Validate downloaded squad
+- `*publish-squad` - Publish your squad to registry
+- `*create-squad` - Create new local squad
+
+## Related Story
 
-For now, manually clone squads from:
-- https://github.com/SynkraAI/aios-squads
+- **SQS-6:** Download & Publish Tasks (Sprint 8)