mcp-skill-server 0.1.0__tar.gz

mcp_skill_server-0.1.0/.claude/skills/hello_world/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: hello-world
+description: A simple example skill that greets users. Use this to test your skill server setup.
+entry: uv run python hello.py
+---
+
+# Hello World Skill
+
+A minimal example skill demonstrating the skill format.
+
+## Usage Examples
+
+- "Run hello world"
+- "Say hello to Alice"
+- "Greet Bob with enthusiasm"
+
+## What it does
+
+Prints a greeting message. Supports optional name and enthusiasm level.

mcp_skill_server-0.1.0/.claude/skills/hello_world/hello.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Simple hello world skill for testing."""
+
+import argparse
+
+
+def main():
+    parser = argparse.ArgumentParser(description="A friendly greeting skill")
+    parser.add_argument(
+        "--name",
+        type=str,
+        default="World",
+        help="Name to greet",
+    )
+    parser.add_argument(
+        "--enthusiasm",
+        type=int,
+        default=1,
+        help="Number of exclamation marks (1-5)",
+    )
+
+    args = parser.parse_args()
+
+    exclaim = "!" * min(max(args.enthusiasm, 1), 5)
+    print(f"Hello, {args.name}{exclaim}")
+
+
+if __name__ == "__main__":
+    main()

mcp_skill_server-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Check import
+        run: uv run python -c "import mcp_skill_server; print(mcp_skill_server.__version__)"

mcp_skill_server-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_skill_server-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Skill outputs
+**/output/
+
+# OS
+.DS_Store
+Thumbs.db

mcp_skill_server-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

mcp_skill_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

mcp_skill_server-0.1.0/CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MCP Skill Server is a local MCP (Model Context Protocol) server for developing and testing skills before deploying them to production agents. It allows rapid iteration on skills locally instead of the deploy → test → iterate cycle.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest
+
+# Run server with example skills
+uv run mcp-skill-server examples/
+
+# Run server with custom skills directory
+uv run mcp-skill-server /path/to/skills
+
+# Initialize a new skill (standalone command)
+uv run mcp-skill-init ./path/to/skill -n "skill-name" -d "Description"
+
+# Or use as subcommand
+uv run mcp-skill-server init ./path/to/skill
+
+# Validate a skill (standalone command)
+uv run mcp-skill-validate ./path/to/skill
+
+# Or use as subcommand
+uv run mcp-skill-server validate ./path/to/skill
+
+# Install with GCS output handler support
+uv sync --extra gcs
+```
+
+## Architecture
+
+### Core Components
+
+- **`server.py`**: MCP server entry point. Exposes four MCP tools: `list_skills`, `get_skill`, `run_skill`, `refresh_skills`. Uses stdio transport.
+
+- **`loader.py`**: Skill discovery and schema inference. Scans for `*/SKILL.md` files, parses YAML frontmatter, and dynamically discovers commands/parameters by running `--help` on each skill's entry command.
+
+- **`executor.py`**: Runs skill commands as subprocesses. Detects output files in `output/` directory or via `OUTPUT_FILE:` prefix in stdout.
+
+- **`models.py`**: Pydantic request/response models.
+
+### Plugin System
+
+Two plugin types in `plugins/`:
+
+**Output Handlers** - Process files generated by skills:
+- `OutputHandler` (base class): Abstract interface for processing output files
+- `LocalOutputHandler`: Default handler, just tracks local file paths
+- `GCSOutputHandler`: Optional, uploads to Google Cloud Storage (requires `gcs` extra)
+
+**Response Formatters** - Customize MCP tool response formatting:
+- `ResponseFormatter` (base class): Abstract interface for formatting execution results
+- `DefaultResponseFormatter`: Default text-based formatter
+
+### Skill Format
+
+Skills are folders containing a `SKILL.md` with YAML frontmatter:
+
+```yaml
+---
+name: my-skill
+description: What it does
+entry: uv run python script.py
+---
+```
+
+Commands and parameters are auto-discovered by parsing argparse `--help` output. Skills save outputs to `output/` directory.
+
+### Key Data Flow
+
+1. Server discovers skills via `SkillLoader.discover_skills()` → finds `*/SKILL.md` files
+2. On `get_skill`, calls `skill.refresh_commands()` → runs `entry -h` to discover schema
+3. On `run_skill`, `SkillExecutor.execute()` builds bash command and runs subprocess
+4. Output files detected in `output/` or via `OUTPUT_FILE:` stdout marker
+5. Optional `OutputHandler` processes output files (upload, copy, etc.)
+6. `ResponseFormatter` formats execution result for MCP tool response

mcp_skill_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janine Cheng
+
+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.

mcp_skill_server-0.1.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: mcp-skill-server
+Version: 0.1.0
+Summary: Develop AI skills locally in your editor, deploy to production when ready
+Project-URL: Homepage, https://github.com/jcc-ne/mcp-skill-server
+Project-URL: Repository, https://github.com/jcc-ne/mcp-skill-server
+Project-URL: Issues, https://github.com/jcc-ne/mcp-skill-server/issues
+Author: Janine Cheng
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llm,mcp,skills,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.0.0; extra == 'gcs'
+Description-Content-Type: text/markdown
+
+Most coding assistants now support skills natively, so an MCP server just for skill discovery isn't necessary. Where this package adds value is making skills' execution **deterministic and deployable** — with a fixed entry point and controlled execution, skills developed in your editor can run in non-sandboxed production environments. It also supports incremental loading, so agents discover skills on demand instead of loading everything upfront.
+
+---
+# MCP Skill Server
+
+[![CI](https://github.com/jcc-ne/mcp-skill-server/actions/workflows/ci.yml/badge.svg)](https://github.com/jcc-ne/mcp-skill-server/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcp-skill-server)](https://pypi.org/project/mcp-skill-server/)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-skill-server)](https://pypi.org/project/mcp-skill-server/)
+[![License](https://img.shields.io/github/license/jcc-ne/mcp-skill-server)](LICENSE)
+
+Build agent skills where you work. Write a Python script, add a `SKILL.md`, and your agent can use it immediately. Iterate in real-time as part of your daily workflow. When it's ready, deploy the same skill to production — no rewrite needed.
+
+## Why?
+
+Most skill development looks like this: write code → deploy → test in a staging agent → realize it's wrong → redeploy → repeat. It's slow, and you never get to actually *use* the skill while building it.
+
+MCP Skill Server flips this. It runs **on your machine, inside your editor** — Claude Code, Cursor, or Claude Desktop. You develop a skill and use it in your real work at the same time. That tight feedback loop (edit → save → use) means you discover what's missing naturally, not through artificial test scenarios.
+The premise is if the skill doesn't work well with Claude Code, it's unlikely to work with a less sophisticated agent.
+
+
+### How skills mature to survive in the outside world
+
+Claude skills can already have companion scripts, but there's no formalized entry point — the agent decides how to invoke them. That works for local use, but it's not deployable: a production MCP server can't reliably call a skill if the execution path isn't fixed.
+
+MCP Skill Server enforces a declared **`entry` field** in your SKILL.md frontmatter (e.g. `entry: uv run python my_script.py`). This gives you a single, fixed entry point that the server controls. Commands and parameters are discovered from the script's `--help` output — that's the source of truth, not the LLM's interpretation of your code.
+
+```
+1. Claude/coding agent skill                → SKILL.md + scripts, but no fixed entry — agent decides how to run them
+2. Local MCP skill (+ entry)   → Fixed entry point, schema from --help, usable daily via this server
+3. Production                  → Same skill, same entry — deployed to your enterprise MCP server
+```
+
+### Sharpen locally, then harden for production
+
+Every agent that connects to the MCP server gets the same interface — `list_skills`, `get_skill`, `run_skill` — so the skill's description, parameter names, and help text are identical regardless of which agent calls them. That said, different agents have different strengths — a skill that works locally still needs testing with your production agent.
+
+1. **Use it yourself** — build the skill, use it daily via Claude Code or Cursor. Fix descriptions and param names when the agent misuses the skill.
+2. **Test with a weaker model** — try a smaller model to surface interface ambiguity.
+3. **Add a deterministic entry point** — declare `entry` in SKILL.md for reliable, secure execution. Use `skill init` to scaffold it, `skill validate` to check readiness.
+4. **Test with your production agent** — verify end-to-end in your target environment, then deploy.
+
+## Install
+
+### Claude Desktop (one-click)
+
+[![Install with Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install_Server-orange?logo=claude)](claudedesktop://install?config=%7B%22mcpServers%22%3A%7B%22skills%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-skill-server%22%2C%22serve%22%2C%22.%2Fmy-skills%22%5D%7D%7D%7D)
+
+After installing, edit the skills path in your Claude Desktop config to point to your skills directory.
+
+### Claude Code
+
+```bash
+claude mcp add skills -- uvx mcp-skill-server serve /path/to/my/skills
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project (or Settings → MCP → Add Server):
+
+```json
+{
+  "mcpServers": {
+    "skills": {
+      "command": "uvx",
+      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
+    }
+  }
+}
+```
+
+### Manual install
+
+```bash
+# From PyPI (recommended)
+uv pip install mcp-skill-server
+
+# Or from source
+git clone https://github.com/jcc-ne/mcp-skill-server
+cd mcp-skill-server && uv sync
+
+# Run the server
+uvx mcp-skill-server serve /path/to/my/skills
+```
+
+Then add to your editor's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "skills": {
+      "command": "uvx",
+      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
+    }
+  }
+}
+```
+
+## Creating a Skill
+
+### Option A: Use `skill init` (recommended)
+
+```bash
+# Create a new skill
+uv run mcp-skill-server init ./my_skills/hello -n "hello" -d "A friendly greeting"
+
+# Or use the standalone command
+uv run mcp-skill-init ./my_skills/hello -n "hello" -d "A friendly greeting"
+
+# Promote an existing prompt-only Claude skill to a runnable MCP skill
+uv run mcp-skill-init ./existing_claude_skill
+```
+
+### Option B: Manual setup
+
+#### 1. Create a folder with your script
+
+```
+my_skills/
+└── hello/
+    ├── SKILL.md
+    └── hello.py
+```
+
+#### 2. Add SKILL.md with frontmatter
+
+```yaml
+---
+name: hello
+description: A friendly greeting skill
+entry: uv run python hello.py
+---
+
+# Hello Skill
+
+Greets the user by name.
+```
+
+#### 3. Write your script with argparse
+
+```python
+# hello.py
+import argparse
+
+parser = argparse.ArgumentParser(description="Greeting skill")
+parser.add_argument("--name", default="World", help="Name to greet")
+args = parser.parse_args()
+
+print(f"Hello, {args.name}!")
+```
+
+That's it. The server auto-discovers commands and parameters from your `--help` output — no config needed.
+
+## Validating for Deployment
+
+When a skill is ready to graduate to production:
+
+```bash
+uv run mcp-skill-server validate ./my_skills/hello
+# or
+uv run mcp-skill-validate ./my_skills/hello
+```
+
+Checks:
+- Required frontmatter fields (name, description, entry)
+- Entry command uses allowed runtime
+- Script file exists
+- Commands discoverable via `--help`
+
+## How It Works
+
+### MCP Tools
+
+The server exposes four tools to your agent:
+
+| Tool | Description |
+|------|-------------|
+| `list_skills` | List all available skills |
+| `get_skill` | Get details about a skill (commands, parameters) |
+| `run_skill` | Execute a skill with parameters |
+| `refresh_skills` | Reload skills after you make changes |
+
+### Schema Discovery
+
+The server automatically discovers your skill's interface by parsing `--help` output:
+
+```python
+# Subcommands become separate commands
+subparsers = parser.add_subparsers(dest='command')
+analyze = subparsers.add_parser('analyze', help='Run analysis')
+
+# Arguments become parameters with inferred types
+analyze.add_argument('--year', type=int, required=True)  # int, required
+analyze.add_argument('--file', type=str)                  # string, optional
+```
+
+### Output Files
+
+Files saved to `output/` are automatically detected. Alternatively, print `OUTPUT_FILE:/path/to/file` to stdout.
+
+## Plugins
+
+### Output Handlers
+
+Process files generated by skills (upload, copy, transform, etc.):
+
+```python
+from mcp_skill_server.plugins import OutputHandler, LocalOutputHandler
+
+# Default: tracks local file paths
+handler = LocalOutputHandler()
+
+# Optional GCS handler (requires `uv sync --extra gcs`)
+from mcp_skill_server.plugins import GCSOutputHandler
+handler = GCSOutputHandler(
+    bucket_name="my-bucket",
+    folder_prefix="skills/outputs/",
+)
+```
+
+### Response Formatters
+
+Customize how execution results are formatted in MCP tool responses:
+
+```python
+from mcp_skill_server.plugins import ResponseFormatter
+
+class CustomFormatter(ResponseFormatter):
+    def format_execution_result(self, result, skill, command):
+        return f"Result: {result.stdout}"
+
+# Use with create_server()
+from mcp_skill_server import create_server
+server = create_server(
+    "/path/to/skills",
+    response_formatter=CustomFormatter()
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/jcc-ne/mcp-skill-server
+cd mcp-skill-server
+uv sync --dev
+uv run pytest
+uv run mcp-skill-server serve examples/
+```
+
+## License
+
+MIT