mcpc-cli 0.1.0__py3-none-any.whl

mcpc/__init__.py

@@ -0,0 +1,3 @@
+"""mcpc — CLI for the MCP Contract specification."""
+
+__version__ = "0.1.0"

mcpc/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m mcpc`."""
+
+from mcpc.cli import main
+
+main()

mcpc/cli.py

@@ -0,0 +1,172 @@
+"""mcpc CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from mcpc import __version__
+from mcpc.init import TEMPLATES, init_bundle
+from mcpc.pack import pack_bundle
+from mcpc.test import test_bundle
+from mcpc.unpack import unpack_bundle
+from mcpc.validate import validate_bundle
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcpc",
+        description="CLI for the MCP Contract specification.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"mcpc {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # -- validate --
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate an MCP Contract bundle.",
+        description=(
+            "Validates the manifest against the schema, checks that all "
+            "provides/consumes contracts are satisfied, and verifies that "
+            "referenced files exist."
+        ),
+    )
+    validate_parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to the bundle directory (default: current directory).",
+    )
+    validate_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only print errors, suppress informational output.",
+    )
+
+    # -- init --
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Scaffold a new MCP Contract bundle.",
+        description="Creates a new bundle directory with manifest and starter files.",
+    )
+    init_parser.add_argument(
+        "name",
+        help="Bundle name (lowercase, hyphens only).",
+    )
+    init_parser.add_argument(
+        "--path",
+        default=".",
+        help="Parent directory for the new bundle (default: current directory).",
+    )
+    init_parser.add_argument(
+        "--template",
+        choices=list(TEMPLATES.keys()),
+        default="full",
+        help="Bundle template (default: full).",
+    )
+
+    # -- pack --
+    pack_parser = subparsers.add_parser(
+        "pack",
+        help="Pack a bundle into a .mcpc archive.",
+        description=(
+            "Validates the bundle, then creates a .mcpc archive (zip) "
+            "containing all bundle files."
+        ),
+    )
+    pack_parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to the bundle directory (default: current directory).",
+    )
+    pack_parser.add_argument(
+        "--output", "-o",
+        default=None,
+        help="Output file path (default: <name>-<version>.mcpc in parent directory).",
+    )
+    pack_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only print errors, suppress informational output.",
+    )
+
+    # -- test --
+    test_parser = subparsers.add_parser(
+        "test",
+        help="Run structural tests on bundle layers.",
+        description=(
+            "Tests layer content quality: prompt frontmatter, schema "
+            "conventions, tool syntax, and app structure."
+        ),
+    )
+    test_parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to the bundle directory (default: current directory).",
+    )
+    test_parser.add_argument(
+        "--layer",
+        choices=["prompts", "schemas", "tools", "apps"],
+        default=None,
+        help="Test only a specific layer.",
+    )
+    test_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only print failures, suppress informational output.",
+    )
+
+    # -- unpack --
+    unpack_parser = subparsers.add_parser(
+        "unpack",
+        help="Extract a .mcpc archive into a bundle directory.",
+        description=(
+            "Extracts a .mcpc archive, verifies it contains a valid "
+            "manifest, and writes the bundle to a directory."
+        ),
+    )
+    unpack_parser.add_argument(
+        "archive",
+        help="Path to the .mcpc archive.",
+    )
+    unpack_parser.add_argument(
+        "--output", "-o",
+        default=None,
+        help="Output directory (default: archive stem in current directory).",
+    )
+    unpack_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only print errors, suppress informational output.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "validate":
+        ok = validate_bundle(args.path, quiet=args.quiet)
+        sys.exit(0 if ok else 1)
+
+    if args.command == "init":
+        ok = init_bundle(args.name, args.path, args.template)
+        sys.exit(0 if ok else 1)
+
+    if args.command == "pack":
+        ok = pack_bundle(args.path, output=args.output, quiet=args.quiet)
+        sys.exit(0 if ok else 1)
+
+    if args.command == "test":
+        ok = test_bundle(args.path, layer=args.layer, quiet=args.quiet)
+        sys.exit(0 if ok else 1)
+
+    if args.command == "unpack":
+        ok = unpack_bundle(args.archive, output=args.output, quiet=args.quiet)
+        sys.exit(0 if ok else 1)

mcpc/init.py

@@ -0,0 +1,300 @@
+"""Scaffold a new MCP Contract bundle."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+_BOLD = "\033[1m"
+_GREEN = "\033[32m"
+_CYAN = "\033[36m"
+_RESET = "\033[0m"
+
+
+def _supports_color() -> bool:
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _fmt(code: str, text: str) -> str:
+    return f"{code}{text}{_RESET}" if _supports_color() else text
+
+
+# ---------------------------------------------------------------------------
+# Templates
+# ---------------------------------------------------------------------------
+
+TEMPLATES = {
+    "full": {
+        "description": "Complete bundle with all layers (prompts, tools, apps, skills)",
+        "layers": ["prompts", "tools", "apps", "skills", "schemas"],
+    },
+    "prompts-only": {
+        "description": "Minimal bundle with prompts layer only — no tools, apps, or skills",
+        "layers": ["prompts", "schemas"],
+    },
+}
+
+
+def _make_manifest(name: str, template: str) -> dict:
+    manifest: dict = {
+        "$schema": "https://mcpcontracts.com/schema/0.1.0.json",
+        "name": name,
+        "version": "0.1.0",
+        "description": "",
+        "author": {"name": ""},
+        "license": "Apache-2.0",
+        "layers": {},
+    }
+
+    layers = manifest["layers"]
+
+    if template in ("full", "prompts-only"):
+        layers["prompts"] = {
+            "entry": "prompts/main.md",
+            "provides": [
+                {
+                    "name": f"{name}-output",
+                    "schema": f"schemas/{name}-output.json",
+                    "description": f"Output shape for {name} workflow.",
+                }
+            ],
+        }
+
+    if template == "full":
+        layers["tools"] = {
+            "entry": "tools/server.py",
+            "runtime": "python",
+            "provides": [
+                {
+                    "name": f"{name}-data",
+                    "schema": f"schemas/{name}-data.json",
+                    "description": f"Data provided by {name} tool server.",
+                }
+            ],
+        }
+        layers["apps"] = {
+            "entry": "apps/main.html",
+            "consumes": [
+                {
+                    "name": f"{name}-data",
+                    "schema": f"schemas/{name}-data.json",
+                },
+                {
+                    "name": f"{name}-output",
+                    "schema": f"schemas/{name}-output.json",
+                },
+            ],
+        }
+        layers["skills"] = {
+            "targets": {
+                "claude": "skills/claude.md",
+            }
+        }
+        manifest["compiler_compatibility"] = ["claude"]
+        manifest["compose"] = {
+            "chain": ["prompts", "tools", "apps"],
+            "fallback": "prompts-only",
+        }
+    else:
+        manifest["compiler_compatibility"] = ["claude", "gpt", "gemini"]
+        manifest["compose"] = {
+            "chain": ["prompts"],
+            "fallback": "prompts-only",
+        }
+
+    return manifest
+
+
+def _make_schema(name: str, title: str, description: str) -> dict:
+    return {
+        "$id": f"https://mcpcontracts.com/schemas/{name}/0.1.0",
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": title,
+        "description": description,
+        "type": "object",
+        "required": [],
+        "properties": {},
+    }
+
+
+def _make_prompt(bundle_name: str, provides_name: str) -> str:
+    return f"""---
+name: {bundle_name}
+version: 0.1.0
+description: Primary methodology for {bundle_name}.
+provides: {provides_name}
+---
+
+# {bundle_name.replace('-', ' ').title()}
+
+Describe your workflow's reasoning methodology here.
+
+## Methodology
+
+1. **Step one** — What to analyze first.
+2. **Step two** — How to structure the analysis.
+3. **Step three** — What output to produce.
+
+## Output Shape
+
+The analysis produces structured output conforming to the
+`{provides_name}` schema.
+"""
+
+
+def _make_tool_stub(bundle_name: str) -> str:
+    return f'''"""
+{bundle_name} MCP Tool Server (Stub)
+
+Implement your MCP tools here. Each tool should:
+  - Declare typed input/output schemas in schemas/
+  - Not embed reasoning logic (that belongs in prompts/)
+  - Not assume a specific prompt or app layer
+"""
+'''
+
+
+def _make_app_stub(bundle_name: str) -> str:
+    return f"""<!--
+  {bundle_name} App (Stub)
+
+  Implement your interactive view here. The app should:
+    - Declare every schema it consumes in the manifest
+    - Not call external APIs directly (data flows through tools)
+    - Be renderable with mock data for independent testing
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>{bundle_name.replace('-', ' ').title()}</title>
+</head>
+<body>
+  <h1>{bundle_name.replace('-', ' ').title()}</h1>
+</body>
+</html>
+"""
+
+
+def _make_skill(bundle_name: str) -> str:
+    return f"""---
+target: claude
+version: 0.1.0
+---
+
+# Claude Platform Skill
+
+Platform-specific adaptation for running {bundle_name} on Claude.
+
+## Tool Registration
+
+Register the tool server via MCP stdio transport in Claude Desktop config.
+
+## Context Window
+
+Estimate your prompt chain token count here. Claude Opus supports 200k context.
+
+## Graceful Degradation
+
+If the tool server is unavailable, the prompt layer should still produce
+useful output from the LLM's training data.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def init_bundle(name: str, path: str, template: str) -> bool:
+    """Scaffold a new MCP Contract bundle. Returns True on success."""
+    bundle_dir = Path(path).resolve() / name
+
+    if bundle_dir.exists():
+        print(f"  error: {bundle_dir} already exists", file=sys.stderr)
+        return False
+
+    tmpl = TEMPLATES[template]
+    manifest = _make_manifest(name, template)
+
+    print(f"\n{_fmt(_BOLD, 'mcpc init')} {name} ({tmpl['description']})\n")
+
+    # Create directories
+    dirs = [bundle_dir / layer for layer in tmpl["layers"]]
+    for d in dirs:
+        d.mkdir(parents=True, exist_ok=True)
+
+    created: list[str] = []
+
+    # Write manifest
+    manifest_path = bundle_dir / "mcp-contract.json"
+    with open(manifest_path, "w") as f:
+        json.dump(manifest, f, indent=2)
+        f.write("\n")
+    created.append("mcp-contract.json")
+
+    # Write prompt
+    prompt_path = bundle_dir / "prompts" / "main.md"
+    with open(prompt_path, "w") as f:
+        f.write(_make_prompt(name, f"{name}-output"))
+    created.append("prompts/main.md")
+
+    # Write output schema
+    schema_path = bundle_dir / "schemas" / f"{name}-output.json"
+    with open(schema_path, "w") as f:
+        json.dump(
+            _make_schema(
+                f"{name}-output",
+                f"{name.replace('-', ' ').title()} Output",
+                f"Output shape for {name} workflow.",
+            ),
+            f,
+            indent=2,
+        )
+        f.write("\n")
+    created.append(f"schemas/{name}-output.json")
+
+    if template == "full":
+        # Data schema
+        data_schema_path = bundle_dir / "schemas" / f"{name}-data.json"
+        with open(data_schema_path, "w") as f:
+            json.dump(
+                _make_schema(
+                    f"{name}-data",
+                    f"{name.replace('-', ' ').title()} Data",
+                    f"Data provided by {name} tool server.",
+                ),
+                f,
+                indent=2,
+            )
+            f.write("\n")
+        created.append(f"schemas/{name}-data.json")
+
+        # Tool stub
+        tool_path = bundle_dir / "tools" / "server.py"
+        with open(tool_path, "w") as f:
+            f.write(_make_tool_stub(name))
+        created.append("tools/server.py")
+
+        # App stub
+        app_path = bundle_dir / "apps" / "main.html"
+        with open(app_path, "w") as f:
+            f.write(_make_app_stub(name))
+        created.append("apps/main.html")
+
+        # Skill
+        skill_path = bundle_dir / "skills" / "claude.md"
+        with open(skill_path, "w") as f:
+            f.write(_make_skill(name))
+        created.append("skills/claude.md")
+
+    # Report
+    for f in created:
+        print(f"  {_fmt(_GREEN, '+')} {f}")
+
+    print(f"\n{_fmt(_CYAN, '  info:')}  created {len(created)} files in {bundle_dir}")
+    print(f"{_fmt(_CYAN, '  info:')}  run {_fmt(_BOLD, f'mcpc validate {name}')} to check\n")
+
+    return True

mcpc/pack.py

@@ -0,0 +1,124 @@
+"""Pack an MCP Contract bundle into a .mcpc archive.
+
+Validates the bundle first, then creates a zip archive with the .mcpc
+extension containing all bundle files. The archive preserves the
+directory structure relative to the bundle root.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import zipfile
+from pathlib import Path
+
+from mcpc.validate import validate_bundle
+
+
+_BOLD = "\033[1m"
+_RED = "\033[31m"
+_GREEN = "\033[32m"
+_CYAN = "\033[36m"
+_RESET = "\033[0m"
+
+
+def _supports_color() -> bool:
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _fmt(code: str, text: str) -> str:
+    return f"{code}{text}{_RESET}" if _supports_color() else text
+
+
+def _error(msg: str) -> str:
+    return _fmt(_RED, f"  error: {msg}")
+
+
+def _info(msg: str) -> str:
+    return _fmt(_CYAN, f"  info:  {msg}")
+
+
+def _ok(msg: str) -> str:
+    return _fmt(_GREEN, f"  ok:    {msg}")
+
+
+# ---------------------------------------------------------------------------
+# File collection
+# ---------------------------------------------------------------------------
+
+# Files/directories to always exclude from the archive
+EXCLUDE_DIRS = {".git", "__pycache__", "node_modules", ".venv", "venv", ".mypy_cache"}
+EXCLUDE_FILES = {".DS_Store", "Thumbs.db"}
+
+
+def _collect_files(bundle_dir: Path) -> list[Path]:
+    """Collect all files in the bundle directory, excluding common junk."""
+    files: list[Path] = []
+    for root, dirs, filenames in os.walk(bundle_dir):
+        # Prune excluded directories in-place
+        dirs[:] = [d for d in dirs if d not in EXCLUDE_DIRS and not d.startswith(".")]
+        for name in filenames:
+            if name in EXCLUDE_FILES:
+                continue
+            files.append(Path(root) / name)
+    return sorted(files)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def pack_bundle(path: str, output: str | None = None, quiet: bool = False) -> bool:
+    """Pack an MCP Contract bundle into a .mcpc archive. Returns True on success."""
+    bundle_dir = Path(path).resolve()
+
+    if not quiet:
+        print(f"\n{_fmt(_BOLD, 'mcpc pack')} {bundle_dir}\n")
+
+    # Step 1: Validate
+    if not quiet:
+        print(_info("validating bundle..."))
+
+    valid = validate_bundle(str(bundle_dir), quiet=True)
+    if not valid:
+        print(_error("bundle validation failed — run 'mcpc validate' for details"))
+        return False
+
+    if not quiet:
+        print(_ok("validation passed"))
+
+    # Step 2: Determine output path
+    manifest_path = bundle_dir / "mcp-contract.json"
+    with open(manifest_path) as f:
+        manifest = json.load(f)
+
+    name = manifest.get("name", "bundle")
+    version = manifest.get("version", "0.0.0")
+
+    if output is not None:
+        out_path = Path(output).resolve()
+    else:
+        out_path = bundle_dir.parent / f"{name}-{version}.mcpc"
+
+    # Step 3: Collect files
+    files = _collect_files(bundle_dir)
+
+    if not quiet:
+        print(_info(f"packing {len(files)} files..."))
+
+    # Step 4: Create archive
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for file_path in files:
+            arcname = file_path.relative_to(bundle_dir)
+            zf.write(file_path, arcname)
+
+    size_kb = out_path.stat().st_size / 1024
+
+    if not quiet:
+        print()
+        print(_ok(f"created {out_path.name} ({size_kb:.1f} KB)"))
+        print(_info(f"path: {out_path}"))
+        print()
+
+    return True