progressive-skills-mcp 0.2.0__py3-none-any.whl

progressive_skills_mcp/_version.py

@@ -0,0 +1,5 @@
+"""Central definition of the Skillz package version."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

progressive_skills_mcp/progressive_disclosure.py

@@ -0,0 +1,164 @@
+"""Progressive disclosure implementation for skillz.
+
+Add this code to _server.py to enable progressive disclosure.
+"""
+
+from typing import Optional, Any
+from fastmcp import Context
+from fastmcp.exceptions import ToolError
+import base64
+
+
+class MetadataGenerator:
+    """Generate system prompt metadata for all skills."""
+    
+    def __init__(self, registry):
+        self.registry = registry
+    
+    def generate_system_prompt_metadata(self) -> str:
+        """Generate markdown-formatted skill metadata for system prompts."""
+        skills = sorted(self.registry.skills, key=lambda s: s.slug)
+        
+        if not skills:
+            return "No skills available."
+        
+        lines = [
+            "## Available Skills",
+            "",
+            "You have access to specialized skills. To use a skill, call the `load_skill` tool with the skill name.",
+            "",
+        ]
+        
+        for skill in skills:
+            lines.append(f"- **{skill.slug}**: {skill.metadata.description}")
+        
+        return "\n".join(lines)
+    
+    def generate_json_metadata(self) -> str:
+        """Generate JSON metadata for programmatic use."""
+        import json
+        metadata = [
+            {
+                "name": skill.slug,
+                "description": skill.metadata.description,
+                "allowed_tools": list(skill.metadata.allowed_tools),
+            }
+            for skill in self.registry.skills
+        ]
+        return json.dumps(metadata, indent=2)
+
+
+def register_progressive_disclosure_tools(mcp, registry) -> None:
+    """Register 3 universal tools for progressive disclosure."""
+    
+    @mcp.tool(
+        name="load_skill",
+        description=(
+            "Load the complete instructions for a skill. "
+            "Use this when you've decided a skill is relevant based on "
+            "the skill metadata in your system prompt. "
+            "Returns the full SKILL.md content without frontmatter."
+        )
+    )
+    async def load_skill_tool(
+        skill_name: str,
+        ctx: Optional[Context] = None,
+    ) -> str:
+        """Load full skill instructions (Level 2 progressive disclosure)."""
+        try:
+            skill = registry.get(skill_name)
+            LOGGER.info("Loaded skill: %s", skill_name)
+            return skill.read_body()
+        except Exception as exc:
+            raise ToolError(
+                f"Skill '{skill_name}' not found. "
+                f"Available skills can be seen in your system prompt."
+            ) from exc
+    
+    @mcp.tool(
+        name="read_skill_file",
+        description=(
+            "Read a specific file from a skill's directory. "
+            "Use this when skill instructions reference a file "
+            "(e.g., 'See references/api_reference.md'). "
+            "Provide the skill name and relative file path."
+        )
+    )
+    async def read_skill_file_tool(
+        skill_name: str,
+        file_path: str,
+        ctx: Optional[Context] = None,
+    ) -> str:
+        """Read a specific file from skill directory (Level 3 progressive disclosure)."""
+        try:
+            skill = registry.get(skill_name)
+            
+            # Validate path doesn't traverse upward
+            if ".." in file_path or file_path.startswith("/"):
+                raise ToolError("Invalid path: path traversal not allowed")
+            
+            if not skill.exists(file_path):
+                raise ToolError(
+                    f"File '{file_path}' not found in skill '{skill_name}'"
+                )
+            
+            # Read content
+            data = skill.open_bytes(file_path)
+            
+            # Try to decode as UTF-8, fallback to base64 for binary
+            try:
+                content = data.decode("utf-8")
+            except UnicodeDecodeError:
+                content = f"[Binary file - base64 encoded]\n{base64.b64encode(data).decode('ascii')}"
+            
+            LOGGER.info("Read file: %s/%s", skill_name, file_path)
+            return content
+            
+        except Exception as exc:
+            raise ToolError(str(exc)) from exc
+    
+    @mcp.tool(
+        name="list_skill_files",
+        description=(
+            "List files available in a skill's directory. "
+            "Use this to discover what reference files, scripts, or resources "
+            "a skill provides. Optionally specify a subdirectory like "
+            "'references' or 'scripts'."
+        )
+    )
+    async def list_skill_files_tool(
+        skill_name: str,
+        subdirectory: Optional[str] = None,
+        ctx: Optional[Context] = None,
+    ) -> str:
+        """List available files in a skill directory."""
+        try:
+            skill = registry.get(skill_name)
+            
+            # Get all resource paths
+            all_paths = list(skill.iter_resource_paths())
+            
+            # Filter by subdirectory if specified
+            if subdirectory:
+                # Normalize subdirectory path
+                subdir_prefix = subdirectory.rstrip("/") + "/"
+                filtered_paths = [
+                    path for path in all_paths
+                    if path.startswith(subdir_prefix)
+                ]
+            else:
+                filtered_paths = all_paths
+            
+            if not filtered_paths:
+                subdir_msg = f" in subdirectory '{subdirectory}'" if subdirectory else ""
+                return f"No files found in skill '{skill_name}'{subdir_msg}"
+            
+            # Format output
+            subdir_msg = f" in '{subdirectory}'" if subdirectory else ""
+            lines = [f"Files in skill '{skill_name}'{subdir_msg}:"]
+            lines.extend(f"  - {path}" for path in sorted(filtered_paths))
+            
+            return "\n".join(lines)
+            
+        except Exception as exc:
+            raise ToolError(str(exc)) from exc

progressive_skills_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.3
+Name: progressive-skills-mcp
+Version: 0.2.0
+Summary: MCP server that exposes Claude-style skills to any MCP client.
+Keywords: mcp,skills,fastmcp,claude
+Author: Eleanor Berger
+Author-email: Eleanor Berger <eleanor@intellectronica.net>
+License: MIT License
+         
+         Copyright (c) 2025 Eleanor Berger <eleanor@intellectronica.net>
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fastmcp>=2.2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Flowtrica/skills-mcp
+Project-URL: Issues, https://github.com/Flowtrica/skills-mcp/issues
+Description-Content-Type: text/markdown
+
+# Skills MCP
+
+MCP server for SKILL.md files with **progressive disclosure** - achieving **13x token efficiency** over traditional approaches.
+
+Based on [intellectronica/skillz](https://github.com/intellectronica/skillz) with progressive disclosure modifications inspired by Claude.ai's approach.
+
+## What's Different?
+
+**Original skillz:**
+- Creates 1 tool per skill
+- 20 skills = 20 tools × ~100 tokens = **2000 tokens/request**
+
+**Skills MCP (this fork):**
+- Creates 3 universal tools (`load_skill`, `read_skill_file`, `list_skill_files`)
+- 20 skills = 3 tools × ~50 tokens = **150 tokens/request**
+- **13x improvement!** 🎉
+
+## Features
+
+✅ Progressive disclosure (3-level token efficiency)  
+✅ Metadata generation for system prompts  
+✅ Compatible with all SKILL.md format files  
+✅ Supports .zip and .skill archives  
+✅ Docker image available  
+
+## Quick Start
+
+### Using Docker
+
+```bash
+docker run -i --rm \
+  -v /path/to/skills:/skills \
+  flowtrica/skills-mcp:latest \
+  /skills
+```
+
+### Using uvx
+
+```bash
+uvx skills-mcp@latest /path/to/skills
+```
+
+### With MCPHub
+
+```json
+{
+  "mcpServers": {
+    "skills": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "--entrypoint", "sh",
+        "flowtrica/skills-mcp:latest",
+        "-c",
+        "git clone https://github.com/YOUR_USERNAME/your-skills.git /tmp/skills && skills-mcp /tmp/skills"
+      ]
+    }
+  }
+}
+```
+
+## Progressive Disclosure
+
+### Level 1: System Prompt (Once per conversation)
+```markdown
+## Available Skills
+- **weather**: Get weather forecasts
+- **pptx**: Create presentations
+```
+**Cost:** ~200 tokens, sent ONCE
+
+### Level 2: On-Demand Instructions
+```python
+load_skill("pptx")  # Returns full SKILL.md
+```
+**Cost:** 0 tokens until loaded
+
+### Level 3: Referenced Resources  
+```python
+read_skill_file("pptx", "references/api.md")
+```
+**Cost:** 0 tokens until accessed
+
+## Generate Metadata
+
+For Onyx or other MCP clients that support system prompts:
+
+```bash
+skills-mcp --generate-metadata /path/to/skills
+```
+
+Output:
+```markdown
+## Available Skills
+
+You have access to specialized skills...
+
+- **test-skill**: A simple test skill
+- **weather**: Get weather forecasts
+```
+
+## Installation
+
+```bash
+pip install skills-mcp
+```
+
+Or use with `uv`:
+```bash
+uv tool install skills-mcp
+```
+
+## Usage
+
+```bash
+# Run MCP server
+skills-mcp /path/to/skills
+
+# Generate metadata
+skills-mcp --generate-metadata /path/to/skills
+
+# Generate JSON metadata
+skills-mcp --generate-metadata --format json /path/to/skills
+
+# List discovered skills
+skills-mcp --list-skills /path/to/skills
+```
+
+## Skill Format
+
+Skills can be:
+- **Directories** with SKILL.md file
+- **Zip archives** containing SKILL.md
+- **.skill archives**
+
+Example structure:
+```
+skills/
+├── weather/
+│   ├── SKILL.md
+│   └── references/
+│       └── api.md
+└── pptx.zip
+```
+
+SKILL.md format:
+```markdown
+---
+name: skill-name
+description: Brief description
+---
+
+# Full Instructions
+
+Detailed skill instructions here...
+```
+
+## Building Docker Image
+
+```bash
+docker build -t flowtrica/skills-mcp:latest .
+docker push flowtrica/skills-mcp:latest
+```
+
+## Token Efficiency Comparison
+
+| Approach | Tools/Request | Tokens/Request | 20 Skills |
+|----------|--------------|----------------|-----------|
+| Original | 20 tools | ~100 each | 2000 tokens |
+| **Skills MCP** | **3 tools** | **~50 each** | **150 tokens** |
+| **Improvement** | | | **13x better!** 🎉 |
+
+## License
+
+MIT (same as original skillz)
+
+## Credits
+
+- Based on [skillz](https://github.com/intellectronica/skillz) by Eleanor Berger
+- Progressive disclosure modifications by Flowtrica
+- Inspired by Claude.ai's skills system
+
+## Links
+
+- Original skillz: https://github.com/intellectronica/skillz
+- Skills repo: https://github.com/Flowtrica/agent-skills
+- Docker Hub: https://hub.docker.com/r/flowtrica/skills-mcp

progressive_skills_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+progressive_skills_mcp/__init__.py,sha256=WFbujAfiFsm3g567Ea91ZXjhLesI78EVhc3Ao3oy1PM,522
+progressive_skills_mcp/__main__.py,sha256=AFR1CXSuPL4Td1RPNWZzuUXntdaHqgJOp9DL5iPk8QM,215
+progressive_skills_mcp/_server.py,sha256=jWuqHTTad8ECpawX-qd0PdNCodb0t2hcOPJo5qUnxVI,41991
+progressive_skills_mcp/_version.py,sha256=q4q6xy8hoU3hhiPLlZPK9YPK0gwpSwNYBznw8EVjY6k,106
+progressive_skills_mcp/progressive_disclosure.py,sha256=rSOGm0XodEXMoNlRTnkyPeDFiY3yug1i_pv3aUvHqPE,5855
+progressive_skills_mcp/skills/context7-docs-lookup.zip,sha256=9jvk8QROayFq249BxCUCi2dhvaUdH2eOdEZunHjNSkg,2430
+progressive_skills_mcp-0.2.0.dist-info/WHEEL,sha256=5DEXXimM34_d4Gx1AuF9ysMr1_maoEtGKjaILM3s4w4,80
+progressive_skills_mcp-0.2.0.dist-info/entry_points.txt,sha256=v3yDRF-b-QfYLa8bfmOvTr40hHKTy9F0166K-DfoyGo,80
+progressive_skills_mcp-0.2.0.dist-info/METADATA,sha256=yirmfD0v-RsW7xn-bIWfFB4ABcZt94TMX88AxxT26es,5964
+progressive_skills_mcp-0.2.0.dist-info/RECORD,,

progressive_skills_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.29
+Root-Is-Purelib: true
+Tag: py3-none-any

progressive_skills_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+progressive-skills-mcp = progressive_skills_mcp.__main__:run
+