opencodekit 0.8.0 → 0.9.0

package/dist/template/.opencode/plugin/skill-mcp.ts

@@ -0,0 +1,458 @@
+import { type ChildProcess, spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { type Plugin, tool } from "@opencode-ai/plugin";
+
+interface McpServerConfig {
+	command: string;
+	args?: string[];
+	env?: Record<string, string>;
+}
+
+interface McpClient {
+	process: ChildProcess;
+	config: McpServerConfig;
+	requestId: number;
+	pendingRequests: Map<
+		number,
+		{ resolve: (v: any) => void; reject: (e: any) => void }
+	>;
+	capabilities?: {
+		tools?: any[];
+		resources?: any[];
+		prompts?: any[];
+	};
+}
+
+interface SkillMcpState {
+	clients: Map<string, McpClient>; // key: skillName:serverName
+	loadedSkills: Map<string, Record<string, McpServerConfig>>; // skillName -> mcp configs
+}
+
+function parseYamlFrontmatter(content: string): {
+	frontmatter: any;
+	body: string;
+} {
+	const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+	if (!match) return { frontmatter: {}, body: content };
+
+	const yamlStr = match[1];
+	const body = match[2];
+
+	// Simple YAML parser for our use case
+	const frontmatter: any = {};
+	let currentKey = "";
+	let currentIndent = 0;
+	let mcpConfig: any = null;
+	let serverName = "";
+	let serverConfig: any = {};
+
+	for (const line of yamlStr.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+
+		const indent = line.search(/\S/);
+		const keyMatch = trimmed.match(/^(\w+):\s*(.*)$/);
+
+		if (keyMatch) {
+			const [, key, value] = keyMatch;
+
+			if (indent === 0) {
+				// Top-level key
+				if (key === "mcp") {
+					mcpConfig = {};
+					frontmatter.mcp = mcpConfig;
+				} else {
+					frontmatter[key] = value || undefined;
+				}
+				currentKey = key;
+				currentIndent = indent;
+			} else if (mcpConfig !== null && indent === 2) {
+				// Server name under mcp
+				serverName = key;
+				serverConfig = {};
+				mcpConfig[serverName] = serverConfig;
+			} else if (serverConfig && indent === 4) {
+				// Server config property
+				if (key === "command") {
+					serverConfig.command = value;
+				} else if (key === "args") {
+					// Parse inline array or set up for multi-line
+					if (value.startsWith("[")) {
+						try {
+							serverConfig.args = JSON.parse(value);
+						} catch {
+							serverConfig.args = [];
+						}
+					} else {
+						serverConfig.args = [];
+					}
+				}
+			}
+		} else if (trimmed.startsWith("- ") && serverConfig?.args) {
+			// Array item for args
+			const item = trimmed.slice(2).replace(/^["']|["']$/g, "");
+			serverConfig.args.push(item);
+		}
+	}
+
+	return { frontmatter, body };
+}
+
+function findSkillPath(skillName: string, projectDir: string): string | null {
+	const locations = [
+		join(projectDir, ".opencode", "skill", skillName, "SKILL.md"),
+		join(homedir(), ".config", "opencode", "skill", skillName, "SKILL.md"),
+	];
+
+	for (const loc of locations) {
+		if (existsSync(loc)) return loc;
+	}
+	return null;
+}
+
+export const SkillMcpPlugin: Plugin = async ({ directory }) => {
+	const state: SkillMcpState = {
+		clients: new Map(),
+		loadedSkills: new Map(),
+	};
+
+	function getClientKey(skillName: string, serverName: string): string {
+		return `${skillName}:${serverName}`;
+	}
+
+	async function sendRequest(
+		client: McpClient,
+		method: string,
+		params?: any,
+	): Promise<any> {
+		return new Promise((resolve, reject) => {
+			const id = ++client.requestId;
+			const request = {
+				jsonrpc: "2.0",
+				id,
+				method,
+				params: params || {},
+			};
+
+			client.pendingRequests.set(id, { resolve, reject });
+
+			const timeout = setTimeout(() => {
+				client.pendingRequests.delete(id);
+				reject(new Error(`Request timeout: ${method}`));
+			}, 30000);
+
+			client.pendingRequests.set(id, {
+				resolve: (v) => {
+					clearTimeout(timeout);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(timeout);
+					reject(e);
+				},
+			});
+
+			client.process.stdin?.write(JSON.stringify(request) + "\n");
+		});
+	}
+
+	async function connectServer(
+		skillName: string,
+		serverName: string,
+		config: McpServerConfig,
+	): Promise<McpClient> {
+		const key = getClientKey(skillName, serverName);
+
+		// Return existing client if connected
+		const existing = state.clients.get(key);
+		if (existing && !existing.process.killed) {
+			return existing;
+		}
+
+		// Spawn MCP server process
+		const proc = spawn(config.command, config.args || [], {
+			stdio: ["pipe", "pipe", "pipe"],
+			env: { ...process.env, ...config.env },
+			shell: true,
+		});
+
+		const client: McpClient = {
+			process: proc,
+			config,
+			requestId: 0,
+			pendingRequests: new Map(),
+		};
+
+		// Handle stdout (JSON-RPC responses)
+		let buffer = "";
+		proc.stdout?.on("data", (data) => {
+			buffer += data.toString();
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+
+			for (const line of lines) {
+				if (!line.trim()) continue;
+				try {
+					const response = JSON.parse(line);
+					if (response.id !== undefined) {
+						const pending = client.pendingRequests.get(response.id);
+						if (pending) {
+							client.pendingRequests.delete(response.id);
+							if (response.error) {
+								pending.reject(new Error(response.error.message));
+							} else {
+								pending.resolve(response.result);
+							}
+						}
+					}
+				} catch {}
+			}
+		});
+
+		proc.on("error", (err) => {
+			console.error(`MCP server error [${key}]:`, err.message);
+		});
+
+		proc.on("exit", (code) => {
+			state.clients.delete(key);
+		});
+
+		state.clients.set(key, client);
+
+		// Initialize connection
+		try {
+			await sendRequest(client, "initialize", {
+				protocolVersion: "2024-11-05",
+				capabilities: {},
+				clientInfo: { name: "opencode-skill-mcp", version: "1.0.0" },
+			});
+
+			// Send initialized notification
+			proc.stdin?.write(
+				JSON.stringify({
+					jsonrpc: "2.0",
+					method: "notifications/initialized",
+				}) + "\n",
+			);
+
+			// Discover capabilities
+			try {
+				const toolsResult = await sendRequest(client, "tools/list", {});
+				client.capabilities = { tools: toolsResult.tools || [] };
+			} catch {
+				client.capabilities = { tools: [] };
+			}
+		} catch (e: any) {
+			proc.kill();
+			state.clients.delete(key);
+			throw new Error(`Failed to initialize MCP server: ${e.message}`);
+		}
+
+		return client;
+	}
+
+	function disconnectAll() {
+		for (const [key, client] of state.clients) {
+			client.process.kill();
+		}
+		state.clients.clear();
+	}
+
+	return {
+		tool: {
+			skill_mcp: tool({
+				description: `Invoke MCP tools from skill-embedded MCP servers.
+
+When a skill declares MCP servers in its YAML frontmatter, use this tool to:
+- List available tools: skill_mcp(skill_name="playwright", list_tools=true)
+- Call a tool: skill_mcp(skill_name="playwright", tool_name="browser_navigate", arguments='{"url": "..."}')
+
+The skill must be loaded first via the skill() tool to register its MCP config.`,
+				args: {
+					skill_name: tool.schema
+						.string()
+						.describe("Name of the loaded skill with MCP config"),
+					mcp_name: tool.schema
+						.string()
+						.optional()
+						.describe("Specific MCP server name (if skill has multiple)"),
+					list_tools: tool.schema
+						.boolean()
+						.optional()
+						.describe("List available tools from this MCP"),
+					tool_name: tool.schema
+						.string()
+						.optional()
+						.describe("MCP tool to invoke"),
+					arguments: tool.schema
+						.string()
+						.optional()
+						.describe("JSON string of tool arguments"),
+				},
+				async execute(args) {
+					const {
+						skill_name,
+						mcp_name,
+						list_tools,
+						tool_name,
+						arguments: argsJson,
+					} = args;
+
+					if (!skill_name) {
+						return JSON.stringify({ error: "skill_name required" });
+					}
+
+					// Find skill and parse its MCP config
+					const skillPath = findSkillPath(skill_name, directory);
+					if (!skillPath) {
+						return JSON.stringify({ error: `Skill '${skill_name}' not found` });
+					}
+
+					const content = readFileSync(skillPath, "utf-8");
+					const { frontmatter } = parseYamlFrontmatter(content);
+
+					if (!frontmatter.mcp || Object.keys(frontmatter.mcp).length === 0) {
+						return JSON.stringify({
+							error: `Skill '${skill_name}' has no MCP config`,
+						});
+					}
+
+					// Determine which MCP server to use
+					const mcpServers = frontmatter.mcp as Record<string, McpServerConfig>;
+					const serverNames = Object.keys(mcpServers);
+					const targetServer = mcp_name || serverNames[0];
+
+					if (!mcpServers[targetServer]) {
+						return JSON.stringify({
+							error: `MCP server '${targetServer}' not found in skill`,
+							available: serverNames,
+						});
+					}
+
+					const serverConfig = mcpServers[targetServer];
+
+					// Connect to MCP server
+					let client: McpClient;
+					try {
+						client = await connectServer(
+							skill_name,
+							targetServer,
+							serverConfig,
+						);
+					} catch (e: any) {
+						return JSON.stringify({ error: `Failed to connect: ${e.message}` });
+					}
+
+					// List tools
+					if (list_tools) {
+						return JSON.stringify(
+							{
+								mcp: targetServer,
+								tools:
+									client.capabilities?.tools?.map((t: any) => ({
+										name: t.name,
+										description: t.description,
+										schema: t.inputSchema,
+									})) || [],
+							},
+							null,
+							2,
+						);
+					}
+
+					// Call tool
+					if (tool_name) {
+						let toolArgs = {};
+						if (argsJson) {
+							try {
+								toolArgs = JSON.parse(argsJson);
+							} catch (e) {
+								return JSON.stringify({ error: "Invalid JSON in arguments" });
+							}
+						}
+
+						try {
+							const result = await sendRequest(client, "tools/call", {
+								name: tool_name,
+								arguments: toolArgs,
+							});
+							return JSON.stringify({ result }, null, 2);
+						} catch (e: any) {
+							return JSON.stringify({
+								error: `Tool call failed: ${e.message}`,
+							});
+						}
+					}
+
+					return JSON.stringify({
+						error: "Specify either list_tools=true or tool_name to call",
+						mcp: targetServer,
+						available_tools:
+							client.capabilities?.tools?.map((t: any) => t.name) || [],
+					});
+				},
+			}),
+
+			skill_mcp_status: tool({
+				description: "Show status of connected MCP servers from skills.",
+				args: {},
+				async execute() {
+					const servers: any[] = [];
+					for (const [key, client] of state.clients) {
+						const [skillName, serverName] = key.split(":");
+						servers.push({
+							skill: skillName,
+							server: serverName,
+							connected: !client.process.killed,
+							tools: client.capabilities?.tools?.length || 0,
+						});
+					}
+					return JSON.stringify({
+						connected_servers: servers,
+						count: servers.length,
+					});
+				},
+			}),
+
+			skill_mcp_disconnect: tool({
+				description:
+					"Disconnect MCP servers. Use when done with browser automation etc.",
+				args: {
+					skill_name: tool.schema
+						.string()
+						.optional()
+						.describe("Specific skill to disconnect (all if omitted)"),
+				},
+				async execute(args) {
+					if (args.skill_name) {
+						const toDisconnect: string[] = [];
+						for (const key of state.clients.keys()) {
+							if (key.startsWith(args.skill_name + ":")) {
+								toDisconnect.push(key);
+							}
+						}
+						for (const key of toDisconnect) {
+							const client = state.clients.get(key);
+							client?.process.kill();
+							state.clients.delete(key);
+						}
+						return JSON.stringify({ disconnected: toDisconnect });
+					} else {
+						const count = state.clients.size;
+						disconnectAll();
+						return JSON.stringify({ disconnected: "all", count });
+					}
+				},
+			}),
+		},
+
+		event: async ({ event }) => {
+			// Cleanup on session idle (closest available event)
+			if (event.type === "session.idle") {
+				// Optional: could disconnect idle servers here
+			}
+		},
+	};
+};

package/dist/template/.opencode/skill/figma/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: figma
+description: Access Figma design data via Framelink MCP. Fetch layout, styles, components from Figma files/frames. Use when implementing UI from Figma designs, extracting design tokens, or downloading assets.
+mcp:
+  figma:
+    command: npx
+    args: ["-y", "figma-developer-mcp", "--stdio"]
+    env:
+      FIGMA_API_KEY: "${FIGMA_API_KEY}"
+---
+
+# Figma Design Data (MCP)
+
+Access Figma design data via the Framelink MCP server. When this skill is loaded, the `figma` MCP server auto-starts and exposes tools to fetch design data and download images.
+
+## Prerequisites
+
+Set your Figma API key as an environment variable:
+
+```bash
+export FIGMA_API_KEY="your-figma-personal-access-token"
+```
+
+To create a Figma Personal Access Token:
+
+1. Go to Figma → Settings → Account → Personal access tokens
+2. Create a new token with read access
+3. See: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
+
+## Quick Start
+
+After loading this skill, use `skill_mcp` to invoke Figma tools:
+
+```
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "1234:5678"}')
+```
+
+## Available Tools
+
+### get_figma_data
+
+Fetch comprehensive Figma file data including layout, content, visuals, and component information.
+
+| Parameter | Type   | Required | Description                                                                                       |
+| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `fileKey` | string | Yes      | The Figma file key (from URL: `figma.com/file/<fileKey>/...` or `figma.com/design/<fileKey>/...`) |
+| `nodeId`  | string | No       | Specific node ID (from URL param `node-id=<nodeId>`). Format: `1234:5678` or `1234-5678`          |
+| `depth`   | number | No       | Levels deep to traverse. Only use if explicitly requested by user.                                |
+
+**Returns:** YAML-formatted design data with:
+
+- `metadata` - File/node information
+- `nodes` - Simplified node tree with layout, styles, text content
+- `globalVars` - Shared styles and variables
+
+### download_figma_images
+
+Download SVG and PNG images/icons from a Figma file.
+
+| Parameter   | Type   | Required | Description                                   |
+| ----------- | ------ | -------- | --------------------------------------------- |
+| `fileKey`   | string | Yes      | The Figma file key                            |
+| `nodes`     | array  | Yes      | Array of node objects to download (see below) |
+| `localPath` | string | Yes      | Absolute path to save images                  |
+| `pngScale`  | number | No       | Export scale for PNGs (default: 2)            |
+
+**Node object structure:**
+
+```json
+{
+  "nodeId": "1234:5678",
+  "fileName": "icon-name.svg",
+  "imageRef": "optional-for-image-fills"
+}
+```
+
+## Workflow
+
+### 1. Extract File Key and Node ID from Figma URL
+
+Figma URLs follow these patterns:
+
+- `https://www.figma.com/file/<fileKey>/<fileName>?node-id=<nodeId>`
+- `https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>`
+
+Example: `https://www.figma.com/design/abc123xyz/MyDesign?node-id=1234-5678`
+
+- `fileKey`: `abc123xyz`
+- `nodeId`: `1234-5678` (or `1234:5678` - both formats work)
+
+### 2. Fetch Design Data
+
+```
+# Fetch specific frame/component
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz", "nodeId": "1234:5678"}')
+
+# Fetch entire file (use sparingly - can be large)
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz"}')
+```
+
+### 3. Download Assets (Optional)
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "abc123xyz",
+  "nodes": [
+    {"nodeId": "1234:5678", "fileName": "hero-image.png"},
+    {"nodeId": "5678:9012", "fileName": "icon-arrow.svg"}
+  ],
+  "localPath": "/absolute/path/to/assets"
+}')
+```
+
+## Examples
+
+### Implement a Component from Figma
+
+```
+# User provides: https://www.figma.com/design/abc123/Dashboard?node-id=100-200
+
+# 1. Fetch the design data
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "100-200"}')
+
+# 2. Review the returned YAML for:
+#    - Layout structure (flex, grid, spacing)
+#    - Typography (font, size, weight, line-height)
+#    - Colors (fills, strokes)
+#    - Dimensions and constraints
+
+# 3. Implement the component using the extracted data
+```
+
+### Extract Design Tokens
+
+```
+# Fetch a design system file
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "designSystemKey"}')
+
+# The globalVars section contains:
+# - Color styles
+# - Typography styles
+# - Effect styles (shadows, blurs)
+```
+
+### Download Icons
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "iconLibraryKey",
+  "nodes": [
+    {"nodeId": "10:20", "fileName": "icon-home.svg"},
+    {"nodeId": "10:30", "fileName": "icon-settings.svg"},
+    {"nodeId": "10:40", "fileName": "icon-user.svg"}
+  ],
+  "localPath": "/project/src/assets/icons",
+  "pngScale": 2
+}')
+```
+
+## Data Structure
+
+The `get_figma_data` tool returns simplified, AI-optimized data:
+
+```yaml
+metadata:
+  name: "Component Name"
+  lastModified: "2024-01-15T..."
+
+nodes:
+  - id: "1234:5678"
+    name: "Button"
+    type: "FRAME"
+    layout:
+      mode: "HORIZONTAL"
+      padding: { top: 12, right: 24, bottom: 12, left: 24 }
+      gap: 8
+    size: { width: 120, height: 48 }
+    fills:
+      - type: "SOLID"
+        color: { r: 0.2, g: 0.4, b: 1, a: 1 }
+    cornerRadius: 8
+    children:
+      - id: "1234:5679"
+        name: "Label"
+        type: "TEXT"
+        content: "Click me"
+        textStyle:
+          fontFamily: "Inter"
+          fontSize: 16
+          fontWeight: 600
+
+globalVars:
+  styles:
+    "S:abc123": { name: "Primary", fills: [...] }
+```
+
+## Tips
+
+- **Always use nodeId** when provided - fetching entire files is slow and context-heavy
+- **Node IDs with `-` or `:`** both work - the MCP handles conversion
+- **Check globalVars** for reusable styles before hardcoding values
+- **Use depth parameter sparingly** - only when explicitly needed
+- **For images/icons**, identify nodes with `imageRef` in the data for proper downloading
+- **SVG vs PNG**: Use `.svg` for icons/vectors, `.png` for photos/complex images
+
+## Troubleshooting
+
+**"Invalid API key"**: Ensure `FIGMA_API_KEY` environment variable is set correctly.
+
+**"File not found"**: Verify the fileKey is correct and you have access to the file.
+
+**"Node not found"**: Check the nodeId format. Try both `1234:5678` and `1234-5678`.
+
+**Large response**: Use `nodeId` to fetch specific frames instead of entire files.