opencode-template

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# OpenCode Template

Comprehensive template repository for OpenCode CLI - a powerful AI-assisted development environment with agents, commands, and skills.

## What is OpenCode?

OpenCode is an AI-powered development CLI that helps you build software faster through:
- **Agents**: Specialized AI assistants for different development tasks
- **Commands**: Pre-built workflows for common operations
- **Skills**: Reusable knowledge modules that enhance agent capabilities
- **Plugins**: Extensions that add custom functionality

## Quick Start

### Prerequisites

- OpenCode CLI installed
- Node.js 18+ (for MCP servers)
- Git

### Installation

1. Install OpenCode CLI (if not already installed)

2. Clone this template:
```bash
git clone https://github.com/julianromli/opencode-template.git
cd opencode-template
```

3. **Setup Environment Variables (IMPORTANT)**:

   **Windows (PowerShell as Administrator):**
   ```powershell
   cd scripts
   .\setup-env-windows.ps1
   ```

   **macOS/Linux:**
   ```bash
   cd scripts
   bash setup-env-mac.sh
   source ~/.zshrc  # or ~/.bashrc
   ```

   See `scripts/README.md` for detailed instructions and troubleshooting.

4. Initialize your project:
```bash
opencode init
```

5. Restart your terminal or IDE for environment variables to take effect

### Required Environment Variables

The setup scripts configure these essential variables:

```bash
OPENCODE_EXPERIMENTAL_PLAN_MODE=1    # Enable experimental features
OPENCODE_UNSAFE_ALLOW_OUTSIDE=1      # Allow operations outside workspace
OPENCODE_UNSAFE_FILES=1              # Enable file operations
OPENCODE_UNSAFE_INCLUDE_GIT=1        # Enable git operations
```

**Why these are needed:**
- Enable advanced OpenCode features
- Allow AI agents to perform file and git operations
- Required for full template functionality

### Basic Usage

Start OpenCode in your project:
```bash
opencode
```

Invoke an agent:
```bash
opencode agent <agent-name>
```

Run a command:
```bash
opencode command <command-name>
```

## Repository Structure

```
.
├── agent/              # AI agent definitions
│   ├── core/          # Core system agents
│   ├── development/   # Development-focused agents
│   ├── content/       # Content creation agents
│   ├── data/          # Data analysis agents
│   ├── meta/          # Meta-level agents
│   └── subagents/     # Specialized sub-agents
├── command/           # Command definitions
│   ├── openagents/    # OpenAgents-specific commands
│   └── prompt-engineering/ # Prompt optimization commands
├── skill/             # Skill modules
│   ├── backend-dev/   # Backend development patterns
│   ├── frontend-design/ # Frontend design guidelines
│   ├── next-best-practices/ # Next.js best practices
│   └── ...            # Many more specialized skills
├── plugin/            # Plugin scripts
├── tool/              # Custom tools
└── opencode.json      # OpenCode configuration
```

## Core Components

### Agents

Agents are specialized AI assistants that handle specific tasks:

- **Core Agents** (`agent/core/`):
  - `openagent.md` - General-purpose agent
  - `opencoder.md` - Coding-focused agent

- **Development Agents** (`agent/development/`):
  - `backend-specialist.md` - Backend development
  - `frontend-specialist.md` - Frontend development
  - `devops-specialist.md` - DevOps and infrastructure
  - `codebase-agent.md` - Codebase analysis

- **Specialized Agents**:
  - Database architects
  - Security coders
  - Code reviewers
  - Content writers
  - Data analysts

### Commands

Pre-built workflows for common tasks:

- **Development**:
  - `build-context-system.md` - Build context management
  - `debug.md` - Debugging workflows
  - `fix.md` - Bug fixing procedures
  - `refactor-clean.md` - Code refactoring
  - `test.md` - Testing workflows

- **Planning**:
  - `brainstorm.md` - Ideation sessions
  - `write-plan.md` - Project planning
  - `execute-plan.md` - Plan execution

- **Quality**:
  - `review.md` - Code review
  - `optimize.md` - Performance optimization
  - `validate-repo.md` - Repository validation

- **Content**:
  - `design-system.md` - Design system creation
  - `seo.md` - SEO optimization
  - `enhance.md` - Content enhancement

### Skills

Reusable knowledge modules that enhance agent capabilities:

- **Backend Development**:
  - `backend-dev/` - Backend patterns and practices
  - `database-design/` - Database architecture
  - `llm-application-dev/` - LLM app development

- **Frontend Development**:
  - `frontend-design/` - UI/UX design principles
  - `frontend-ui-animator/` - Animation patterns
  - `next-best-practices/` - Next.js optimization
  - `vercel-react-best-practices/` - React performance

- **Development Practices**:
  - `test-driven-development/` - TDD methodology
  - `code-refactoring/` - Refactoring strategies
  - `systematic-debugging/` - Debugging techniques
  - `subagent-driven-development/` - Multi-agent workflows

- **Tools & Utilities**:
  - `skill-creator/` - Create new skills
  - `shadcn-management/` - shadcn/ui component management
  - `browser/` - Browser automation
  - `using-git-worktrees/` - Git worktree workflows

## Configuration

### opencode.json

Main configuration file for OpenCode:

```json
{
  "version": "1.0",
  "agents": {
    "directory": "agent"
  },
  "commands": {
    "directory": "command"
  },
  "skills": {
    "directory": "skill"
  },
  "plugins": {
    "directory": "plugin"
  }
}
```

## Creating Custom Components

### Creating an Agent

1. Create a new `.md` file in `agent/` directory
2. Define agent capabilities and behavior
3. Reference relevant skills and tools

Example structure:
```markdown
# Agent Name

## Purpose
Brief description of what this agent does

## Capabilities
- Capability 1
- Capability 2

## Skills Used
- skill-name-1
- skill-name-2

## Instructions
Detailed instructions for the agent...
```

### Creating a Command

1. Create a new `.md` file in `command/` directory
2. Define command workflow and steps
3. Specify required inputs and outputs

### Creating a Skill

1. Create a new directory in `skill/`
2. Add `SKILL.md` with skill documentation
3. Add reference materials in `references/` subdirectory
4. Add scripts in `scripts/` subdirectory if needed

Use the `skill-creator` skill to automate this:
```bash
opencode skill create <skill-name>
```

## Advanced Features

### Subagents

Subagents are specialized agents that can be invoked by other agents:

- **Code Subagents** (`agent/subagents/code/`):
  - Build agent
  - Coder agent
  - Reviewer
  - Tester

- **Core Subagents** (`agent/subagents/core/`):
  - Context retriever
  - Documentation generator
  - Task manager

### Agent Categories

Organize agents using `0-category.json` files:

```json
{
  "name": "Category Name",
  "description": "Category description",
  "icon": "icon-name"
}
```

## Best Practices

### Agent Development

1. **Single Responsibility**: Each agent should have one clear purpose
2. **Skill Composition**: Leverage existing skills rather than duplicating knowledge
3. **Clear Instructions**: Provide explicit, step-by-step instructions
4. **Error Handling**: Include error handling and recovery strategies

### Command Development

1. **Modular Steps**: Break commands into clear, sequential steps
2. **Validation**: Include validation checks at each step
3. **Documentation**: Document inputs, outputs, and side effects
4. **Idempotency**: Commands should be safe to run multiple times

### Skill Development

1. **Focused Scope**: Keep skills focused on specific domains
2. **Reference Materials**: Include examples and reference documentation
3. **Versioning**: Track skill versions and changes
4. **Testing**: Test skills with multiple agents and scenarios

## Common Workflows

### Starting a New Project

```bash
# Initialize project
opencode init

# Generate project structure
opencode command design-system

# Set up development environment
opencode agent backend-specialist "Set up project structure"
```

### Code Review Workflow

```bash
# Request code review
opencode command review

# Or use the code reviewer agent directly
opencode agent code-reviewer "Review recent changes"
```

### Debugging Workflow

```bash
# Use systematic debugging
opencode command debug

# Or invoke debugging skill
opencode agent opencoder "Use systematic-debugging skill to fix issue"
```

## Troubleshooting

### Agent Not Found

Ensure agent file exists in `agent/` directory and is properly formatted.

### Skill Not Loading

Check:
1. Skill directory contains `SKILL.md`
2. Skill is referenced correctly in agent/command
3. File permissions are correct

### Command Fails

1. Check command syntax in `.md` file
2. Verify all required inputs are provided
3. Review error logs in `.opencode/` directory

## Contributing

### Adding New Agents

1. Create agent file in appropriate subdirectory
2. Follow naming convention: `kebab-case.md`
3. Include comprehensive documentation
4. Test with multiple scenarios

### Adding New Skills

1. Use `skill-creator` skill as template
2. Include `SKILL.md` with clear documentation
3. Add reference materials and examples
4. Test with multiple agents

### Submitting Changes

1. Fork the repository
2. Create feature branch
3. Make changes with clear commits
4. Submit pull request with description

## Model Context Protocol (MCP)

### What is MCP?

**Model Context Protocol (MCP)** is an open protocol that standardizes how applications provide context to large language models (LLMs). It enables AI applications to connect with various data sources and tools in a consistent, structured manner.

### MCP Architecture

MCP follows a client-server architecture:

- **MCP Hosts**: Applications like AI assistants or IDEs (e.g., OpenCode CLI)
- **MCP Clients**: Connectors within the host that maintain 1:1 connections with servers
- **MCP Servers**: Services that provide context, tools, and capabilities through the standardized protocol

### Available MCP Integrations

OpenCode CLI supports various MCP servers that extend AI capabilities:

#### 1. **Context7 MCP** (`mcp_context7`)
**Purpose**: Up-to-date library documentation and code examples

**Tools**:
- `resolve-library-id`: Find Context7-compatible library IDs (e.g., `/mongodb/docs`, `/vercel/next.js`)
- `query-docs`: Query documentation with specific questions

**Use Cases**:
- Getting latest API documentation
- Finding code examples for libraries
- Learning framework-specific patterns
- Checking version-specific features

**Example**:
```bash
# First resolve library ID
resolve-library-id libraryName="next.js" query="Next.js documentation"

# Then query specific docs
query-docs libraryId="/vercel/next.js" query="How to use App Router in Next.js 15"
```

#### 2. **Exa Web Search MCP** (`mcp_exa`)
**Purpose**: Advanced web search and research capabilities

**Tools**:
- `exa`: General web search with clean, LLM-ready content
- `company_research_exa`: Research companies and business information
- `crawling_exa`: Extract content from specific URLs
- `get_code_context_exa`: Find code examples and documentation
- `deep_researcher_start`: Start AI research agent for complex topics
- `deep_researcher_check`: Check research task status and results

**Use Cases**:
- Finding current information and news
- Researching companies and technologies
- Extracting content from web pages
- Finding code examples from GitHub/Stack Overflow
- Deep research on complex topics

**Example**:
```bash
# Web search
exa query="Next.js 15 new features" numResults=5

# Code search
get_code_context_exa query="React Server Components examples" tokensNum=5000

# Deep research
deep_researcher_start instructions="Research best practices for microservices architecture"
```

#### 3. **Next.js DevTools MCP** (`mcp_next_devtools`)
**Purpose**: Next.js development server integration and diagnostics

**Tools**:
- `init`: Initialize Next.js DevTools context
- `nextjs_docs`: Fetch official Next.js documentation
- `nextjs_index`: Discover running Next.js dev servers and available tools
- `nextjs_call`: Call specific MCP tools on running dev server
- `browser_eval`: Browser automation for testing
- `upgrade_nextjs_16`: Guide for upgrading to Next.js 16
- `enable_cache_components`: Migrate to Cache Components mode

**Use Cases**:
- Real-time Next.js error diagnostics
- Querying running dev server state
- Browser-based page verification
- Next.js version upgrades
- Cache Components migration

**Example**:
```bash
# Initialize
init project_path="."

# Get errors from running dev server
nextjs_index
nextjs_call port="3000" toolName="get_errors"

# Query Next.js docs
nextjs_docs path="/docs/app/api-reference/functions/refresh"
```

### Configuring MCP Servers

MCP servers are configured in `.kiro/settings/mcp.json` (workspace-level) or `~/.kiro/settings/mcp.json` (user-level):

```json
{
  "mcpServers": {
    "context7": {
      "command": "uvx",
      "args": ["context7-mcp-server@latest"],
      "disabled": false,
      "autoApprove": ["resolve-library-id", "query-docs"]
    },
    "exa": {
      "command": "uvx",
      "args": ["exa-mcp-server@latest"],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      },
      "disabled": false
    }
  }
}
```

### MCP Best Practices

1. **Always call `resolve-library-id` before `query-docs`** (Context7)
2. **Limit MCP calls to 3 per question** to avoid excessive API usage
3. **Use specific queries** - "How to set up JWT auth in Express" not just "auth"
4. **Check dev server status** before calling Next.js MCP tools
5. **Use browser automation** for real page verification (not curl)

### Installing MCP Servers

Most MCP servers use `uvx` (Python package runner):

```bash
# Install uv (Python package manager)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Once installed, uvx will auto-download MCP servers on first use
```

### Troubleshooting MCP

**Server not connecting:**
- Check MCP config file syntax
- Verify `uvx` is installed
- Check server logs in OpenCode output

**Tools not available:**
- Restart OpenCode after config changes
- Check `disabled: false` in config
- Verify API keys for services that require them

**Performance issues:**
- Limit concurrent MCP calls
- Use specific queries to reduce response size
- Consider caching frequently accessed data

## Resources

- **OpenCode Documentation**: [Official Docs]
- **MCP Official Site**: https://modelcontextprotocol.io
- **Agent Examples**: See `agent/` directory
- **Skill Examples**: See `skill/` directory
- **Command Examples**: See `command/` directory

## License

See individual skill/component licenses in their respective directories.

## Support

For issues and questions:
- Open an issue on GitHub
- Check existing documentation in `docs/` directories
- Review skill-specific README files
- Visit MCP documentation for protocol-specific questions

---

**Note**: This template is designed to be customized for your specific needs. Feel free to add, remove, or modify agents, commands, and skills based on your workflow.

OpenCode Template

Comprehensive template repository for OpenCode CLI - a powerful AI-assisted development environment with agents, commands, and skills.

What is OpenCode?

OpenCode is an AI-powered development CLI that helps you build software faster through:

Agents: Specialized AI assistants for different development tasks
Commands: Pre-built workflows for common operations
Skills: Reusable knowledge modules that enhance agent capabilities
Plugins: Extensions that add custom functionality

Quick Start

Prerequisites

OpenCode CLI installed
Node.js 18+ (for MCP servers)
Git

Installation

Install OpenCode CLI (if not already installed)
Clone this template:

git clone https://github.com/julianromli/opencode-template.git
cd opencode-template

Setup Environment Variables (IMPORTANT):

Windows (PowerShell as Administrator):
```
cd scripts
.\setup-env-windows.ps1
```
macOS/Linux:
```
cd scripts
bash setup-env-mac.sh
source ~/.zshrc  # or ~/.bashrc
```
See scripts/README.md for detailed instructions and troubleshooting.
Initialize your project:

opencode init

Restart your terminal or IDE for environment variables to take effect

Required Environment Variables

The setup scripts configure these essential variables:

OPENCODE_EXPERIMENTAL_PLAN_MODE=1    # Enable experimental features
OPENCODE_UNSAFE_ALLOW_OUTSIDE=1      # Allow operations outside workspace
OPENCODE_UNSAFE_FILES=1              # Enable file operations
OPENCODE_UNSAFE_INCLUDE_GIT=1        # Enable git operations

Why these are needed:

Enable advanced OpenCode features
Allow AI agents to perform file and git operations
Required for full template functionality

Basic Usage

Start OpenCode in your project:

opencode

Invoke an agent:

opencode agent <agent-name>

Run a command:

opencode command <command-name>

Repository Structure

.
├── agent/              # AI agent definitions
│   ├── core/          # Core system agents
│   ├── development/   # Development-focused agents
│   ├── content/       # Content creation agents
│   ├── data/          # Data analysis agents
│   ├── meta/          # Meta-level agents
│   └── subagents/     # Specialized sub-agents
├── command/           # Command definitions
│   ├── openagents/    # OpenAgents-specific commands
│   └── prompt-engineering/ # Prompt optimization commands
├── skill/             # Skill modules
│   ├── backend-dev/   # Backend development patterns
│   ├── frontend-design/ # Frontend design guidelines
│   ├── next-best-practices/ # Next.js best practices
│   └── ...            # Many more specialized skills
├── plugin/            # Plugin scripts
├── tool/              # Custom tools
└── opencode.json      # OpenCode configuration

Core Components

Agents

Agents are specialized AI assistants that handle specific tasks:

Core Agents (agent/core/):
- openagent.md - General-purpose agent
- opencoder.md - Coding-focused agent
Development Agents (agent/development/):
- backend-specialist.md - Backend development
- frontend-specialist.md - Frontend development
- devops-specialist.md - DevOps and infrastructure
- codebase-agent.md - Codebase analysis
Specialized Agents:
- Database architects
- Security coders
- Code reviewers
- Content writers
- Data analysts

Commands

Pre-built workflows for common tasks:

Development:
- build-context-system.md - Build context management
- debug.md - Debugging workflows
- fix.md - Bug fixing procedures
- refactor-clean.md - Code refactoring
- test.md - Testing workflows
Planning:
- brainstorm.md - Ideation sessions
- write-plan.md - Project planning
- execute-plan.md - Plan execution
Quality:
- review.md - Code review
- optimize.md - Performance optimization
- validate-repo.md - Repository validation
Content:
- design-system.md - Design system creation
- seo.md - SEO optimization
- enhance.md - Content enhancement

Skills

Reusable knowledge modules that enhance agent capabilities:

Backend Development:
- backend-dev/ - Backend patterns and practices
- database-design/ - Database architecture
- llm-application-dev/ - LLM app development
Frontend Development:
- frontend-design/ - UI/UX design principles
- frontend-ui-animator/ - Animation patterns
- next-best-practices/ - Next.js optimization
- vercel-react-best-practices/ - React performance
Development Practices:
- test-driven-development/ - TDD methodology
- code-refactoring/ - Refactoring strategies
- systematic-debugging/ - Debugging techniques
- subagent-driven-development/ - Multi-agent workflows
Tools & Utilities:
- skill-creator/ - Create new skills
- shadcn-management/ - shadcn/ui component management
- browser/ - Browser automation
- using-git-worktrees/ - Git worktree workflows

Configuration

opencode.json

Main configuration file for OpenCode:

{
  "version": "1.0",
  "agents": {
    "directory": "agent"
  },
  "commands": {
    "directory": "command"
  },
  "skills": {
    "directory": "skill"
  },
  "plugins": {
    "directory": "plugin"
  }
}

Creating Custom Components

Creating an Agent

Create a new .md file in agent/ directory
Define agent capabilities and behavior
Reference relevant skills and tools

Example structure:

# Agent Name

## Purpose
Brief description of what this agent does

## Capabilities
- Capability 1
- Capability 2

## Skills Used
- skill-name-1
- skill-name-2

## Instructions
Detailed instructions for the agent...

Creating a Command

Create a new .md file in command/ directory
Define command workflow and steps
Specify required inputs and outputs

Creating a Skill

Create a new directory in skill/
Add SKILL.md with skill documentation
Add reference materials in references/ subdirectory
Add scripts in scripts/ subdirectory if needed

Use the skill-creator skill to automate this:

opencode skill create <skill-name>

Advanced Features

Subagents

Subagents are specialized agents that can be invoked by other agents:

Code Subagents (agent/subagents/code/):
- Build agent
- Coder agent
- Reviewer
- Tester
Core Subagents (agent/subagents/core/):
- Context retriever
- Documentation generator
- Task manager

Agent Categories

Organize agents using 0-category.json files:

{
  "name": "Category Name",
  "description": "Category description",
  "icon": "icon-name"
}

Best Practices

Agent Development

Single Responsibility: Each agent should have one clear purpose
Skill Composition: Leverage existing skills rather than duplicating knowledge
Clear Instructions: Provide explicit, step-by-step instructions
Error Handling: Include error handling and recovery strategies

Command Development

Modular Steps: Break commands into clear, sequential steps
Validation: Include validation checks at each step
Documentation: Document inputs, outputs, and side effects
Idempotency: Commands should be safe to run multiple times

Skill Development

Focused Scope: Keep skills focused on specific domains
Reference Materials: Include examples and reference documentation
Versioning: Track skill versions and changes
Testing: Test skills with multiple agents and scenarios

Common Workflows

Starting a New Project

# Initialize project
opencode init

# Generate project structure
opencode command design-system

# Set up development environment
opencode agent backend-specialist "Set up project structure"

Code Review Workflow

# Request code review
opencode command review

# Or use the code reviewer agent directly
opencode agent code-reviewer "Review recent changes"

Debugging Workflow

# Use systematic debugging
opencode command debug

# Or invoke debugging skill
opencode agent opencoder "Use systematic-debugging skill to fix issue"

Troubleshooting

Agent Not Found

Ensure agent file exists in agent/ directory and is properly formatted.

Skill Not Loading

Check:

Skill directory contains SKILL.md
Skill is referenced correctly in agent/command
File permissions are correct

Command Fails

Check command syntax in .md file
Verify all required inputs are provided
Review error logs in .opencode/ directory

Contributing

Adding New Agents

Create agent file in appropriate subdirectory
Follow naming convention: kebab-case.md
Include comprehensive documentation
Test with multiple scenarios

Adding New Skills

Use skill-creator skill as template
Include SKILL.md with clear documentation
Add reference materials and examples
Test with multiple agents

Submitting Changes

Fork the repository
Create feature branch
Make changes with clear commits
Submit pull request with description

Model Context Protocol (MCP)

What is MCP?

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to large language models (LLMs). It enables AI applications to connect with various data sources and tools in a consistent, structured manner.

MCP Architecture

MCP follows a client-server architecture:

MCP Hosts: Applications like AI assistants or IDEs (e.g., OpenCode CLI)
MCP Clients: Connectors within the host that maintain 1:1 connections with servers
MCP Servers: Services that provide context, tools, and capabilities through the standardized protocol

Available MCP Integrations

OpenCode CLI supports various MCP servers that extend AI capabilities:

1. Context7 MCP (`mcp_context7`)

Purpose: Up-to-date library documentation and code examples

Tools:

resolve-library-id: Find Context7-compatible library IDs (e.g., /mongodb/docs, /vercel/next.js)
query-docs: Query documentation with specific questions

Use Cases:

Getting latest API documentation
Finding code examples for libraries
Learning framework-specific patterns
Checking version-specific features

Example:

# First resolve library ID
resolve-library-id libraryName="next.js" query="Next.js documentation"

# Then query specific docs
query-docs libraryId="/vercel/next.js" query="How to use App Router in Next.js 15"

2. Exa Web Search MCP (`mcp_exa`)

Purpose: Advanced web search and research capabilities

Tools:

exa: General web search with clean, LLM-ready content
company_research_exa: Research companies and business information
crawling_exa: Extract content from specific URLs
get_code_context_exa: Find code examples and documentation
deep_researcher_start: Start AI research agent for complex topics
deep_researcher_check: Check research task status and results

Use Cases:

Finding current information and news
Researching companies and technologies
Extracting content from web pages
Finding code examples from GitHub/Stack Overflow
Deep research on complex topics

Example:

# Web search
exa query="Next.js 15 new features" numResults=5

# Code search
get_code_context_exa query="React Server Components examples" tokensNum=5000

# Deep research
deep_researcher_start instructions="Research best practices for microservices architecture"

3. Next.js DevTools MCP (`mcp_next_devtools`)

Purpose: Next.js development server integration and diagnostics

Tools:

init: Initialize Next.js DevTools context
nextjs_docs: Fetch official Next.js documentation
nextjs_index: Discover running Next.js dev servers and available tools
nextjs_call: Call specific MCP tools on running dev server
browser_eval: Browser automation for testing
upgrade_nextjs_16: Guide for upgrading to Next.js 16
enable_cache_components: Migrate to Cache Components mode

Use Cases:

Real-time Next.js error diagnostics
Querying running dev server state
Browser-based page verification
Next.js version upgrades
Cache Components migration

Example:

# Initialize
init project_path="."

# Get errors from running dev server
nextjs_index
nextjs_call port="3000" toolName="get_errors"

# Query Next.js docs
nextjs_docs path="/docs/app/api-reference/functions/refresh"

Configuring MCP Servers

MCP servers are configured in .kiro/settings/mcp.json (workspace-level) or ~/.kiro/settings/mcp.json (user-level):

{
  "mcpServers": {
    "context7": {
      "command": "uvx",
      "args": ["context7-mcp-server@latest"],
      "disabled": false,
      "autoApprove": ["resolve-library-id", "query-docs"]
    },
    "exa": {
      "command": "uvx",
      "args": ["exa-mcp-server@latest"],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      },
      "disabled": false
    }
  }
}

MCP Best Practices

Always call resolve-library-id before query-docs (Context7)
Limit MCP calls to 3 per question to avoid excessive API usage
Use specific queries - "How to set up JWT auth in Express" not just "auth"
Check dev server status before calling Next.js MCP tools
Use browser automation for real page verification (not curl)

Installing MCP Servers

Most MCP servers use uvx (Python package runner):

# Install uv (Python package manager)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Once installed, uvx will auto-download MCP servers on first use

Troubleshooting MCP

Server not connecting:

Check MCP config file syntax
Verify uvx is installed
Check server logs in OpenCode output

Tools not available:

Restart OpenCode after config changes
Check disabled: false in config
Verify API keys for services that require them

Performance issues:

Limit concurrent MCP calls
Use specific queries to reduce response size
Consider caching frequently accessed data

Resources

OpenCode Documentation: [Official Docs]
MCP Official Site: https://modelcontextprotocol.io
Agent Examples: See agent/ directory
Skill Examples: See skill/ directory
Command Examples: See command/ directory

License

See individual skill/component licenses in their respective directories.

Support

For issues and questions:

Open an issue on GitHub
Check existing documentation in docs/ directories
Review skill-specific README files
Visit MCP documentation for protocol-specific questions

Note: This template is designed to be customized for your specific needs. Feel free to add, remove, or modify agents, commands, and skills based on your workflow.

opencode-template

原始内容

OpenCode Template

What is OpenCode?

Quick Start

Prerequisites

Installation

Required Environment Variables

Basic Usage

Repository Structure

Core Components

Agents

Commands

Skills

Configuration

opencode.json

Creating Custom Components

Creating an Agent

Creating a Command

Creating a Skill

Advanced Features

Subagents

Agent Categories

Best Practices

Agent Development

Command Development

Skill Development

Common Workflows

Starting a New Project

Code Review Workflow

Debugging Workflow

Troubleshooting

Agent Not Found

Skill Not Loading

Command Fails

Contributing

Adding New Agents

Adding New Skills

Submitting Changes

Model Context Protocol (MCP)

What is MCP?

MCP Architecture

Available MCP Integrations

1. Context7 MCP (mcp_context7)

2. Exa Web Search MCP (mcp_exa)

3. Next.js DevTools MCP (mcp_next_devtools)

Configuring MCP Servers

MCP Best Practices

Installing MCP Servers

Troubleshooting MCP

Resources

License

Support

1. Context7 MCP (`mcp_context7`)

2. Exa Web Search MCP (`mcp_exa`)

3. Next.js DevTools MCP (`mcp_next_devtools`)