moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/configure/mcp-servers.md

@@ -0,0 +1,214 @@
+---
+source: https://opencode.ai/docs/mcp-servers/
+fetched: 2026-01-08
+title: MCP Servers Configuration
+---
+
+# MCP Servers in OpenCode
+
+## Overview
+
+OpenCode enables integration of external tools through the Model Context Protocol (MCP), supporting both local and remote servers that become automatically available to language models.
+
+## Local MCP Servers
+
+Use a command-based approach:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "filesystem": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem"],
+      "environment": {
+        "MCP_ROOT": "/path/to/root"
+      }
+    }
+  }
+}
+```
+
+### Local Server Options
+
+| Option | Description |
+|--------|-------------|
+| `type` | Set to `"local"` |
+| `command` | Array of command and arguments |
+| `environment` | Environment variables |
+
+## Remote MCP Servers
+
+Connect via HTTP:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-remote-server": {
+      "type": "remote",
+      "url": "https://example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer TOKEN"
+      }
+    }
+  }
+}
+```
+
+### Remote Server Options
+
+| Option | Description |
+|--------|-------------|
+| `type` | Set to `"remote"` |
+| `url` | Server endpoint URL |
+| `headers` | HTTP headers (auth, etc.) |
+
+## Authentication
+
+### Automatic OAuth
+
+OpenCode handles OAuth automatically for remote servers, including dynamic client registration.
+
+### Manual Authentication
+
+```bash
+# Trigger OAuth flow
+opencode mcp auth <server-name>
+
+# Check auth status
+opencode mcp list
+
+# Remove credentials
+opencode mcp logout <server-name>
+```
+
+### Disable OAuth
+
+For API-key-based servers, disable OAuth:
+
+```json
+{
+  "mcp": {
+    "api-server": {
+      "type": "remote",
+      "url": "https://api.example.com/mcp",
+      "oauth": false,
+      "headers": {
+        "X-API-Key": "{env:API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Management
+
+### Global Control
+
+Enable/disable across all agents:
+
+```json
+{
+  "tools": {
+    "mcp_filesystem_*": false
+  }
+}
+```
+
+### Per-Agent Configuration
+
+Activate selectively for specific agents:
+
+```json
+{
+  "agent": {
+    "file-worker": {
+      "tools": {
+        "mcp_filesystem_*": true
+      }
+    }
+  }
+}
+```
+
+### Glob Patterns
+
+Use wildcards to manage multiple servers:
+
+```json
+{
+  "tools": {
+    "mcp_*": false,
+    "mcp_approved_*": true
+  }
+}
+```
+
+## Performance Consideration
+
+"MCP servers add to your context, so you want to be careful with which ones you enable."
+
+Excessive tools can quickly exhaust context limits.
+
+### Best Practices
+
+1. **Enable only needed servers**: Disable unused MCP servers
+2. **Use per-agent configuration**: Only enable for relevant agents
+3. **Monitor context usage**: Watch for context limit warnings
+4. **Use glob patterns**: Manage groups of tools efficiently
+
+## Examples
+
+### GitHub MCP Server
+
+```json
+{
+  "mcp": {
+    "github": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+      "environment": {
+        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Database MCP Server
+
+```json
+{
+  "mcp": {
+    "postgres": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
+      "environment": {
+        "DATABASE_URL": "{env:DATABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+### Multiple Servers
+
+```json
+{
+  "mcp": {
+    "filesystem": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
+    },
+    "github": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"]
+    },
+    "custom-api": {
+      "type": "remote",
+      "url": "https://api.myservice.com/mcp"
+    }
+  }
+}
+```

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/configure/models.md

@@ -0,0 +1,197 @@
+---
+source: https://opencode.ai/docs/models/
+fetched: 2026-01-08
+title: Models Configuration
+---
+
+# OpenCode Models Documentation
+
+## Overview
+
+OpenCode explains how to configure LLM providers and models, supporting 75+ providers through the AI SDK and Models.dev integration.
+
+## Providers
+
+OpenCode preloads popular providers by default. Users can add credentials via the `/connect` command to enable additional providers.
+
+```bash
+/connect
+```
+
+## Model Selection
+
+Access model selection through the `/models` command after configuring your provider:
+
+```bash
+/models
+```
+
+## Recommended Models
+
+The following models are recommended for code generation and tool calling:
+
+| Model | Provider |
+|-------|----------|
+| GPT 5.2 | OpenAI |
+| GPT 5.1 Codex | OpenAI |
+| Claude Opus 4.5 | Anthropic |
+| Claude Sonnet 4.5 | Anthropic |
+| Minimax M2.1 | Minimax |
+| Gemini 3 Pro | Google |
+
+## Default Configuration
+
+Set default models via the config file using the format `provider_id/model_id`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4",
+  "small_model": "anthropic/claude-haiku-3-5"
+}
+```
+
+For local models:
+
+```json
+{
+  "model": "lmstudio/google/gemma-3n-e4b"
+}
+```
+
+## Model Options Configuration
+
+### Global Configuration
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "openai/gpt-5",
+  "provider": {
+    "openai": {
+      "models": {
+        "gpt-5": {
+          "options": {
+            "reasoningEffort": "high"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Agent-Specific Configuration
+
+```json
+{
+  "agent": {
+    "deep-thinker": {
+      "model": "openai/gpt-5",
+      "modelOptions": {
+        "reasoningEffort": "xhigh"
+      }
+    }
+  }
+}
+```
+
+## Variants System
+
+Models support multiple configuration variants for different use cases.
+
+### Built-in Variants
+
+**Anthropic:**
+- `high` (default): Standard thinking budget
+- `max`: Maximum thinking budget
+
+**OpenAI:**
+- `none`: No reasoning
+- `low`: Low reasoning effort
+- `medium`: Medium reasoning effort
+- `high`: High reasoning effort (default)
+- `xhigh`: Extra high reasoning effort
+
+**Google:**
+- `low`: Low effort level
+- `high`: High effort level
+
+### Custom Variants
+
+Override existing variants or create custom ones:
+
+```json
+{
+  "provider": {
+    "anthropic": {
+      "models": {
+        "claude-sonnet-4": {
+          "variants": {
+            "quick": {
+              "options": {
+                "thinkingBudget": 1000
+              }
+            },
+            "deep": {
+              "options": {
+                "thinkingBudget": 50000
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Switching Variants
+
+Use the `variant_cycle` keybind to switch between variants during a session.
+
+## Model Loading Priority
+
+Models are selected in the following order:
+
+1. **Command-line flag**: `--model` or `-m`
+2. **Config file**: `model` field in `opencode.json`
+3. **Last used model**: Persisted from previous session
+4. **Internal default**: Built-in priority list
+
+## Examples
+
+### Using Multiple Models
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4",
+  "small_model": "anthropic/claude-haiku-3-5",
+  "agent": {
+    "complex-tasks": {
+      "model": "anthropic/claude-opus-4"
+    },
+    "quick-tasks": {
+      "model": "anthropic/claude-haiku-3-5"
+    }
+  }
+}
+```
+
+### Local Model Configuration
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "ollama/llama2",
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "http://localhost:11434/v1"
+      }
+    }
+  }
+}
+```

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/configure/permissions.md

@@ -0,0 +1,162 @@
+---
+source: https://opencode.ai/docs/permissions/
+fetched: 2026-01-08
+title: Permissions Configuration
+---
+
+# OpenCode Permissions Documentation
+
+## Overview
+
+OpenCode manages action approval through a `permission` config system that determines whether actions run automatically, require approval, or are blocked entirely.
+
+## Core Permission States
+
+Actions resolve to three outcomes:
+
+| State | Description |
+|-------|-------------|
+| `"allow"` | Automatic execution |
+| `"ask"` | User approval required |
+| `"deny"` | Blocked |
+
+## Configuration Structure
+
+### Global Configuration
+
+Set permissions globally using `"*"` as a catch-all, with specific tool overrides:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "*": "ask",
+    "bash": "allow",
+    "edit": "deny"
+  }
+}
+```
+
+### Granular Pattern Control
+
+Object syntax enables granular control based on input patterns:
+
+```json
+{
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "rm *": "deny"
+    }
+  }
+}
+```
+
+### Pattern Matching
+
+- `*`: Matches any characters
+- `?`: Matches single character
+- Last matching rule takes precedence
+
+## Available Permissions
+
+OpenCode protects the following actions:
+
+| Permission | Description |
+|------------|-------------|
+| `read` | File reading |
+| `edit` | File editing |
+| `glob` | Pattern matching |
+| `grep` | Content searching |
+| `list` | Directory listing |
+| `bash` | Shell command execution |
+| `task` | Subagent invocation |
+| `skill` | Skill loading |
+| `lsp` | Language server operations |
+| `todoread` | Task list reading |
+| `todowrite` | Task list writing |
+| `webfetch` | Web content retrieval |
+| `websearch` | Web searching |
+| `codesearch` | Code searching |
+| `external_directory` | External directory access |
+| `doom_loop` | Runaway loop prevention |
+
+## Default Behavior
+
+| Permission | Default |
+|------------|---------|
+| Most permissions | `"allow"` |
+| `doom_loop` | `"ask"` |
+| `external_directory` | `"ask"` |
+| `*.env` files | `"deny"` |
+
+**Note:** Files matching `*.env` patterns are denied by default to protect sensitive data.
+
+## Agent-Level Overrides
+
+Agents can override global permissions:
+
+```json
+{
+  "agent": {
+    "careful-agent": {
+      "permission": {
+        "*": "ask",
+        "read": "allow"
+      }
+    }
+  }
+}
+```
+
+Agent rules take precedence in merged configurations.
+
+## Examples
+
+### Restrictive Configuration
+
+```json
+{
+  "permission": {
+    "*": "ask",
+    "read": "allow",
+    "grep": "allow",
+    "glob": "allow"
+  }
+}
+```
+
+### Allow Git, Deny Destructive
+
+```json
+{
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "rm *": "deny",
+      "sudo *": "deny"
+    }
+  }
+}
+```
+
+### Safe Read-Only Mode
+
+```json
+{
+  "permission": {
+    "edit": "deny",
+    "write": "deny",
+    "bash": "deny"
+  }
+}
+```
+
+## Best Practices
+
+1. **Start restrictive**: Use `"*": "ask"` and allow specific actions
+2. **Protect sensitive files**: Ensure `.env` and credentials are denied
+3. **Use patterns**: Create specific rules for common commands
+4. **Test permissions**: Verify behavior before production use

moai_adk/templates/.claude/skills/moai-tool-opencode/modules/configure/rules.md

@@ -0,0 +1,129 @@
+---
+source: https://opencode.ai/docs/rules/
+fetched: 2026-01-08
+title: Rules and Instructions
+---
+
+# Rules Documentation - OpenCode
+
+## Overview
+
+OpenCode allows developers to customize LLM behavior through custom instructions. The primary mechanism is an `AGENTS.md` file that functions similarly to "CLAUDE.md" or Cursor's rules, containing project-specific guidance.
+
+## Key Features
+
+### Initialization
+
+Running the `/init` command scans your project and generates an `AGENTS.md` file with auto-detected context.
+
+```bash
+/init
+```
+
+### File Locations
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| Project-level | `AGENTS.md` in repository root | Version-controlled team rules |
+| Global | `~/.config/opencode/AGENTS.md` | Personal rules across projects |
+
+### Configuration Support
+
+The `opencode.json` file accepts an `instructions` field that references external rule files:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "AGENTS.md",
+    "packages/*/AGENTS.md",
+    ".opencode/instructions/*.md"
+  ]
+}
+```
+
+Supports glob patterns for flexible file discovery.
+
+## Implementation Example
+
+A typical project `AGENTS.md` establishes:
+- Monorepo structure
+- Code standards
+- Naming conventions
+- Import conventions
+- Framework-specific guidance
+
+### Example AGENTS.md
+
+```markdown
+# Project Instructions
+
+## Architecture
+This is an SST v3 monorepo with the following structure:
+- `packages/core/` - Shared business logic
+- `packages/functions/` - Lambda handlers
+- `packages/web/` - React frontend
+
+## Code Standards
+- Use TypeScript strict mode
+- Prefer functional components
+- Use barrel exports from index.ts
+
+## Conventions
+- Import order: external, internal, relative
+- Use named exports over default exports
+- File names: kebab-case
+```
+
+## Precedence Rules
+
+OpenCode searches hierarchically:
+
+1. Local files first (traversing upward from current directory)
+2. Then global configuration
+
+Both global and project rules combine when present.
+
+## Advanced Patterns
+
+### Lazy Loading
+
+Developers can implement "lazy loading" of external references by instructing the AI to read specific files "on a need-to-know basis" rather than preemptively.
+
+```markdown
+## Extended Documentation
+When working on authentication, read @docs/auth-patterns.md
+When working on database, read @docs/db-conventions.md
+```
+
+This keeps configuration modular while maintaining focused context.
+
+### Multiple Instruction Files
+
+Use glob patterns to load multiple instruction files:
+
+```json
+{
+  "instructions": [
+    "AGENTS.md",
+    ".opencode/rules/*.md",
+    "packages/*/AGENTS.md"
+  ]
+}
+```
+
+### Conditional Rules
+
+Structure rules for specific contexts:
+
+```markdown
+## When Working on API
+- Use zod for validation
+- Follow REST conventions
+- Include error handling
+
+## When Working on Frontend
+- Use React Query for data fetching
+- Follow component composition patterns
+- Include loading states
+```