{"id":49034833,"url":"https://github.com/cablate/Agentic-MCP-Skill","last_synced_at":"2026-05-05T15:00:42.746Z","repository":{"id":332080703,"uuid":"1132679756","full_name":"cablate/Agentic-MCP-Skill","owner":"cablate","description":"Agentic-MCP, Progressive MCP client with three-layer lazy loading. Validates AgentSkills.io pattern for efficient token usage. Use MCP without pre-install \u0026 wasting full-loading","archived":false,"fork":false,"pushed_at":"2026-01-21T06:07:30.000Z","size":2039,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-27T01:20:00.599Z","etag":null,"topics":["agentskill","agentskills","lazy-loading","mcp","mcp-server","model-context-protocol","skill","skills"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cablate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-12T09:54:12.000Z","updated_at":"2026-01-21T06:07:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cablate/Agentic-MCP-Skill","commit_stats":null,"previous_names":["cablate/mcp-progressive-agentskill","cablate/agentic-mcp-skill"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cablate/Agentic-MCP-Skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2FAgentic-MCP-Skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2FAgentic-MCP-Skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2FAgentic-MCP-Skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2FAgentic-MCP-Skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cablate","download_url":"https://codeload.github.com/cablate/Agentic-MCP-Skill/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2FAgentic-MCP-Skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32654618,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentskill","agentskills","lazy-loading","mcp","mcp-server","model-context-protocol","skill","skills"],"created_at":"2026-04-19T11:00:23.108Z","updated_at":"2026-05-05T15:00:42.740Z","avatar_url":"https://github.com/cablate.png","language":"TypeScript","funding_links":[],"categories":["Skills Library"],"sub_categories":["agentskills.io Standard"],"readme":"\u003cdiv align=\"center\"\u003e\n\n  # Agentic-MCP with Skill\n\n  ### AgentSkill for MCP - Three-layer progressive disclosure validates AgentSkills.io pattern for efficient MCP token usage\n\n  \u003cimg src=\"Banner.png\" alt=\"Agentic-MCP 封面圖\" width=\"100%\"\u003e\n\n  [![Website](https://img.shields.io/badge/Website-AGENTIC_MCP-blue)](https://agentic-mcp-skill.cablate.com/)\n  [![Node.js Version](https://img.shields.io/badge/node-%3E=18.0.0-brightgreen)](https://nodejs.org)\n\n  **[English](./README.md)** | **[繁體中文](./README_zhTW.md)**\n\n\u003c/div\u003e\n\n---\n\n## Design Intent\n\n### Proven AgentSkills Pattern\n\nIn the AgentSkills.io ecosystem, **Progressive Disclosure** combined with **Script linkage** has been validated as effective:\n\n- AI only loads specific information when needed, significantly reducing token usage\n- Scripts can be invoked via AI commands, providing high customization potential\n- Sharing tools via scripts is far less costly than developing and using complex MCP Servers\n\nThe impact of this pattern is **significant and substantial**.\n\n### Current MCP Skill Dilemma\n\nDespite this, many Skills using MCP still face two extreme options:\n\n**Option 1: Install MCP directly in Claude Code, Skill only guides AI to call MCP**\n- MCP server occupies AI context long-term\n- Full tool list loaded every conversation\n- Token waste, and MCP itself cannot be progressively explored\n\n**Option 2: Write custom scripts yourself**\n- Tests user's programming skills\n- High customization but lacks standards\n- Each MCP has its own format/specs, high adaptation cost for both open and closed source\n- Difficult to maintain and share\n\n### This Skill's Goal\n\n**Validate whether AgentSkills.io pattern applies to improving MCP usage**\n\nThis concept validation attempts to port AgentSkills' successful pattern to the MCP domain:\n\n1. Can AgentSkills architecture apply to MCP server management?\n2. Is three-layer progressive disclosure effective in MCP scenarios?\n3. Is Socket-based daemon architecture more practical than direct MCP usage?\n\n### Experimental Nature\n\nThis is not a mature product, but an experiment:\n\n- Test AgentSkills pattern applicability in MCP domain\n- Explore actual effectiveness of three-layer loading\n- Validate pros/cons of Daemon architecture\n- Serve as reference prototype for future development\n\n### Important Disclaimer\n\n**This is a very early, rushed AI-assisted demo version** with current goals:\n\n- Validate concept feasibility\n- Explore usage patterns\n- Collect feedback for improvements\n\n**Not recommended for production use**.\nExpect many issues and optimization opportunities. If you find any problems or have suggestions, please open an Issue or contribute a PR.\n\n---\n\n## Core Concepts\n\n### Three-Layer Progressive Disclosure\n\nLike AgentSkills, you don't need to load everything at once:\n\n**Layer 1: Know which servers are available**\n```\nLoad only basic info (name, version, status)\nUsage: ~50-100 tokens\nUse case: Check availability, choose server\n```\n\n**Layer 2: Know what tools this server provides**\n```\nLoad tool list (names + brief descriptions)\nUsage: ~200-400 tokens\nUse case: Browse available tools, decide what to use\n```\n\n**Layer 3: Load only the tools you need**\n```\nLoad complete input format for specific tool\nUsage: ~300-500 tokens/tool\nUse case: Before calling tool\n```\n\n### Why This Approach\n\nAssume an MCP server has 20 tools, you only need 2:\n\n| Loading Method | Token Usage | Description |\n|:---|:---:|:---|\n| Load All | 6,000 | 20 tools × 300 tokens |\n| Three-Layer Progressive | 850 | Metadata(50) + List(200) + 2 tools(600) |\n| Savings | 86% | Only load what you need |\n\n---\n\n## Development Status\n\n### Future Plans\n\nBased on concept validation results, future directions include:\n\n**Short-term Goals**\n- More convenient MCP Servers management (UI, auto-discovery, one-click install)\n- Implement Auth features (API Key management, permission control)\n\n**Mid-term Goals**\n- Enhance MCP Server tool calling experience (better error messages, parameter validation, result formatting)\n- Intercept MCP Server output with customizable Script data processing, avoid massive messy data entering conversation memory\n\nThis project's direction depends on:\n\n- Concept validation results\n- Community feedback\n- Actual usage needs\n\nFeedback and suggestions welcome.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js \u003e= 18.0.0\n- npm\n\n### 1. Install from npm (Recommended)\n\n```bash\n# Install globally\nnpm install -g @cablate/agentic-mcp\n\n# Verify installation\nagentic-mcp --version\n\n# Start daemon\nagentic-mcp daemon start\n```\n\n### 2. Configure\n\nEdit `mcp-servers.json` in the project root:\n\n```json\n{\n  \"servers\": {\n    \"playwright\": {\n      \"description\": \"Browser automation tool for web navigation, screenshots, clicks, form filling, and more\",\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"@playwright/mcp@latest\", \"--isolated\"]\n    }\n  }\n}\n```\n\n### 3. Start Daemon\n\n```bash\nnode dist/cli/index.js daemon start --config \u003cconfig-path\u003e\n```\n\n### 4. Test Connection\n\n```bash\n# Check daemon health\nagentic-mcp daemon health\n\n# Layer 1: Check server status\nagentic-mcp metadata playwright\n\n# Layer 2: List available tools\nagentic-mcp list playwright\n\n# Layer 3: View specific tool format\nagentic-mcp schema playwright browser_navigate\n```\n\n### 5. Call Tool\n\n```bash\nagentic-mcp call playwright browser_navigate --params '{\"url\": \"https://example.com\"}'\n```\n\n---\n\n## Testing\n\nThis project uses Vitest for testing with the following test suites:\n\n### Running Tests\n\n```bash\n# Run tests in watch mode\nnpm test\n\n# Run tests once\nnpm run test:run\n\n# Run with coverage report\nnpm run test:coverage\n```\n\n### Test Structure\n\n```\ntests/\n├── unit/\n│   ├── client.test.ts       # ProgressiveMCPClient tests (12 tests)\n│   ├── socket-client.test.ts # SocketClient tests (7 tests)\n│   └── cli/\n│       └── commands.test.ts  # CLI command tests (6 tests)\n```\n\n### Current Coverage\n\n- **Statements**: 61.71%\n- **Branches**: 47.29%\n- **Functions**: 65.85%\n- **Lines**: 61.53%\n\nTest coverage focuses on core modules (`client.ts`, `socket-client.ts`). Daemon integration tests are deferred to future work.\n\n### Test Philosophy\n\nThis project follows a **pragmatic progressive** approach:\n- Focus on happy path testing first\n- Use real MCP server (`@modelcontextprotocol/server-filesystem`) for integration\n- Mock only where necessary (e.g., `net` module for SocketClient)\n- Defer complex scenarios (daemon socket tests) to keep initial implementation simple\n\n---\n\n## Usage Examples\n\n### Web Automation\n\nAutomate browser operations using Playwright MCP server:\n\n```bash\n# 1. Navigate to website\nagentic-mcp call playwright browser_navigate --params '{\"url\": \"https://www.apple.com/tw\"}'\n\n# 2. Take screenshot\nagentic-mcp call playwright browser_take_screenshot\n\n# 3. Click element\nagentic-mcp call playwright browser_click --params '{\"element\": \"Mac link\", \"ref\": \"e19\"}'\n```\n\n### Hot Reload Configuration\n\nReload after modifying `mcp-servers.json` without restarting daemon:\n\n```bash\nagentic-mcp daemon reload\n```\n\nResponse example:\n\n```\n✓ Configuration reloaded\n  Old servers: playwright_global\n  New servers: playwright_global, filesystem_global\n```\n\n---\n\n## Architecture\n\n### System Architecture\n\n```\n+-----------------------------+\n|     AI / CLI Layer          |\n|  (CLI commands)              |\n|  - agentic-mcp metadata      |\n|  - agentic-mcp list          |\n|  - agentic-mcp schema        |\n|  - agentic-mcp call          |\n+-----------+-----------------+\n            | Socket (newline-delimited JSON)\n            v\n+-----------------------------+\n|   MCP Daemon (Long-Running)  |\n|  - Maintain persistent MCP   |\n|    connections               |\n|  - Socket communication      |\n|  - Manage shared sessions    |\n|  - Support Hot Reload        |\n+-----------+-----------------+\n            | MCP Protocol\n            v\n+-----------------------------+\n|        MCP Servers           |\n|  - playwright (browser)      |\n|  - filesystem (files)        |\n|  - github (Git)              |\n|  - custom servers            |\n+-----------------------------+\n```\n\n---\n\n## Configuration\n\n### MCP Servers Configuration\n\nEdit `mcp-servers.json`:\n\n```json\n{\n  \"servers\": {\n    \"playwright\": {\n      \"description\": \"Browser automation tool for web navigation, screenshots, clicks, and form filling\",\n      \"transportType\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"@playwright/mcp@latest\", \"--isolated\"]\n    }\n  }\n}\n```\n\n**Configuration Notes**:\n- `description` (optional): Server description for AI to understand the MCP server's purpose. If not provided, Layer 1 metadata will not include this field.\n\n---\n\n## Resources\n- [SKILL.md](./SKILL.md) - Complete usage guide\n- [docs/AGENT_BROWSER_DESIGN_PATTERNS.md](./docs/AGENT_BROWSER_DESIGN_PATTERNS.md) - Design patterns learned from agent-browser\n- [MCP Specification](https://modelcontextprotocol.io)\n- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- [AgentSkills.io](https://agentskills.io/home)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nThis is a concept validation project, feedback welcome\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcablate%2FAgentic-MCP-Skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcablate%2FAgentic-MCP-Skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcablate%2FAgentic-MCP-Skill/lists"}