obs-mcp 0.2.0

OBS Studio control server for AI assistants via MCP and the OBS WebSocket protocol
Documentation
#!/usr/bin/env python3
"""Generate the tool-catalog section of skills/obs-mcp/SKILL.md.

Imports the tool table from gen_tools_table.py (the single source of truth)
and renders one bullet per tool: name, description, the OBS request it
maps to, and a compact argument summary. The section is injected between
the TOOL-CATALOG-START / TOOL-CATALOG-END markers in SKILL.md, so the
hand-written parts of the skill survive regeneration.

Usage:
    python3 scripts/gen_skill.py
"""

import importlib.util
import re
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
GEN = ROOT / "scripts" / "gen_tools_table.py"
SKILL = ROOT / "skills" / "obs-mcp" / "SKILL.md"

# Load TOOLS from the generator without executing main().
src = GEN.read_text().split("def rust_kind")[0]
ns = {}
exec(src, ns)
TOOLS = ns["TOOLS"]

# Map tool name -> category from the "# --- category ---" comments in the file.
category_of = {}
current = "general"
for line in GEN.read_text().splitlines():
    m = re.match(r"\s*# --- (.*?) ---\s*$", line)
    if m:
        current = m.group(1)
        continue
    m = re.match(r'\s*\("(obs-[a-z0-9-]+)"', line)
    if m:
        category_of[m.group(1)] = current

TYPE_NAMES = {
    "str": "string",
    "num": "number",
    "bool": "boolean",
    "obj": "object",
    "arr": "array",
}


def param_summary(params):
    if not params:
        return ""
    parts = []
    for pname, pkind, preq, _pdesc in params:
        if pkind.startswith("enum:"):
            kt = "enum"
        else:
            kt = TYPE_NAMES.get(pkind, pkind)
        req = "" if preq else " optional"
        parts.append(f"{pname} ({kt}{req})")
    return ", ".join(parts)


def catalog_markdown():
    lines = []
    # Preserve generator order of categories.
    seen = set()
    for name, req, params, renames, desc in TOOLS:
        cat = category_of.get(name, "general")
        if cat not in seen:
            seen.add(cat)
            raw = cat.split(":")[0].strip()
            # Title-case and normalize the category label for a heading.
            words = []
            for w in raw.split():
                if w == "obs":
                    words.append("OBS")
                elif w in ("32", "v5"):
                    words.append(w)
                else:
                    words.append(w.capitalize())
            title = " ".join(words)
            lines.append("")
            lines.append(f"{title} tools")
            lines.append("")
        args = param_summary(params)
        suffix = f" | {args}" if args else ""
        lines.append(f"- `{name}` — {desc} (OBS request `{req}`{suffix})")
    return "\n".join(lines)


def sync_doc_counts():
    """Rewrite the tool count in README/docs/skill prose from the table.

    The count appears in a few natural-language sentences; each is matched
    by a known phrase and the number is substituted with the current table
    size, so the docs cannot drift from the code. Add a phrase here when a
    new count-bearing sentence is written.
    """
    count = len(TOOLS)
    substitutions = [
        (r"\d+ declarative tools", f"{count} declarative tools"),
        (r"catalog of all \d+ tools", f"catalog of all {count} tools"),
        (r"calls all \d+ tools", f"calls all {count} tools"),
        (r"all \d+ tools; every call returns success", f"all {count} tools; every call returns success"),
        (r"asserts \d+ tools are listed", f"asserts {count} tools are listed"),
        (r"exposes \d+ tools", f"exposes {count} tools"),
    ]
    targets = [
        ROOT / "README.md",
        ROOT / "docs" / "LIVE_TEST.md",
        SKILL,
    ]
    for path in targets:
        text = path.read_text()
        for pattern, replacement in substitutions:
            text = re.sub(pattern, replacement, text)
        path.write_text(text)


def main():
    skill = SKILL.read_text()
    start = "<!-- TOOL-CATALOG-START -->"
    end = "<!-- TOOL-CATALOG-END -->"
    if start not in skill or end not in skill:
        raise SystemExit(f"markers not found in {SKILL}")
    head, _ = skill.split(start, 1)
    _, tail = skill.split(end, 1)
    new_skill = head + start + "\n" + catalog_markdown() + "\n" + end + tail
    SKILL.write_text(new_skill)
    sync_doc_counts()
    print(f"wrote {SKILL} with {len(TOOLS)} tools in the catalog; doc counts synced")


if __name__ == "__main__":
    main()