Enhanced Skills MCP Server

A Model Context Protocol (MCP) server that serves specialized prompt libraries (skills) from a local directory AND provides a Lazy-MCP Bridge for compatibility with hierarchical tool systems. Provides token-efficient access to expert knowledge across domains for any MCP-compatible client.

⚠️ Platform Compatibility Note: This server has been tested and developed on Linux. While the core skills functionality should work cross-platform, the Lazy-MCP Bridge integration contains Linux-specific paths and assumptions. Windows and macOS users may need to modify configuration or use alternative lazy-mcp setups.

Features

🚀 Progressive Disclosure: Only skill metadata in context (~50 tokens/skill), full content loaded on-demand
💰 Token Efficient: 95%+ reduction in token usage during tool discovery
� Auto-Discovery: Automatically scans and loads skills from configurable directory
⚡ Hot Reload: Skills update immediately without server restart
🔧 Configurable: Environment variable controls skills directory location
🌉 Lazy-MCP Bridge: Seamlessly integrates lazy-mcp hierarchical tools for maximum compatibility
📦 Universal: Works with any MCP client (Cline, Claude Desktop, etc.)
🛡️ Skill Validation: Enforces naming conventions and content rules
🤖 Executable Skills: Dynamic instruction generation with tool orchestration
🔄 Dynamic Behavior: Context-aware skill execution with parameter support
🔗 Tool Orchestration: Skills can specify and use available tools

Installation

Prerequisites

Node.js 18+
npm or yarn

Global Installation (Recommended)

npm install -g @skills-server/mcp

This installs the skills-server command globally and makes it available in your PATH.

Local Installation (Development)

git clone <repository-url>
cd skills-server
npm install
npm run build

Configuration

Environment Variables

SKILLS_DIR: Path to skills directory (default: ~/.skills)
LAZY_MCP_ENABLED: Enable Lazy-MCP Bridge integration (default: false)
LAZY_MCP_COMMAND: Command to run lazy-mcp server (default: lazy-mcp script path)

MCP Client Setup

Add to your MCP client configuration:

For VS Code Exrensions

Add to your extension config.jason:

{
  "mcpServers": {
    "skills-server": {
      "command": "skills-server",
      "env": {
        "SKILLS_DIR": "~/.skills"
      }
    }
  }
}

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "skills-server": {
      "command": "skills-server",
      "env": {
        "SKILLS_DIR": "~/.skills"
      }
    }
  }
}

For Other MCP Clients

Use the skills-server command in your MCP server configuration.

Local Development Setup

If running locally, use the full path to the built binary:

{
  "mcpServers": {
    "skills-server": {
      "command": "node",
      "args": ["/path/to/skills-server/build/index.js"],
      "env": {
        "SKILLS_DIR": "/path/to/your/skills"
      }
    }
  }
}

Lazy-MCP Bridge

The server integrates with lazy-mcp by VoiceTreeLab to provide access to hierarchical tool systems. This bridge enables seamless compatibility between traditional MCP tools and lazy-mcp's hierarchical architecture.

Installing Lazy-MCP

Prerequisites:

Python 3.8+
pip package manager

Installation:

# Clone the repository
git clone https://github.com/voicetreelab/lazy-mcp.git
cd lazy-mcp

# Install dependencies
pip install -r requirements.txt

# Make the run script executable
chmod +x run-lazy-mcp.sh

Configuration: The skills server automatically detects lazy-mcp when it's available in your system PATH or when the LAZY_MCP_COMMAND environment variable points to the lazy-mcp executable.

Bridge Features

When enabled, the server automatically:

Discovers Tools: Scans lazy-mcp's hierarchy and exposes tools as traditional MCP tools
Handles Execution: Proxies tool calls through lazy-mcp's execute_tool mechanism
Maintains Efficiency: Preserves lazy-mcp's token-saving benefits
Ensures Compatibility: Works with MCP clients that expect direct tool access

Bridge Benefits

🔗 Universal Access: All lazy-mcp tools available in any MCP client
⚡ Token Savings: Hierarchical loading without client-side changes
🔄 Seamless Integration: No changes needed to existing lazy-mcp setups
🛡️ Error Resilience: Graceful fallback if lazy-mcp is unavailable

Customization

Important Note for Users

This package includes a pre-configured lazy-mcp setup optimized for the author's environment. To get the full experience, you'll need to customize both the skills-server and your lazy-mcp configuration for your own setup.

1. Customizing Tool Categories

The skills-server filters lazy-mcp tools to prevent duplicates with VS Code extension internal tools. To customize which categories are included:

Edit src/index.ts (lines 239-243):

const universalCategories = [
  'brave-search', 'playwright', 'puppeteer', 'filesystem',
  'desktop-commander', 'memory', 'youtube', 'fuse-optimizer',
  'brave-search-marketplace', 'playwright-marketplace', 'puppeteer-marketplace', 'whatsapp-mcp'
];

Modify this array to include the categories that match your available MCP servers.

2. Setting Up Your Own Lazy-MCP

Your lazy-mcp configuration needs to point to your own MCP server locations:

Install lazy-mcp following the official documentation
Configure your MCP servers in lazy-mcp's config.json
Update server paths to match your installation locations
Regenerate the hierarchy using lazy-mcp's structure generator

3. Deployment Considerations

Core skills functionality works without lazy-mcp
Lazy-mcp integration requires your own lazy-mcp setup
Tool filtering prevents conflicts with VS Code extension internal tools
Customization is expected for optimal performance in your environment

Skills Format

Each skill is a directory containing a SKILL.md file with YAML frontmatter:

skill-name/
└── SKILL.md

SKILL.md Structure

---
name: skill-name
description: Brief description of what this skill does and when to use it
type: static | executable  # Optional: defines skill behavior
allowed_tools: [tool1, tool2]  # Optional: tools this skill can orchestrate
execution_logic: conditional  # Optional: dynamic behavior type
parameters:  # Optional: skill parameters
  param1: string
  param2: object
---

# Skill Title

[Comprehensive skill content with instructions, examples, and best practices]

Example Skill

Static Skill (Traditional):

---
name: docker-compose-manager
description: Manages Docker Compose services for containerized applications. Use when starting, stopping, or checking status of Docker services.
---

# Docker Compose Manager Skill

You are an expert at managing Docker Compose services...

## Core Operations
- **Start services**: Use `docker-compose up -d`
- **Stop services**: Use `docker-compose down`
- etc.

Executable Skill (Advanced):

---
name: debug-agent
description: Dynamic debugging agent that analyzes errors and provides fixes using available tools
type: executable
allowed_tools: [list_directory, read_file, search_files, system-monitoring]
execution_logic: conditional
parameters:
  error_type: string
  context: object
---

# Debug Agent - Dynamic Problem Solver

You are an expert debugging agent that can analyze problems and provide solutions using available tools...

## Dynamic Decision Making

Based on the error type and context, select the appropriate tools and approach:

- **File-related issues**: Use file system tools to examine code and configuration
- **System problems**: Use monitoring tools to check health and performance
- **Integration errors**: Test connectivity and data flow
- **Logic errors**: Analyze code and test different scenarios

Always provide clear explanations of your findings and step-by-step solutions.

Usage

With VS Code extensions like Cline

After configuration, skills and lazy-mcp tools are automatically available:

You: "Search for React component libraries"
Cline: [Uses brave_web_search tool]

You: "Navigate to example.com and take a screenshot"
Cline: [Uses browser_navigate and browser_take_screenshot tools]

You: "Set up PostgreSQL database connection"
Cline: [Loads postgres skill automatically]

With Other MCP Clients

Skills and lazy-mcp tools appear as standard MCP tools. Note: Integration with Claude Code and other CLI tools has not been tested but should work based on MCP protocol compatibility.

Progressive Disclosure Architecture

How It Works

Discovery: Server scans SKILLS_DIR for skill directories
Metadata Loading: Reads only YAML frontmatter (name, description) for tool discovery
Tool Registration: Creates MCP tools with metadata-only information
Progressive Loading: Full content loaded only when skills are actually called
Token Efficiency: ~50 tokens per skill during discovery vs 1500+ tokens for full content

Validated Performance Metrics

JSON Response Size: 54% reduction (91KB → 42KB)
Token Efficiency: 95%+ reduction during tool discovery
Tool Discovery: ~50 tokens per skill (metadata only)
Skill Execution: Full content (1500+ tokens) only when needed
Content Expansion: 22x content ratio between discovery and execution
Real AI Validation: Progressive disclosure working for both skills and lazy-mcp tools
Executable Skills: Dynamic instruction generation with 89.2% token savings
Tool Orchestration: Skills can dynamically use available MCP tools

Caching

Metadata Cache: 5 seconds for skill metadata
Full Content Cache: 30 seconds for complete skill content
Hot Reload: Changes reflected immediately without server restart

Development

Project Structure

skills-server/
├── src/
│   └── index.ts      # Main server implementation
├── build/
│   └── index.js      # Compiled server
├── package.json
└── README.md

Adding Features

The server can be extended with:

Additional skill metadata
Skill validation
Custom skill formats
Integration with external APIs

Testing

# Build and test
npm run build
npm test

# Run comprehensive test suite
node test_runner.js

# Validate progressive disclosure
node test-progressive-disclosure.js

Progressive Disclosure Validation

The server includes comprehensive tests that validate:

Token Efficiency: 95%+ reduction in discovery tokens
Metadata-Only Discovery: Only skill names/descriptions during tool listing
Full Content Loading: Complete skill content when tools are called
Skill Validation: Proper naming conventions and content rules
Real AI Integration: Ready for production use with actual models

API Reference

Tools

get_skill: Returns full content of requested skill
- Input: skill_name (string)
- Output: Complete skill markdown content

Configuration Options

SKILLS_DIR: Directory containing skill folders
CACHE_DURATION: Skill cache duration in milliseconds (default: 5000)

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

GPL-3.0 License - see LICENSE file for details.

Related Projects

local-skills-mcp - Alternative file-based skills server
MCP Protocol - Model Context Protocol specification

Built with Model Context Protocol SDK

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
build		build
src		src
.gitignore		.gitignore
ALL_TOOLS_WORKING_SUMMARY.md		ALL_TOOLS_WORKING_SUMMARY.md
COMMIT_SUMMARY.md		COMMIT_SUMMARY.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
PUBLISH_CHECKLIST.md		PUBLISH_CHECKLIST.md
README.md		README.md
TEST_SUMMARY.md		TEST_SUMMARY.md
TOOL_PARAMETER_FORMATS.md		TOOL_PARAMETER_FORMATS.md
UNIVERSAL_MCP_FIX_GUIDE.md		UNIVERSAL_MCP_FIX_GUIDE.md
create-chart.js		create-chart.js
package-lock.json		package-lock.json
package.json		package.json
performance-chart.txt		performance-chart.txt
publish.sh		publish.sh
quick_validation.js		quick_validation.js
simple-test.js		simple-test.js
test-bridge.js		test-bridge.js
test-comparison.js		test-comparison.js
test_bridge_reliability.js		test_bridge_reliability.js
test_concurrency.js		test_concurrency.js
test_content_delivery.js		test_content_delivery.js
test_correct_tool_usage.js		test_correct_tool_usage.js
test_environment_variables.js		test_environment_variables.js
test_error_handling.js		test_error_handling.js
test_hot_reload.js		test_hot_reload.js
test_lazy_mcp.js		test_lazy_mcp.js
test_memory_leaks.js		test_memory_leaks.js
test_runner.js		test_runner.js
test_security.js		test_security.js
test_skills_content.js		test_skills_content.js
test_skills_integration.js		test_skills_integration.js
test_tool_discovery.js		test_tool_discovery.js
test_tool_execution.js		test_tool_execution.js
tsconfig.json		tsconfig.json
validation-test.js		validation-test.js

ivanenev/skills-server

Folders and files

Latest commit

History

Repository files navigation