opencode-lazy-loader 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 keybrdist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# OpenCode Lazy Loader Plugin
+
+This is the OpenCode plugin that lazy-loads skill-embedded MCP servers. It lets skills bundle their own MCP servers so they can be loaded on-demand instead of being configured globally.
+
+Note: This package was renamed from `opencode-embedded-skill-mcp` to `opencode-lazy-loader`. If you still have the old package, upgrade to the new name.
+
+This is a standalone OpenCode plugin that enables skills to bundle and manage their own [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers, then lazy-load them on demand.
+
+This allows skills to bring their own tools, resources, and prompts without requiring manual server configuration in `opencode.json`.
+
+## Why use this?
+
+- **Plug-and-Play Skills**: Skills bring their own tools. No need to manually register servers in your global config.
+- **Cleaner Context**: Tools are loaded on-demand only when the skill is active, keeping your agent's context window focused and efficient.
+- **Team Portability**: Commit skills to your project repo; anyone with the plugin gets the tools automatically.
+- **Efficient Resources**: Servers start only when used and shut down automatically after 5 minutes of inactivity.
+
+---
+
+## Technical Features
+
+- **Skill-Embedded MCPs**: Configure MCP servers directly within skill definitions (markdown frontmatter or `mcp.json`).
+- **Zero Configuration**: Skills manage their own MCP connections; just load the skill and use the tools.
+- **Connection Management**:
+  - Connection pooling per session/skill/server.
+  - Lazy connection initialization (connects on first use).
+  - Automatic idle cleanup (disconnects after 5 minutes of inactivity).
+  - Session-scoped resource cleanup.
+- **Environment Variable Support**: Full support for `${VAR}` and `${VAR:-default}` expansion in MCP configurations.
+
+## Installation
+
+Deprecation notice: The package was renamed from `opencode-embedded-skill-mcp` to `opencode-lazy-loader`. If you installed the old name, update to the new package.
+
+Add the plugin to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-lazy-loader"]
+}
+```
+
+Or install it locally:
+
+```json
+{
+  "plugin": ["./path/to/opencode-lazy-loader"]
+}
+```
+
+## Usage
+
+### 1. Create a Skill with Embedded MCP
+
+You can define MCP servers in the skill's YAML frontmatter:
+
+**`~/.config/opencode/skill/my-skill/SKILL.md`**
+
+```markdown
+---
+name: browser-automation
+description: "A skill for automating browser interactions"
+mcp:
+  playwright:
+    command: ["npx", "-y", "@playwright/mcp@latest"]
+---
+
+# Browser Automation
+
+This skill provides browser automation tools via the `playwright` MCP.
+```
+
+Alternatively, place an `mcp.json` file in the skill directory:
+
+**`~/.config/opencode/skill/browser-automation/mcp.json`**
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": ["npx", "-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+### 2. Load the Skill
+
+In OpenCode:
+
+```
+skill(name="browser-automation")
+```
+
+**Pro Tip:** You don't always need to call the tool explicitly. Just ask for the skill by name in chat, and OpenCode will usually find and load it for you:
+
+> "Use the browser-automation skill to take a screenshot of google.com"
+
+The plugin will load the skill and discover the capabilities of the embedded MCP server.
+
+### 3. Use MCP Tools
+
+Invoke tools, read resources, or get prompts using `skill_mcp`:
+
+```
+skill_mcp(mcp_name="playwright", tool_name="screenshot", arguments='{"url": "https://google.com"}')
+```
+
+## Tools Provided
+
+### `skill`
+
+Loads a skill and displays its instructions along with any available MCP capabilities (tools, resources, prompts).
+
+- **name**: The name of the skill to load.
+
+### `skill_mcp`
+
+Invokes an operation on a skill-embedded MCP server.
+
+- **mcp_name**: The name of the MCP server (defined in the skill config).
+- **tool_name**: (Optional) The name of the tool to call.
+- **resource_name**: (Optional) The URI of the resource to read.
+- **prompt_name**: (Optional) The name of the prompt to get.
+- **arguments**: (Optional) JSON string of arguments for the operation.
+- **grep**: (Optional) Regex pattern to filter the output.
+
+## Configuration Format
+
+The MCP configuration supports the standard format:
+
+```typescript
+interface McpServerConfig {
+  command: string | string[];          // Command to execute (array recommended for args)
+  environment?: Record<string, string> // Environment variables
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "opencode-lazy-loader",
+  "version": "1.0.0",
+  "description": "OpenCode plugin for lazy-loading skill-embedded MCP servers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "mcp",
+    "skill"
+  ],
+  "author": "keybrdist",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keybrdist/opencode-lazy-loader.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@opencode-ai/plugin": "^1.1.23",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}