dropmcp 0.1.0__py3-none-any.whl

dropmcp/INSTRUCTIONS.default.md

@@ -0,0 +1,21 @@
+This server exposes a curated set of **skills** and **prompts** loaded from a
+filesystem. Skills are returned as tools; prompts are templated messages you
+invoke by name.
+
+### Skills
+
+Check this server's skills when the user is working on a task one of them
+covers:
+
+{{INSTRUCTION_SUMMARIES}}
+
+Each skill tool returns its full instructions plus resource links to any
+supporting files (scripts, templates, references). Call the tool, then follow
+the returned instructions.
+
+### Prompts
+
+This server also exposes prompts — templated messages you can invoke with
+arguments:
+
+{{PROMPT_SUMMARIES}}

dropmcp/__init__.py

@@ -0,0 +1,110 @@
+"""dropmcp — drop a skills/ and prompts/ folder, get a FastMCP server.
+
+Quick start::
+
+    import dropmcp
+    dropmcp.run(skills="skills", prompts="prompts")
+
+Or grab the server to add your own routes/middleware first::
+
+    mcp = dropmcp.create_server(skills="skills", prompts="prompts")
+    # ... customise ...
+    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)
+
+dropmcp serves over streamable-HTTP only — it exists to *share* skills with
+remote clients, not to run locally over stdio.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from dropmcp.config import Settings
+from dropmcp.server import build_server
+
+__all__ = ["create_server", "run", "Settings"]
+
+__version__ = "0.1.0"
+
+_HTTP_TRANSPORT = "streamable-http"
+
+
+def create_server(
+    *,
+    skills: str | Path | None = None,
+    prompts: str | Path | None = None,
+    catalog_defaults: str | Path | None = None,
+    instructions: str | Path | None = None,
+    name: str | None = None,
+    website_url: str | None = None,
+    icon: str | Path | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    ui_enabled: bool | None = None,
+    reload: bool | None = None,
+) -> FastMCP:
+    """Build and return a configured `FastMCP` server without running it.
+
+    Use this when you want to attach custom routes or middleware before
+    serving. Settings are resolved from these kwargs, then `DROPMCP_*`
+    environment variables, then defaults.
+    """
+    settings = Settings.resolve(
+        skills=skills,
+        prompts=prompts,
+        catalog_defaults=catalog_defaults,
+        instructions=instructions,
+        name=name,
+        website_url=website_url,
+        icon=icon,
+        host=host,
+        port=port,
+        ui_enabled=ui_enabled,
+        reload=reload,
+    )
+    return build_server(settings)
+
+
+def run(
+    *,
+    skills: str | Path | None = None,
+    prompts: str | Path | None = None,
+    catalog_defaults: str | Path | None = None,
+    instructions: str | Path | None = None,
+    name: str | None = None,
+    website_url: str | None = None,
+    icon: str | Path | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    ui_enabled: bool | None = None,
+    reload: bool | None = None,
+) -> None:
+    """Build the server and serve it over streamable-HTTP.
+
+    Bind address is controlled by ``host``/``port`` (or ``DROPMCP_HOST`` /
+    ``DROPMCP_PORT``). The catalog UI is served at ``/`` and the MCP endpoint
+    at ``/mcp``.
+    """
+    settings = Settings.resolve(
+        skills=skills,
+        prompts=prompts,
+        catalog_defaults=catalog_defaults,
+        instructions=instructions,
+        name=name,
+        website_url=website_url,
+        icon=icon,
+        host=host,
+        port=port,
+        ui_enabled=ui_enabled,
+        reload=reload,
+    )
+    mcp = build_server(settings)
+
+    mcp.run(
+        transport=_HTTP_TRANSPORT,
+        host=settings.host,
+        port=settings.port,
+        stateless_http=True,
+    )

dropmcp/__main__.py

@@ -0,0 +1,14 @@
+"""``python -m dropmcp`` — serve a dropmcp server configured entirely from
+``DROPMCP_*`` environment variables.
+
+Handy for container / env-only deployments where you don't want to write a
+``server.py``. There are no command-line options: dropmcp is a hosted
+streamable-HTTP server, so everything is driven by the environment.
+"""
+
+from __future__ import annotations
+
+import dropmcp
+
+if __name__ == "__main__":
+    dropmcp.run()

dropmcp/catalog.py

@@ -0,0 +1,285 @@
+"""Discover catalog metadata and asset paths from skills/ and prompts/ layouts.
+
+Skills: skills/{skill-name}/SKILL.md with optional catalog/ assets.
+Prompts: prompts/{prompt-name}/PROMPT.md with optional catalog/ assets.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+log = logging.getLogger(__name__)
+
+SKILL_FILE = "SKILL.md"
+PROMPT_FILE = "PROMPT.md"
+CATALOG_DIR = "catalog"
+SCREENSHOTS_DIR = "screenshots"
+EXAMPLES_DIR = "examples"
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".svg", ".webp"}
+
+
+def _find_image(directory: Path, stem: str) -> Path | None:
+    for ext in sorted(IMAGE_EXTENSIONS):
+        candidate = directory / f"{stem}{ext}"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _parse_frontmatter_meta(path: Path) -> dict[str, Any]:
+    raw = path.read_text(encoding="utf-8")
+    match = FRONTMATTER_RE.match(raw)
+    if not match:
+        raise ValueError(f"{path}: missing YAML frontmatter")
+    return yaml.safe_load(match.group(1)) or {}
+
+
+def _list_screenshot_filenames(screenshots_dir: Path) -> list[str]:
+    if not screenshots_dir.is_dir():
+        return []
+    names: list[str] = []
+    for p in screenshots_dir.iterdir():
+        if (
+            p.is_file()
+            and not p.name.startswith(".")
+            and p.suffix.lower() in IMAGE_EXTENSIONS
+        ):
+            names.append(p.name)
+    return sorted(names)
+
+
+def _list_example_filenames(examples_dir: Path) -> list[str]:
+    if not examples_dir.is_dir():
+        return []
+    names: list[str] = []
+    for p in examples_dir.iterdir():
+        if p.is_file() and not p.name.startswith("."):
+            names.append(p.name)
+    return sorted(names)
+
+
+def _safe_file_in_subdir(parent: Path, filename: str) -> Path | None:
+    if not filename or filename in (".", ".."):
+        return None
+    if Path(filename).name != filename:
+        return None
+    base = parent.resolve()
+    path = (parent / filename).resolve()
+    try:
+        path.relative_to(base)
+    except ValueError:
+        return None
+    return path if path.is_file() else None
+
+
+def _inspect_catalog(catalog_dir: Path) -> tuple[bool, bool, list[str], list[str]]:
+    if not catalog_dir.is_dir():
+        return False, False, [], []
+    hero = _find_image(catalog_dir, "hero")
+    thumb = _find_image(catalog_dir, "thumbnail")
+    screenshots = _list_screenshot_filenames(catalog_dir / SCREENSHOTS_DIR)
+    examples = _list_example_filenames(catalog_dir / EXAMPLES_DIR)
+    return hero is not None, thumb is not None, screenshots, examples
+
+
+@dataclass
+class CatalogEntry:
+    name: str
+    type: str
+    category: str
+    description: str
+    arguments: list[dict]
+    has_hero: bool
+    has_thumbnail: bool
+    screenshot_filenames: list[str]
+    example_filenames: list[str]
+    dir_path: Path
+    item_dir: Path
+
+
+class CatalogProvider:
+    """Discovers catalog assets from skills and prompts directories."""
+
+    def __init__(
+        self,
+        skills_dir: Path,
+        prompts_dir: Path,
+        defaults_dir: Path,
+        *,
+        reload: bool = False,
+    ) -> None:
+        self._skills_dir = Path(skills_dir).resolve()
+        self._prompts_dir = Path(prompts_dir).resolve()
+        self._defaults_dir = Path(defaults_dir).resolve()
+        self._reload = reload
+        self._entries: list[CatalogEntry] | None = None
+
+    def _discover(self) -> list[CatalogEntry]:
+        entries: list[CatalogEntry] = []
+        entries.extend(self._discover_skills())
+        entries.extend(self._discover_prompts())
+        entries.sort(key=lambda e: (e.type, e.name))
+        return entries
+
+    def _discover_skills(self) -> list[CatalogEntry]:
+        found: list[CatalogEntry] = []
+        if not self._skills_dir.is_dir():
+            return found
+
+        for skill_dir in sorted(self._skills_dir.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            main_file = skill_dir / SKILL_FILE
+            if not main_file.is_file():
+                continue
+            try:
+                meta = _parse_frontmatter_meta(main_file)
+                name = str(meta["name"])
+                category = str(meta.get("category", ""))
+                description = str(meta.get("description", ""))
+                item_dir = skill_dir.resolve()
+                catalog_dir = (item_dir / CATALOG_DIR).resolve()
+                has_hero, has_thumb, shots, examples = _inspect_catalog(catalog_dir)
+                found.append(
+                    CatalogEntry(
+                        name=name,
+                        type="skill",
+                        category=category,
+                        description=description,
+                        arguments=[],
+                        has_hero=has_hero,
+                        has_thumbnail=has_thumb,
+                        screenshot_filenames=shots,
+                        example_filenames=examples,
+                        dir_path=catalog_dir,
+                        item_dir=item_dir,
+                    )
+                )
+            except Exception as exc:
+                log.warning("Skipping skill %s: %s", skill_dir, exc)
+        return found
+
+    def _discover_prompts(self) -> list[CatalogEntry]:
+        found: list[CatalogEntry] = []
+        if not self._prompts_dir.is_dir():
+            return found
+
+        for prompt_dir in sorted(self._prompts_dir.iterdir()):
+            if not prompt_dir.is_dir():
+                continue
+            main_file = prompt_dir / PROMPT_FILE
+            if not main_file.is_file():
+                continue
+            try:
+                meta = _parse_frontmatter_meta(main_file)
+                name = str(meta["name"])
+                description = str(meta.get("description", ""))
+                arguments = meta.get("arguments", [])
+                if not isinstance(arguments, list):
+                    arguments = []
+                else:
+                    arguments = [a for a in arguments if isinstance(a, dict)]
+                item_dir = prompt_dir.resolve()
+                catalog_dir = (item_dir / CATALOG_DIR).resolve()
+                has_hero, has_thumb, shots, examples = _inspect_catalog(catalog_dir)
+                found.append(
+                    CatalogEntry(
+                        name=name,
+                        type="prompt",
+                        category="prompts",
+                        description=description,
+                        arguments=arguments,
+                        has_hero=has_hero,
+                        has_thumbnail=has_thumb,
+                        screenshot_filenames=shots,
+                        example_filenames=examples,
+                        dir_path=catalog_dir,
+                        item_dir=item_dir,
+                    )
+                )
+            except Exception as exc:
+                log.warning("Skipping prompt %s: %s", prompt_dir, exc)
+        return found
+
+    def _ensure_discovered(self) -> None:
+        if self._reload or self._entries is None:
+            self._entries = self._discover()
+
+    def get_entries(self) -> list[CatalogEntry]:
+        self._ensure_discovered()
+        return list(self._entries or [])
+
+    def get_entry(self, item_type: str, name: str) -> CatalogEntry | None:
+        self._ensure_discovered()
+        t = item_type.lower()
+        for e in self._entries or []:
+            if e.type == t and e.name == name:
+                return e
+        return None
+
+    def resolve_image_path(
+        self,
+        item_type: str,
+        name: str,
+        image_kind: str,
+        filename: str | None = None,
+    ) -> Path | None:
+        entry = self.get_entry(item_type, name)
+        if entry is None:
+            return None
+        catalog_dir = entry.dir_path
+        kind = image_kind.lower()
+        if kind == "hero":
+            return _find_image(catalog_dir, "hero")
+        if kind == "thumbnail":
+            return _find_image(catalog_dir, "thumbnail")
+        if kind == "screenshot":
+            if not filename:
+                return None
+            shots = catalog_dir / SCREENSHOTS_DIR
+            return _safe_file_in_subdir(shots, filename)
+        return None
+
+    def resolve_example_path(
+        self, item_type: str, name: str, filename: str
+    ) -> Path | None:
+        entry = self.get_entry(item_type, name)
+        if entry is None:
+            return None
+        catalog_dir = entry.dir_path
+        examples = catalog_dir / EXAMPLES_DIR
+        return _safe_file_in_subdir(examples, filename)
+
+    def resolve_thumbnail_path(self, item_type: str, name: str) -> Path | None:
+        """Resolve thumbnail with fallback: thumbnail.* -> hero.* -> defaults/{category}.* -> defaults/default.svg"""
+        entry = self.get_entry(item_type, name)
+        if entry is None:
+            return None
+        catalog_dir = entry.dir_path
+
+        thumb = _find_image(catalog_dir, "thumbnail")
+        if thumb is not None:
+            return thumb
+
+        hero = _find_image(catalog_dir, "hero")
+        if hero is not None:
+            return hero
+
+        if self._defaults_dir.is_dir():
+            fallback = _find_image(self._defaults_dir, entry.category)
+            if fallback is not None:
+                return fallback
+            default_svg = self._defaults_dir / "default.svg"
+            if default_svg.is_file():
+                return default_svg
+
+        return None

dropmcp/config.py

@@ -0,0 +1,156 @@
+"""Runtime configuration for a dropmcp server.
+
+A single `Settings` object holds everything the server needs. Values are
+resolved in priority order: explicit keyword arguments, then environment
+variables (`DROPMCP_*`), then sensible defaults. This keeps the one-liner
+(`dropmcp.run(skills="skills", prompts="prompts")`) ergonomic while letting
+hosted deployments override anything via the environment.
+
+dropmcp serves over streamable-HTTP only — it exists to *share* skills with
+multiple remote clients, so there is no local stdio transport to configure.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+_TRUE = {"1", "true", "yes", "on"}
+_FALSE = {"0", "false", "no", "off"}
+
+DEFAULT_NAME = "dropmcp"
+DEFAULT_SKILLS_DIR = "skills"
+DEFAULT_PROMPTS_DIR = "prompts"
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+INSTRUCTIONS_FILENAME = "INSTRUCTIONS.md"
+DEFAULT_INSTRUCTIONS_RESOURCE = "INSTRUCTIONS.default.md"
+DEFAULT_ICON_RESOURCE = "static/icon.svg"
+
+
+def _env(name: str) -> str | None:
+    value = os.environ.get(name)
+    return value if value else None
+
+
+def _env_bool(name: str) -> bool | None:
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    lowered = value.strip().lower()
+    if lowered in _TRUE:
+        return True
+    if lowered in _FALSE:
+        return False
+    return None
+
+
+def _first(*candidates):
+    for candidate in candidates:
+        if candidate is not None:
+            return candidate
+    return None
+
+
+def _packaged_default_instructions() -> Path:
+    return Path(resources.files("dropmcp") / DEFAULT_INSTRUCTIONS_RESOURCE)
+
+
+def _packaged_default_icon() -> Path:
+    return Path(resources.files("dropmcp") / DEFAULT_ICON_RESOURCE)
+
+
+def _resolve_instructions_path(
+    explicit: str | Path | None,
+    skills_dir: Path,
+) -> Path:
+    """Pick the INSTRUCTIONS template: explicit -> env -> cwd -> packaged default.
+
+    The cwd lookup means a user who drops an `INSTRUCTIONS.md` next to their
+    `skills/` and `prompts/` folders gets it picked up automatically.
+    """
+    chosen = _first(explicit, _env("DROPMCP_INSTRUCTIONS"))
+    if chosen is not None:
+        return Path(chosen)
+
+    for candidate in (Path.cwd() / INSTRUCTIONS_FILENAME, skills_dir.parent / INSTRUCTIONS_FILENAME):
+        if candidate.is_file():
+            return candidate
+
+    return _packaged_default_instructions()
+
+
+def _resolve_icon_path(
+    explicit: str | Path | None,
+    skills_dir: Path,
+) -> Path:
+    chosen = _first(explicit, _env("DROPMCP_ICON"))
+    if chosen is not None:
+        return Path(chosen)
+
+    for candidate in (Path.cwd() / "icon.svg", skills_dir.parent / "icon.svg"):
+        if candidate.is_file():
+            return candidate
+
+    return _packaged_default_icon()
+
+
+@dataclass(frozen=True)
+class Settings:
+    skills_dir: Path
+    prompts_dir: Path
+    catalog_defaults_dir: Path | None
+    instructions_path: Path
+    name: str
+    website_url: str | None
+    icon: Path
+    host: str
+    port: int
+    ui_enabled: bool
+    reload: bool
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        skills: str | Path | None = None,
+        prompts: str | Path | None = None,
+        catalog_defaults: str | Path | None = None,
+        instructions: str | Path | None = None,
+        name: str | None = None,
+        website_url: str | None = None,
+        icon: str | Path | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        ui_enabled: bool | None = None,
+        reload: bool | None = None,
+    ) -> "Settings":
+        skills_dir = Path(
+            _first(skills, _env("DROPMCP_SKILLS"), DEFAULT_SKILLS_DIR)
+        )
+        prompts_dir = Path(
+            _first(prompts, _env("DROPMCP_PROMPTS"), DEFAULT_PROMPTS_DIR)
+        )
+
+        catalog_defaults_raw = _first(catalog_defaults, _env("DROPMCP_CATALOG_DEFAULTS"))
+        catalog_defaults_dir = (
+            Path(catalog_defaults_raw) if catalog_defaults_raw is not None else None
+        )
+
+        port_raw = _first(port, _env("DROPMCP_PORT"), DEFAULT_PORT)
+
+        return cls(
+            skills_dir=skills_dir,
+            prompts_dir=prompts_dir,
+            catalog_defaults_dir=catalog_defaults_dir,
+            instructions_path=_resolve_instructions_path(instructions, skills_dir),
+            name=_first(name, _env("DROPMCP_NAME"), DEFAULT_NAME),
+            website_url=_first(website_url, _env("DROPMCP_WEBSITE_URL")),
+            icon=_resolve_icon_path(icon, skills_dir),
+            host=_first(host, _env("DROPMCP_HOST"), DEFAULT_HOST),
+            port=int(port_raw),
+            ui_enabled=_first(ui_enabled, _env_bool("DROPMCP_UI"), True),
+            reload=_first(reload, _env_bool("DROPMCP_RELOAD"), False),
+        )

dropmcp/instructions.py

@@ -0,0 +1,121 @@
+"""Aggregate per-skill / per-prompt `instruction_summary` frontmatter into the
+server-level instructions string the MCP client sees.
+
+Each skill or prompt can declare a short phrase (or list of phrases) in its
+YAML frontmatter under `instruction_summary`. At server startup we collect
+them all and substitute them into `INSTRUCTIONS.md` wherever the
+`{{INSTRUCTION_SUMMARIES}}` (skills) and `{{PROMPT_SUMMARIES}}` (prompts)
+placeholders appear, rendered as markdown bullet lists. The placeholders
+let the rest of `INSTRUCTIONS.md` stay hand-written while the bullet lists
+stay in lockstep with whatever is currently installed under `skills/` and
+`prompts/`.
+
+If a placeholder is absent the template is returned unchanged for that
+section, so existing deployments that haven't adopted a placeholder still
+work.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+
+import yaml
+
+log = logging.getLogger(__name__)
+
+SKILLS_PLACEHOLDER = "{{INSTRUCTION_SUMMARIES}}"
+PROMPTS_PLACEHOLDER = "{{PROMPT_SUMMARIES}}"
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+def _parse_frontmatter(path: Path) -> dict:
+    raw = path.read_text(encoding="utf-8")
+    match = _FRONTMATTER_RE.match(raw)
+    if not match:
+        return {}
+    try:
+        return yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError as exc:
+        log.warning("Failed to parse frontmatter for %s: %s", path, exc)
+        return {}
+
+
+def _extract_summaries(meta: dict) -> list[str]:
+    value = meta.get("instruction_summary")
+    if value is None:
+        return []
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return []
+
+
+def _collect(root: Path, main_file: str) -> list[tuple[str, str]]:
+    """Return `(name, summary)` pairs for every entry under `root`.
+
+    `name` is taken from the YAML frontmatter; if absent we fall back to the
+    directory name so the bullet still has something the agent can call.
+    """
+    if not root.is_dir():
+        return []
+    pairs: list[tuple[str, str]] = []
+    for sub in sorted(root.iterdir()):
+        f = sub / main_file
+        if not f.is_file():
+            continue
+        meta = _parse_frontmatter(f)
+        name = str(meta.get("name") or sub.name).strip()
+        for summary in _extract_summaries(meta):
+            pairs.append((name, summary))
+    return pairs
+
+
+def _render_bullets(
+    pairs: list[tuple[str, str]],
+    empty_message: str,
+) -> str:
+    if not pairs:
+        return empty_message
+    return "\n".join(f"- `{name}` — {summary}" for name, summary in pairs)
+
+
+def build_server_instructions(
+    template_path: Path,
+    skills_dir: Path,
+    prompts_dir: Path,
+) -> str | None:
+    """Read `INSTRUCTIONS.md` and substitute the summaries placeholders.
+
+    `{{INSTRUCTION_SUMMARIES}}` is replaced with a bullet list of skill
+    `instruction_summary` values; `{{PROMPT_SUMMARIES}}` is replaced with the
+    same for prompts. Returns None if the template file is missing so callers
+    can pass `None` through to FastMCP (which treats it as "no instructions").
+    """
+    if not template_path.exists():
+        return None
+    template = template_path.read_text(encoding="utf-8").strip()
+
+    if SKILLS_PLACEHOLDER in template:
+        template = template.replace(
+            SKILLS_PLACEHOLDER,
+            _render_bullets(
+                _collect(skills_dir, "SKILL.md"),
+                "_(no skills have declared an instruction_summary yet)_",
+            ),
+        )
+
+    if PROMPTS_PLACEHOLDER in template:
+        template = template.replace(
+            PROMPTS_PLACEHOLDER,
+            _render_bullets(
+                _collect(prompts_dir, "PROMPT.md"),
+                "_(no prompts have declared an instruction_summary yet)_",
+            ),
+        )
+
+    return template