mcp-skill-server CLAUDE.md

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

# 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