@hienlh/ppm 0.9.81 → 0.9.82

package/.opencode/skills/mcp-management/references/configuration.md

@@ -1,114 +0,0 @@
-# MCP Configuration Guide
-
-## Configuration File Structure
-
-MCP servers are configured in `.opencode/.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "server-name": {
-      "command": "executable",
-      "args": ["arg1", "arg2"],
-      "env": {
-        "API_KEY": "value"
-      }
-    }
-  }
-}
-```
-
-## Common Server Configurations
-
-### Memory Server
-
-Store and retrieve key-value data:
-
-```json
-{
-  "memory": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-memory"]
-  }
-}
-```
-
-### Filesystem Server
-
-File operations with restricted access:
-
-```json
-{
-  "filesystem": {
-    "command": "npx",
-    "args": [
-      "-y",
-      "@modelcontextprotocol/server-filesystem",
-      "/allowed/path"
-    ]
-  }
-}
-```
-
-### Brave Search Server
-
-Web search capabilities:
-
-```json
-{
-  "brave-search": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
-    "env": {
-      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
-    }
-  }
-}
-```
-
-### Puppeteer Server
-
-Browser automation:
-
-```json
-{
-  "puppeteer": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
-  }
-}
-```
-
-## Environment Variables
-
-Reference env vars with `${VAR_NAME}` syntax:
-
-```json
-{
-  "api-server": {
-    "command": "node",
-    "args": ["server.js"],
-    "env": {
-      "API_KEY": "${MY_API_KEY}",
-      "BASE_URL": "${API_BASE_URL}"
-    }
-  }
-}
-```
-
-## Configuration Loading Order
-
-Scripts check for config in this order:
-
-1. `process.env` (runtime environment)
-2. `.opencode/skills/mcp-management/.env`
-3. `.opencode/skills/.env`
-4. `.opencode/.env`
-
-## Validation
-
-Config must:
-- Be valid JSON
-- Include `mcpServers` object
-- Each server must have `command` and `args`
-- `env` is optional but must be object if present

package/.opencode/skills/mcp-management/references/gemini-cli-integration.md

@@ -1,215 +0,0 @@
-# Gemini CLI Integration Guide
-
-## ⚠️ CRITICAL: Use Stdin Piping, NOT -p Flag
-
-The `-p` flag is **deprecated** and skips MCP server initialization, causing tools to be unavailable:
-
-```bash
-# ❌ WRONG - This skips MCP connections!
-gemini -y -m gemini-2.5-flash -p "Take a screenshot"
-
-# ✅ CORRECT - This initializes MCP servers
-echo "Take a screenshot" | gemini -y -m gemini-2.5-flash
-```
-
-**Why**: The `-p` flag runs in "quick mode" and bypasses MCP server connection initialization. Always use stdin piping (echo + pipe) to ensure MCP tools are available.
-
-## Overview
-
-Gemini CLI provides automatic MCP tool discovery and execution via natural language prompts. This is the recommended primary method for executing MCP tools.
-
-## Installation
-
-```bash
-npm install -g gemini-cli
-```
-
-Verify installation:
-```bash
-gemini --version
-```
-
-## Configuration
-
-### Symlink Setup
-
-Gemini CLI reads MCP servers from `.gemini/settings.json`. Create a symlink to `.opencode/.mcp.json`:
-
-```bash
-# Create .gemini directory
-mkdir -p .gemini
-
-# Create symlink (Unix/Linux/macOS)
-ln -sf .opencode/.mcp.json .gemini/settings.json
-
-# Create symlink (Windows - requires admin or developer mode)
-mklink .gemini\settings.json .claude\.mcp.json
-```
-
-### Security
-
-Add to `.gitignore`:
-```
-.gemini/settings.json
-```
-
-This prevents committing sensitive API keys and server configurations.
-
-## Usage
-
-### Basic Syntax
-
-```bash
-# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
-echo "<prompt>" | gemini [flags]
-```
-
-### Essential Flags
-
-- `-y`: Skip confirmation prompts (auto-approve tool execution)
-- `-m <model>`: Model selection
-  - `gemini-2.5-flash` (fast, recommended for MCP)
-  - `gemini-2.5-flash` (balanced)
-  - `gemini-pro` (high quality)
-
-### Examples
-
-**Screenshot Capture**:
-```bash
-echo "Take a screenshot of https://www.google.com.vn" | gemini -y -m gemini-2.5-flash
-```
-
-**Memory Operations**:
-```bash
-echo "Remember that Alice is a React developer working on e-commerce projects" | gemini -y -m gemini-2.5-flash
-```
-
-**Web Research**:
-```bash
-echo "Search for latest Next.js 15 features and summarize the top 3" | gemini -y -m gemini-2.5-flash
-```
-
-**Multi-Tool Orchestration**:
-```bash
-echo "Search for Claude AI documentation, take a screenshot of the homepage, and save both to memory" | gemini -y -m gemini-2.5-flash
-```
-
-**Browser Automation**:
-```bash
-echo "Navigate to https://example.com, click the signup button, and take a screenshot" | gemini -y -m gemini-2.5-flash
-```
-
-## How It Works
-
-1. **Configuration Loading**: Reads `.gemini/settings.json` (symlinked to `.opencode/.mcp.json`)
-2. **Server Connection**: Connects to all configured MCP servers
-3. **Tool Discovery**: Lists all available tools from servers
-4. **Prompt Analysis**: Gemini model analyzes the prompt
-5. **Tool Selection**: Automatically selects relevant tools
-6. **Execution**: Calls tools with appropriate parameters
-7. **Result Synthesis**: Combines tool outputs into coherent response
-
-## Advanced Configuration
-
-### Trusted Servers (Skip Confirmations)
-
-Edit `.opencode/.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-memory"],
-      "trust": true
-    }
-  }
-}
-```
-
-With `trust: true`, the `-y` flag is unnecessary.
-
-### Tool Filtering
-
-Limit tool exposure:
-
-```json
-{
-  "mcpServers": {
-    "chrome-devtools": {
-      "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"],
-      "includeTools": ["navigate_page", "screenshot"],
-      "excludeTools": ["evaluate_js"]
-    }
-  }
-}
-```
-
-### Environment Variables
-
-Use `$VAR_NAME` syntax for sensitive data:
-
-```json
-{
-  "mcpServers": {
-    "brave-search": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
-      "env": {
-        "BRAVE_API_KEY": "$BRAVE_API_KEY"
-      }
-    }
-  }
-}
-```
-
-## Troubleshooting
-
-### Check MCP Status
-
-```bash
-gemini
-> /mcp
-```
-
-Shows:
-- Connected servers
-- Available tools
-- Configuration errors
-
-### Verify Symlink
-
-```bash
-# Unix/Linux/macOS
-ls -la .gemini/settings.json
-
-# Windows
-dir .gemini\settings.json
-```
-
-Should show symlink pointing to `.opencode/.mcp.json`.
-
-### Debug Mode
-
-```bash
-echo "Take a screenshot" | gemini --debug
-```
-
-Shows detailed MCP communication logs.
-
-## Comparison with Alternatives
-
-| Method | Speed | Flexibility | Setup | Best For |
-|--------|-------|-------------|-------|----------|
-| Gemini CLI | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | All tasks |
-| Direct Scripts | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | Specific tools |
-| mcp-manager | ⭐ | ⭐⭐ | ⭐⭐⭐ | Fallback |
-
-**Recommendation**: Use Gemini CLI as primary method, fallback to scripts/subagent when unavailable.
-
-## Resources
-
-- [Gemini CLI Documentation](https://geminicli.com/docs)
-- [MCP Server Configuration](https://geminicli.com/docs/tools/mcp-server)
-- [Tool Reference](https://geminicli.com/docs/tools/mcp-server/#tool-interaction)

package/.opencode/skills/mcp-management/references/mcp-protocol.md

@@ -1,116 +0,0 @@
-# Model Context Protocol (MCP) Reference
-
-## Protocol Overview
-
-MCP is JSON-RPC 2.0 based protocol for AI-tool integration.
-
-**Version**: 2025-03-26
-**Foundation**: JSON-RPC 2.0
-**Architecture**: Client-Host-Server
-
-## Connection Lifecycle
-
-1. **Initialize**: Client sends `initialize` request with capabilities
-2. **Response**: Server responds with its capabilities
-3. **Handshake**: Client sends `notifications/initialized`
-4. **Active**: Bidirectional messaging
-5. **Shutdown**: Close connections, cleanup
-
-## Core Capabilities
-
-### Tools (Executable Functions)
-
-Tools are functions that servers expose for execution.
-
-**List Tools**:
-```json
-{"method": "tools/list"}
-```
-
-**Call Tool**:
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "tool_name",
-    "arguments": {}
-  }
-}
-```
-
-### Prompts (Interaction Templates)
-
-Prompts are reusable templates for LLM interactions.
-
-**List Prompts**:
-```json
-{"method": "prompts/list"}
-```
-
-**Get Prompt**:
-```json
-{
-  "method": "prompts/get",
-  "params": {
-    "name": "prompt_name",
-    "arguments": {}
-  }
-}
-```
-
-### Resources (Data Sources)
-
-Resources expose read-only data to clients.
-
-**List Resources**:
-```json
-{"method": "resources/list"}
-```
-
-**Read Resource**:
-```json
-{
-  "method": "resources/read",
-  "params": {"uri": "resource://path"}
-}
-```
-
-## Transport Types
-
-### stdio (Local)
-
-Server runs as subprocess. Messages via stdin/stdout.
-
-```typescript
-const transport = new StdioClientTransport({
-  command: 'node',
-  args: ['server.js']
-});
-```
-
-### HTTP+SSE (Remote)
-
-POST for requests, GET for server events.
-
-```typescript
-const transport = new StreamableHTTPClientTransport({
-  url: 'http://localhost:3000/mcp'
-});
-```
-
-## Error Codes
-
-- **-32700**: Parse error
-- **-32600**: Invalid request
-- **-32601**: Method not found
-- **-32602**: Invalid params
-- **-32603**: Internal error
-- **-32002**: Resource not found (MCP-specific)
-
-## Best Practices
-
-1. **Progressive Disclosure**: Load tool definitions on-demand
-2. **Context Efficiency**: Filter data before returning
-3. **Security**: Validate inputs, sanitize outputs
-4. **Resource Management**: Cleanup connections properly
-5. **Error Handling**: Handle all error cases gracefully

package/.opencode/skills/mcp-management/scripts/.env.example

@@ -1,10 +0,0 @@
-# MCP Management Scripts Environment Variables
-
-# Path to MCP configuration file (optional, defaults to .claude/.mcp.json)
-MCP_CONFIG_PATH=.claude/.mcp.json
-
-# Logging level (optional, defaults to info)
-LOG_LEVEL=info
-
-# Enable debug mode (optional, defaults to false)
-DEBUG=false

package/.opencode/skills/mcp-management/scripts/cli.ts

@@ -1,195 +0,0 @@
-#!/usr/bin/env node
-/**
- * MCP Management CLI - Command-line interface for MCP operations
- */
-
-import { MCPClientManager } from './mcp-client.js';
-import { writeFileSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const GLOBAL_TIMEOUT_MS = parseInt(process.env.MCP_TIMEOUT || '120000', 10);
-let globalManager: MCPClientManager | null = null;
-
-function setupShutdownHandlers() {
-  const shutdown = async (signal: string) => {
-    console.log(`\nReceived ${signal}, cleaning up...`);
-    if (globalManager) {
-      await globalManager.cleanup();
-    }
-    process.exit(0);
-  };
-
-  process.on('SIGINT', () => shutdown('SIGINT'));
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-  process.on('SIGHUP', () => shutdown('SIGHUP'));
-
-  process.on('unhandledRejection', (reason) => {
-    console.error('Unhandled rejection:', reason);
-    process.exit(1);
-  });
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  // Setup shutdown handlers
-  setupShutdownHandlers();
-
-  // Check for help flags BEFORE connecting to servers
-  if (!command || command === '--help' || command === 'help') {
-    printUsage();
-    process.exit(0);
-  }
-
-  // Global timeout
-  const timeoutHandle = setTimeout(() => {
-    console.error('Global timeout exceeded, forcing exit');
-    process.exit(1);
-  }, GLOBAL_TIMEOUT_MS);
-  timeoutHandle.unref();
-
-  const manager = new MCPClientManager();
-  globalManager = manager;
-
-  try {
-    // Load config
-    await manager.loadConfig();
-    console.log('✓ Config loaded');
-
-    // Connect to all servers
-    await manager.connectAll();
-    console.log('✓ Connected to all MCP servers\n');
-
-    switch (command) {
-      case 'list-tools':
-        await listTools(manager);
-        break;
-
-      case 'list-prompts':
-        await listPrompts(manager);
-        break;
-
-      case 'list-resources':
-        await listResources(manager);
-        break;
-
-      case 'call-tool':
-        await callTool(manager, args[1], args[2], args[3]);
-        break;
-
-      default:
-        printUsage();
-    }
-
-    await manager.cleanup();
-    process.exit(0);
-  } catch (error) {
-    console.error('Error:', error);
-    process.exit(1);
-  }
-}
-
-async function listTools(manager: MCPClientManager) {
-  const tools = await manager.getAllTools();
-  console.log(`Found ${tools.length} tools:\n`);
-
-  for (const tool of tools) {
-    console.log(`📦 ${tool.serverName} / ${tool.name}`);
-    console.log(`   ${tool.description}`);
-    if (tool.inputSchema?.properties) {
-      console.log(`   Parameters: ${Object.keys(tool.inputSchema.properties).join(', ')}`);
-    }
-    console.log('');
-  }
-
-  // Save tools to JSON file
-  const assetsDir = join(__dirname, '..', 'assets');
-  const toolsPath = join(assetsDir, 'tools.json');
-
-  try {
-    mkdirSync(assetsDir, { recursive: true });
-    writeFileSync(toolsPath, JSON.stringify(tools, null, 2));
-    console.log(`\n✓ Tools saved to ${toolsPath}`);
-  } catch (error) {
-    console.error(`\n✗ Failed to save tools: ${error}`);
-  }
-}
-
-async function listPrompts(manager: MCPClientManager) {
-  const prompts = await manager.getAllPrompts();
-  console.log(`Found ${prompts.length} prompts:\n`);
-
-  for (const prompt of prompts) {
-    console.log(`💬 ${prompt.serverName} / ${prompt.name}`);
-    console.log(`   ${prompt.description}`);
-    if (prompt.arguments && prompt.arguments.length > 0) {
-      console.log(`   Arguments: ${prompt.arguments.map((a: any) => a.name).join(', ')}`);
-    }
-    console.log('');
-  }
-}
-
-async function listResources(manager: MCPClientManager) {
-  const resources = await manager.getAllResources();
-  console.log(`Found ${resources.length} resources:\n`);
-
-  for (const resource of resources) {
-    console.log(`📄 ${resource.serverName} / ${resource.name}`);
-    console.log(`   URI: ${resource.uri}`);
-    if (resource.description) {
-      console.log(`   ${resource.description}`);
-    }
-    if (resource.mimeType) {
-      console.log(`   Type: ${resource.mimeType}`);
-    }
-    console.log('');
-  }
-}
-
-async function callTool(
-  manager: MCPClientManager,
-  serverName: string,
-  toolName: string,
-  argsJson: string
-) {
-  if (!serverName || !toolName || !argsJson) {
-    console.error('Usage: cli.ts call-tool <server> <tool> <json-args>');
-    process.exit(1);
-  }
-
-  const args = JSON.parse(argsJson);
-  console.log(`Calling ${serverName}/${toolName}...`);
-
-  const result = await manager.callTool(serverName, toolName, args);
-  console.log('\nResult:');
-  console.log(JSON.stringify(result, null, 2));
-}
-
-function printUsage() {
-  console.log(`
-MCP Management CLI
-
-Usage:
-  cli.ts <command> [options]
-
-Commands:
-  list-tools                        List all tools and save to assets/tools.json
-  list-prompts                      List all prompts from all MCP servers
-  list-resources                    List all resources from all MCP servers
-  call-tool <server> <tool> <json>  Call a specific tool
-
-Examples:
-  cli.ts list-tools
-  cli.ts call-tool memory create_entities '{"entities":[{"name":"Alice","entityType":"person"}]}'
-  cli.ts call-tool human-mcp playwright_screenshot_fullpage '{"url":"https://example.com"}'
-
-Note: Tool analysis is done by the LLM reading assets/tools.json directly.
-  `);
-}
-
-main();