sync-mcps

name	sync-mcps
description	Synchronize and generate documentation for OpenCode MCP servers from opencode.json configuration. Use when the user wants to sync their MCP servers, generate MCP documentation, or view their configured MCP servers.
license	MIT
compatibility	Reads opencode.json from user's home directory (~/.config/opencode/opencode.json).
metadata	{"author":"hadenlabs","version":"0.1.0"}

Synchronize MCP servers and generate documentation from opencode.json configuration.

Input: None required. The skill reads directly from ~/.config/opencode/opencode.json.

Steps

1. Read the opencode.json configuration

   Read the file at ~/.config/opencode/opencode.json and extract the mcp object. Each MCP is an object with properties:

   • type: "local" or "remote"
   • command: array (for local) - e.g., ["bunx", "-y", "@modelcontextprotocol/server-github"]
   • url: string (for remote) - e.g., "https://mcp.context7.com/mcp"
   • enabled: boolean
   • environment: object with env vars (optional)

2. Parse each MCP entry

   For each MCP in the mcp object:

   • Get the MCP ID (key) from the object
   • Extract type (local/remote)
   • For local: extract command array and join with spaces
   • For remote: extract url
   • Extract enabled boolean
   • Extract environment object (if present)

3. Determine purpose based on MCP name

   Map MCP names to their purpose:

   • github → GitHub API access (issues/PRs/repos)
   • filesystem → Filesystem read/write
   • context7 → On-demand documentation (Context7)
   • sequential-thinking → Step-by-step reasoning tools
   • grafana → Grafana queries and operations
   • jira → Jira access
   • image-compression → Image compression
   • hashicorp.terraform → Terraform assistance
   • awslabs.aws-knowledge → AWS knowledge
   • awslabs.aws-terraform → Terraform assistance (awslabs)
   • serena → Code indexing/navigation (Serena)
   • obsidian → Obsidian vault access
   • playwright → Browser automation
   • notebooklm → NotebookLM access
   • notion → Notion access
   • supabase → Supabase database access
   • sentry → Sentry error tracking
   • kubernetes → Kubernetes cluster access
   • gitlab → GitLab API access
   • bitbucket → Bitbucket API access
   • docker → Docker operations
   • chrome-devtools → Chrome DevTools
   • grep → Code search
   • engram → Memory/knowledge management
   • Default: Use the MCP name as purpose with "MCP server" suffix

4. Determine requirements based on command

   Map commands to requirements:

   • Contains npx → "Node.js + npx"
   • Contains bunx → "Bun + bunx"
   • Contains uvx → "uvx (UV) + Python"
   • Contains docker → "Docker"
   • Contains /opt/homebrew → "Homebrew installed"
   • URL-based (remote) → "internet access"
   • Default: "See command for requirements"

5. Generate documentation for each MCP

   Use the following template for each MCP:

   <!-- Space: Projects -->
   <!-- Parent: ZshAI -->
   <!-- Title: MCP - {mcp_id} -->
   <!-- Label: OpenCode -->
   <!-- Include: docs/disclaimer.md -->
   
   # `{mcp_id}`
   
   - Type: {local|remote}
   - Command: `{command_array_joined}` (for local)
   - URL: `{url}` (for remote)
   - Enabled: {yes|no}
   - What it does: {purpose}
   - Requirements: {requirements}
   
   ## Environment Variables
   
   {environment_variables_list}
   
   ---
   
   *Auto-generated by sync-mcps skill*
   

   Where:

   • {mcp_id} is the MCP identifier from the JSON key
   • {local|remote} is the type value
   • {command_array_joined} is the command array joined with spaces (for local)
   • {url} is the URL string (for remote)
   • {yes|no} is "yes" if enabled, "no" otherwise
   • {purpose} is the determined purpose based on MCP name
   • {requirements} is the determined requirements based on command
   • {environment_variables_list} is a formatted list of environment variables or "None" if not present

6. Write MCP files to disk

   For each MCP, write a markdown file to docs/opencode/mcp/:

   • Directory: docs/opencode/mcp/
   • Filename: {mcp_id}.md (the MCP identifier as filename)
   • Examples:
     • github → github.md
     • hashicorp.terraform → hashicorp.terraform.md
     • awslabs.aws-knowledge → awslabs.aws-knowledge.md

   Create the directory if it does not exist. The skill is idempotent - existing files are overwritten.

7. Generate and update index.md

   Regenerate docs/opencode/mcp/index.md with a table of all MCPs.

   Template:

   <!-- Space: Projects -->
   <!-- Parent: ZshAI -->
   <!-- Title: MCP servers (OpenCode) -->
   <!-- Label: OpenCode -->
   <!-- Include: docs/disclaimer.md -->
   <!-- Include: ac:toc -->
   
   # MCP servers (OpenCode)
   
   This section describes the MCP (Model Context Protocol) servers configured in OpenCode and what each one is used for.
   
   ## Overview
   
   | MCP id | Type | Purpose | Enabled | Requirements | Details |
   | --- | --- | --- | :-: | --- | --- |
   {table_rows}
   
   ## Quick troubleshooting
   
   - If a local MCP server does not start, verify dependencies (uvx/Node/Docker as applicable).
   - If a remote MCP server fails, verify connectivity/network and the relevant `*_URL` variables.
   - If `github`/`grafana`/`jira` fail with 401/403, review tokens and permissions.
   
   ---
   *Auto-generated by sync-mcps skill*
   

   Where {table_rows} is:

   | `{mcp_id}` | {local|remote} | {purpose} | {yes|no} | {requirements} | `docs/opencode/mcp/{mcp_id}.md` |
   

8. Output all generated documentation

   Display all MCP documentation blocks sequentially (stdout fallback for visibility).

Output

## OpenCode MCP Servers Documentation

Generated from: ~/.config/opencode/opencode.json
Total MCPs: N
Files written: docs/opencode/mcp/{mcp_id}.md (N files)
Index updated: docs/opencode/mcp/index.md

---

[Generated documentation for each MCP...]

---
*Auto-generated by sync-mcps skill*

Guardrails

• If ~/.config/opencode/opencode.json does not exist, show an error message: "Error: ~/.config/opencode/opencode.json not found. Please ensure OpenCode is configured."
• If the mcp object is empty or missing, show a message: "No MCP servers configured in opencode.json"
• Handle both local (command) and remote (url) MCP types
• Create docs/opencode/mcp/ directory if it does not exist
• Overwrite existing files to ensure idempotency
• Always show the generation date in ISO format (YYYY-MM-DD)
• Handle MCPs without environment variables (show "None" for environment variables section)
• Handle MCPs without explicit type (default to "local" if command exists, "remote" if url exists)

MCP Name to Purpose Mapping Summary

MCP ID	Purpose
github	GitHub API access (issues/PRs/repos)
filesystem	Filesystem read/write
context7	On-demand documentation (Context7)
sequential-thinking	Step-by-step reasoning tools
grafana	Grafana queries and operations
jira	Jira access
image-compression	Image compression
hashicorp.terraform	Terraform assistance
awslabs.aws-knowledge	AWS knowledge
awslabs.aws-terraform	Terraform assistance (awslabs)
serena	Code indexing/navigation (Serena)
obsidian	Obsidian vault access
playwright	Browser automation
notebooklm	NotebookLM access
notion	Notion access
supabase	Supabase database access
sentry	Sentry error tracking
kubernetes	Kubernetes cluster access
gitlab	GitLab API access
bitbucket	Bitbucket API access
docker	Docker operations
chrome-devtools	Chrome DevTools
grep	Code search
engram	Memory/knowledge management
{other}	{other} MCP server

Requirements Based on Command Summary

Command contains	Requirements
npx	Node.js + npx
bunx	Bun + bunx
uvx	uvx (UV) + Python
docker	Docker
/opt/homebrew	Homebrew installed
URL-based	internet access