@thanhvn14/csvibe 0.1.3 → 0.1.5

package/.github/skills/mcp-management/README.md

@@ -0,0 +1,219 @@
+# MCP Management Skill
+
+Intelligent management and execution of Model Context Protocol (MCP) servers.
+
+## Overview
+
+This skill enables Claude to discover, analyze, and execute MCP server capabilities without polluting the main context window. Perfect for context-efficient MCP integration using subagent-based architecture.
+
+## Features
+
+- **Multi-Server Management**: Connect to multiple MCP servers from single config
+- **Intelligent Tool Discovery**: Analyze which tools are relevant for specific tasks
+- **Progressive Disclosure**: Load only necessary tool definitions
+- **Execution Engine**: Call MCP tools with proper parameter handling
+- **Context Efficiency**: Delegate MCP operations to `mcp-manager` subagent
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd %USERPROFILE%/.claude/skills/mcp-management/scripts
+npm install
+```
+
+### 2. Configure MCP Servers
+
+Create `%USERPROFILE%/.claude/.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"]
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
+    }
+  }
+}
+```
+
+See `%USERPROFILE%/.claude/.mcp.json.example` for more examples.
+
+### 3. Test Connection
+
+```bash
+cd %USERPROFILE%/.claude/skills/mcp-management/scripts
+npx ts-node cli.ts list-tools
+```
+
+## Usage Patterns
+
+### Pattern 1: Discover Available Tools
+
+```bash
+npx ts-node scripts/cli.ts list-tools
+npx ts-node scripts/cli.ts list-prompts
+npx ts-node scripts/cli.ts list-resources
+```
+
+### Pattern 2: LLM-Driven Tool Selection
+
+The LLM reads `assets/tools.json` and intelligently selects tools. No separate analysis command needed - the LLM's understanding of context and intent is superior to keyword matching.
+
+### Pattern 3: Execute MCP Tools
+
+```bash
+npx ts-node scripts/cli.ts call-tool memory add '{"key":"name","value":"Alice"}'
+```
+
+### Pattern 4: Use with Subagent
+
+In main Claude conversation:
+
+```
+User: "I need to search the web and save results"
+Main Agent: [Spawns mcp-manager subagent]
+mcp-manager: Discovers brave-search + memory tools, reports back
+Main Agent: Uses recommended tools for implementation
+```
+
+## Architecture
+
+```
+Main Agent (Claude)
+    ↓ (delegates MCP tasks)
+mcp-manager Subagent
+    ↓ (uses skill)
+mcp-management Skill
+    ↓ (connects via)
+MCP Servers (memory, filesystem, etc.)
+```
+
+**Benefits**:
+- Main agent context stays clean
+- MCP discovery happens in isolated subagent context
+- Only relevant tool definitions loaded when needed
+- Reduced token usage
+
+## File Structure
+
+```
+mcp-management/
+├── SKILL.md                    # Skill definition
+├── README.md                   # This file
+├── scripts/
+│   ├── mcp-client.ts          # Core MCP client manager
+│   ├── analyze-tools.ts       # Intelligent tool selection
+│   ├── cli.ts                 # Command-line interface
+│   ├── package.json           # Dependencies
+│   ├── tsconfig.json          # TypeScript config
+│   └── .env.example           # Environment template
+└── references/
+    ├── mcp-protocol.md        # MCP protocol reference
+    └── configuration.md       # Config guide
+```
+
+## Scripts Reference
+
+### mcp-client.ts
+
+Core client manager class:
+- Load config from `%USERPROFILE%/.claude/.mcp.json`
+- Connect to multiple MCP servers
+- List/execute tools, prompts, resources
+- Lifecycle management
+
+### cli.ts
+
+Command-line interface:
+- `list-tools` - Show all tools and save to assets/tools.json
+- `list-prompts` - Show all prompts
+- `list-resources` - Show all resources
+- `call-tool <server> <tool> <json>` - Execute tool
+
+**Note**: Tool analysis is performed by the LLM reading `assets/tools.json`, which provides better context understanding than algorithmic matching.
+
+## Configuration
+
+### Environment Variables
+
+Scripts check for variables in this order:
+
+1. `process.env` (runtime)
+2. `%USERPROFILE%/.claude/skills/mcp-management/.env`
+3. `%USERPROFILE%/.claude/skills/.env`
+4. `%USERPROFILE%/.claude/.env`
+
+### MCP Config Format
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "executable",          // Required
+      "args": ["arg1", "arg2"],        // Required
+      "env": {                          // Optional
+        "VAR": "value",
+        "API_KEY": "${ENV_VAR}"        // Reference env vars
+      }
+    }
+  }
+}
+```
+
+## Common MCP Servers
+
+Install with `npx`:
+
+- `@modelcontextprotocol/server-memory` - Key-value storage
+- `@modelcontextprotocol/server-filesystem` - File operations
+- `@modelcontextprotocol/server-brave-search` - Web search
+- `@modelcontextprotocol/server-puppeteer` - Browser automation
+- `@modelcontextprotocol/server-fetch` - HTTP requests
+
+## Integration with mcp-manager Agent
+
+The `mcp-manager` agent (`%USERPROFILE%/.claude/agents/mcp-manager.md`) uses this skill to:
+
+1. **Discover**: Connect to MCP servers, list capabilities
+2. **Analyze**: Filter relevant tools for tasks
+3. **Execute**: Call MCP tools on behalf of main agent
+4. **Report**: Send concise results back to main agent
+
+This architecture keeps main context clean and enables efficient MCP integration.
+
+## Troubleshooting
+
+### "Config not found"
+
+Ensure `%USERPROFILE%/.claude/.mcp.json` exists and is valid JSON.
+
+### "Server connection failed"
+
+Check:
+- Server command is installed (`npx` packages installed?)
+- Server args are correct
+- Environment variables are set
+
+### "Tool not found"
+
+List available tools first:
+```bash
+npx ts-node scripts/cli.ts list-tools
+```
+
+## Resources
+
+- [MCP Specification](https://modelcontextprotocol.io/specification/latest)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Official MCP Servers](https://github.com/modelcontextprotocol/servers)
+- [Skill References](./references/)
+
+## License
+
+MIT