@vodailoc/kilo-kit-mcp 1.1.0

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

@@ -0,0 +1,114 @@
+# MCP Configuration Guide
+
+## Configuration File Structure
+
+MCP servers are configured in `.claude/.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. `.claude/skills/mcp-management/.env`
+3. `.claude/skills/.env`
+4. `.claude/.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/skills/operations/mcp-management/references/gemini-cli-integration.md

@@ -0,0 +1,201 @@
+# Gemini CLI Integration Guide
+
+## 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 `.claude/.mcp.json`:
+
+```bash
+# Create .gemini directory
+mkdir -p .gemini
+
+# Create symlink (Unix/Linux/macOS)
+ln -sf .claude/.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
+gemini [flags] -p "<prompt>"
+```
+
+### 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)
+- `-p "<prompt>"`: Task description
+
+### Examples
+
+**Screenshot Capture**:
+```bash
+gemini -y -m gemini-2.5-flash -p "Take a screenshot of https://www.google.com.vn"
+```
+
+**Memory Operations**:
+```bash
+gemini -y -m gemini-2.5-flash -p "Remember that Alice is a React developer working on e-commerce projects"
+```
+
+**Web Research**:
+```bash
+gemini -y -m gemini-2.5-flash -p "Search for latest Next.js 15 features and summarize the top 3"
+```
+
+**Multi-Tool Orchestration**:
+```bash
+gemini -y -m gemini-2.5-flash -p "Search for Claude AI documentation, take a screenshot of the homepage, and save both to memory"
+```
+
+**Browser Automation**:
+```bash
+gemini -y -m gemini-2.5-flash -p "Navigate to https://example.com, click the signup button, and take a screenshot"
+```
+
+## How It Works
+
+1. **Configuration Loading**: Reads `.gemini/settings.json` (symlinked to `.claude/.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 `.claude/.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 `.claude/.mcp.json`.
+
+### Debug Mode
+
+```bash
+gemini --debug -p "Take a screenshot"
+```
+
+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/skills/operations/mcp-management/references/mcp-protocol.md

@@ -0,0 +1,116 @@
+# 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/skills/operations/mcp-management/scripts/.env.example

@@ -0,0 +1,10 @@
+# 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/skills/operations/mcp-management/scripts/cli.ts

@@ -0,0 +1,155 @@
+#!/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);
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  const manager = new MCPClientManager();
+
+  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();
+  } 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();

package/skills/operations/mcp-management/scripts/dist/analyze-tools.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Tool Analyzer - Intelligently selects relevant MCP tools for tasks
+ */
+/**
+ * Analyze tools and return those relevant to the task
+ */
+export function analyzeToolsForTask(tools, taskDescription) {
+    const keywords = extractKeywords(taskDescription);
+    const scoredTools = tools.map(tool => ({
+        tool,
+        score: calculateRelevanceScore(tool, keywords, taskDescription),
+        reasons: explainScore(tool, keywords, taskDescription)
+    }));
+    // Sort by score descending
+    scoredTools.sort((a, b) => b.score - a.score);
+    // Filter tools with score above threshold
+    const threshold = 0.3;
+    const relevant = scoredTools.filter(st => st.score > threshold);
+    return {
+        relevantTools: relevant.map(st => st.tool),
+        reasoning: relevant.map(st => `${st.tool.name} (${st.tool.serverName}): ${st.reasons.join('; ')}`),
+        confidence: relevant.length > 0
+            ? relevant[0].score
+            : 0
+    };
+}
+function extractKeywords(text) {
+    const stopWords = new Set([
+        'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at',
+        'to', 'for', 'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are'
+    ]);
+    return text
+        .toLowerCase()
+        .split(/\W+/)
+        .filter(word => word.length > 2 && !stopWords.has(word));
+}
+function calculateRelevanceScore(tool, keywords, taskDescription) {
+    let score = 0;
+    const toolText = `${tool.name} ${tool.description}`.toLowerCase();
+    // Keyword matching
+    for (const keyword of keywords) {
+        if (toolText.includes(keyword)) {
+            score += 0.2;
+        }
+    }
+    // Exact phrase matching
+    const taskLower = taskDescription.toLowerCase();
+    if (toolText.includes(taskLower) || taskLower.includes(tool.name.toLowerCase())) {
+        score += 0.5;
+    }
+    // Schema complexity bonus (more params = more specialized)
+    if (tool.inputSchema?.properties) {
+        const paramCount = Object.keys(tool.inputSchema.properties).length;
+        score += Math.min(paramCount * 0.05, 0.3);
+    }
+    return Math.min(score, 1.0);
+}
+function explainScore(tool, keywords, taskDescription) {
+    const reasons = [];
+    const toolText = `${tool.name} ${tool.description}`.toLowerCase();
+    const matchedKeywords = keywords.filter(k => toolText.includes(k));
+    if (matchedKeywords.length > 0) {
+        reasons.push(`matches keywords: ${matchedKeywords.join(', ')}`);
+    }
+    if (tool.description) {
+        reasons.push(`description: ${tool.description.slice(0, 100)}`);
+    }
+    return reasons;
+}