|
| 1 | +#!/usr/bin/env -S uv run --quiet |
| 2 | +# /// script |
| 3 | +# requires-python = ">=3.10" |
| 4 | +# dependencies = [] |
| 5 | +# /// |
| 6 | +"""Generate Cursor plugin manifest from existing repo metadata. |
| 7 | +
|
| 8 | +Outputs: |
| 9 | +- .cursor-plugin/plugin.json |
| 10 | +
|
| 11 | +Design goals: |
| 12 | +- Keep Claude + Cursor metadata in sync. |
| 13 | +- Reuse `.claude-plugin/plugin.json` as the primary metadata source. |
| 14 | +- Discover skills from `skills/*/SKILL.md` so the manifest tracks the |
| 15 | + catalog automatically. |
| 16 | +- Treat `.mcp.json` as hand-maintained (no MCP server is generated here). |
| 17 | +
|
| 18 | +Usage: |
| 19 | + uv run scripts/generate_cursor_plugin.py # write |
| 20 | + uv run scripts/generate_cursor_plugin.py --check # validate only |
| 21 | +""" |
| 22 | + |
| 23 | +from __future__ import annotations |
| 24 | + |
| 25 | +import argparse |
| 26 | +import json |
| 27 | +import re |
| 28 | +import sys |
| 29 | +from pathlib import Path |
| 30 | + |
| 31 | +ROOT = Path(__file__).resolve().parent.parent |
| 32 | +CLAUDE_PLUGIN_MANIFEST = ROOT / ".claude-plugin" / "plugin.json" |
| 33 | +CURSOR_PLUGIN_DIR = ROOT / ".cursor-plugin" |
| 34 | +CURSOR_PLUGIN_MANIFEST = CURSOR_PLUGIN_DIR / "plugin.json" |
| 35 | +MCP_CONFIG = ROOT / ".mcp.json" |
| 36 | + |
| 37 | +# Fields copied verbatim from the Claude plugin manifest into the Cursor |
| 38 | +# manifest so the two stay in lock-step. |
| 39 | +COPIED_FIELDS = ( |
| 40 | + "description", |
| 41 | + "version", |
| 42 | + "author", |
| 43 | + "homepage", |
| 44 | + "repository", |
| 45 | + "license", |
| 46 | + "keywords", |
| 47 | + "logo", |
| 48 | +) |
| 49 | + |
| 50 | +PLUGIN_NAME_RE = re.compile(r"^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$") |
| 51 | + |
| 52 | + |
| 53 | +def load_json(path: Path) -> dict: |
| 54 | + if not path.exists(): |
| 55 | + raise FileNotFoundError(f"Missing required file: {path}") |
| 56 | + return json.loads(path.read_text(encoding="utf-8")) |
| 57 | + |
| 58 | + |
| 59 | +def parse_frontmatter(text: str) -> dict[str, str]: |
| 60 | + """Return the YAML frontmatter at the top of `text` as a flat mapping. |
| 61 | +
|
| 62 | + Only top-level scalar keys are extracted. That is sufficient for `name`, |
| 63 | + which is all this script needs. |
| 64 | + """ |
| 65 | + match = re.search(r"^---\s*\n(.*?)\n---\s*", text, re.DOTALL) |
| 66 | + if not match: |
| 67 | + return {} |
| 68 | + data: dict[str, str] = {} |
| 69 | + for line in match.group(1).splitlines(): |
| 70 | + # Skip continuation lines so multi-line `description: >-` values |
| 71 | + # don't get parsed as keys. |
| 72 | + if ":" not in line or line.startswith((" ", "\t")): |
| 73 | + continue |
| 74 | + key, value = line.split(":", 1) |
| 75 | + data[key.strip()] = value.strip() |
| 76 | + return data |
| 77 | + |
| 78 | + |
| 79 | +def collect_skills() -> list[str]: |
| 80 | + skills: list[str] = [] |
| 81 | + for skill_md in sorted(ROOT.glob("skills/*/SKILL.md")): |
| 82 | + meta = parse_frontmatter(skill_md.read_text(encoding="utf-8")) |
| 83 | + name = meta.get("name", "").strip() |
| 84 | + if not name: |
| 85 | + continue |
| 86 | + skills.append(name) |
| 87 | + return skills |
| 88 | + |
| 89 | + |
| 90 | +def validate_plugin_name(name: str) -> None: |
| 91 | + if not PLUGIN_NAME_RE.match(name): |
| 92 | + raise ValueError( |
| 93 | + "Invalid plugin name in .claude-plugin/plugin.json: " |
| 94 | + f"'{name}'. Must be lowercase and match {PLUGIN_NAME_RE.pattern}" |
| 95 | + ) |
| 96 | + |
| 97 | + |
| 98 | +def build_cursor_plugin_manifest() -> dict: |
| 99 | + src = load_json(CLAUDE_PLUGIN_MANIFEST) |
| 100 | + |
| 101 | + name = src.get("name") |
| 102 | + if not isinstance(name, str) or not name: |
| 103 | + raise ValueError(".claude-plugin/plugin.json must define a non-empty 'name'") |
| 104 | + validate_plugin_name(name) |
| 105 | + |
| 106 | + skills = collect_skills() |
| 107 | + if not skills: |
| 108 | + raise ValueError("No skills discovered under skills/*/SKILL.md") |
| 109 | + |
| 110 | + # `mcpServers` points at .mcp.json so future MCP servers added there |
| 111 | + # are picked up by Cursor without a manifest change. |
| 112 | + manifest: dict = {"name": name, "skills": "skills", "mcpServers": ".mcp.json"} |
| 113 | + for key in COPIED_FIELDS: |
| 114 | + if key in src: |
| 115 | + manifest[key] = src[key] |
| 116 | + |
| 117 | + return manifest |
| 118 | + |
| 119 | + |
| 120 | +def render_json(data: dict) -> str: |
| 121 | + return json.dumps(data, indent=2, ensure_ascii=False) + "\n" |
| 122 | + |
| 123 | + |
| 124 | +def write_or_check(path: Path, content: str, check: bool) -> bool: |
| 125 | + """Return True when the file is already up-to-date. |
| 126 | +
|
| 127 | + In write mode (check=False) the file is written first, so the return |
| 128 | + value is always True in that branch. |
| 129 | + """ |
| 130 | + current = path.read_text(encoding="utf-8") if path.exists() else None |
| 131 | + if current == content: |
| 132 | + return True |
| 133 | + |
| 134 | + if check: |
| 135 | + return False |
| 136 | + |
| 137 | + path.parent.mkdir(parents=True, exist_ok=True) |
| 138 | + path.write_text(content, encoding="utf-8") |
| 139 | + return True |
| 140 | + |
| 141 | + |
| 142 | +def validate_mcp_config() -> None: |
| 143 | + """Make sure .mcp.json is at least valid JSON shaped like an MCP config.""" |
| 144 | + if not MCP_CONFIG.exists(): |
| 145 | + raise FileNotFoundError( |
| 146 | + f"Missing required file: {MCP_CONFIG.relative_to(ROOT)}. " |
| 147 | + 'Create it with `{"mcpServers": {}}` if there are no servers yet.' |
| 148 | + ) |
| 149 | + data = load_json(MCP_CONFIG) |
| 150 | + if not isinstance(data, dict) or "mcpServers" not in data: |
| 151 | + raise ValueError( |
| 152 | + f"{MCP_CONFIG.relative_to(ROOT)} must be a JSON object with an " |
| 153 | + "`mcpServers` key (use `{}` if no servers are configured)." |
| 154 | + ) |
| 155 | + |
| 156 | + |
| 157 | +def main() -> None: |
| 158 | + parser = argparse.ArgumentParser( |
| 159 | + description="Generate Cursor plugin manifest from .claude-plugin/plugin.json" |
| 160 | + ) |
| 161 | + parser.add_argument( |
| 162 | + "--check", |
| 163 | + action="store_true", |
| 164 | + help="Validate the generated manifest is up to date without writing changes.", |
| 165 | + ) |
| 166 | + args = parser.parse_args() |
| 167 | + |
| 168 | + validate_mcp_config() |
| 169 | + plugin_manifest = render_json(build_cursor_plugin_manifest()) |
| 170 | + ok_plugin = write_or_check(CURSOR_PLUGIN_MANIFEST, plugin_manifest, check=args.check) |
| 171 | + |
| 172 | + if args.check: |
| 173 | + if not ok_plugin: |
| 174 | + print("Generated Cursor manifest is out of date:", file=sys.stderr) |
| 175 | + print(f" - {CURSOR_PLUGIN_MANIFEST.relative_to(ROOT)}", file=sys.stderr) |
| 176 | + print("Run: uv run scripts/generate_cursor_plugin.py", file=sys.stderr) |
| 177 | + sys.exit(1) |
| 178 | + |
| 179 | + print("Cursor plugin manifest is up to date.") |
| 180 | + return |
| 181 | + |
| 182 | + print(f"Wrote {CURSOR_PLUGIN_MANIFEST.relative_to(ROOT)}") |
| 183 | + |
| 184 | + |
| 185 | +if __name__ == "__main__": |
| 186 | + main() |
0 commit comments