mcpc-cli 0.1.0__tar.gz

mcpc_cli-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: mcpc-cli
+Version: 0.1.0
+Summary: CLI for the MCP Contract specification — validate, inspect, and manage contract bundles.
+Author: Joe Fullerton
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://mcpcontracts.com
+Project-URL: Repository, https://github.com/jmfullerton96/mcp-contract
+Project-URL: Specification, https://github.com/jmfullerton96/mcp-contract/blob/main/SPEC.md
+Keywords: mcp,ai,llm,composability,json-schema,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# MCP Contract
+
+[![CI](https://github.com/jmfullerton96/mcp-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/jmfullerton96/mcp-contract/actions/workflows/ci.yml)
+[![Spec](https://img.shields.io/badge/spec-v0.1.0--draft-blue)](SPEC.md)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
+[![JSON Schema](https://img.shields.io/badge/JSON%20Schema-draft%202020--12-orange)](schema/mcp-contract.schema.json)
+[![Website](https://img.shields.io/badge/web-mcpcontracts.com-purple)](https://mcpcontracts.com)
+
+A specification for composable AI workflow bundles with typed contracts between layers.
+
+## The Problem
+
+MCP servers are monoliths. If you want to use one server's reasoning prompts with another server's tools and a third server's UI, you fork all three. MCP Contract fixes this by separating bundles into independently authored, versioned, and composable layers.
+
+## The Layers
+
+| Layer | Role | Analogy |
+|---|---|---|
+| **Prompts** | Reasoning logic | Source code |
+| **Tools** | State + execution | Runtime libraries |
+| **Apps** | Interactive views | UI framework |
+| **Skills** | Platform adaptation | Compiler flags |
+| **Compiler** | The LLM | gcc, clang, rustc |
+
+Layers are wired together through **contracts** — typed `provides`/`consumes` declarations backed by JSON Schema. A prompt layer provides an output shape. A tool layer provides data schemas. An app layer consumes both.
+
+## Quick Start
+
+```
+my-workflow/
+├── mcp-contract.json      # Manifest
+├── prompts/               # Markdown reasoning
+├── tools/                 # MCP server
+├── apps/                  # Interactive UIs
+├── schemas/               # JSON Schema contracts
+└── skills/                # Platform hints
+```
+
+See [SPEC.md](SPEC.md) for the full specification.
+
+## Reference Implementation
+
+[Synth Ops](https://github.com/jmfullerton96/synthops) — intelligent infrastructure operations built as an MCP Contract bundle.
+
+## Manifest Schema
+
+The JSON Schema for validating `mcp-contract.json` manifests is at [`schema/mcp-contract.schema.json`](schema/mcp-contract.schema.json).
+
+Reference it in your manifest:
+
+```json
+{
+  "$schema": "https://mcpcontracts.com/schema/0.1.0.json",
+  "name": "my-workflow",
+  "version": "0.1.0",
+  "layers": { ... }
+}
+```
+
+## Status
+
+**v0.1.0-draft** — Spec, manifest schema, CLI (`mcpc validate`, `init`, `pack`, `test`), and one reference implementation.
+
+## License
+
+Apache-2.0

mcpc_cli-0.1.0/README.md

@@ -0,0 +1,66 @@
+# MCP Contract
+
+[![CI](https://github.com/jmfullerton96/mcp-contract/actions/workflows/ci.yml/badge.svg)](https://github.com/jmfullerton96/mcp-contract/actions/workflows/ci.yml)
+[![Spec](https://img.shields.io/badge/spec-v0.1.0--draft-blue)](SPEC.md)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
+[![JSON Schema](https://img.shields.io/badge/JSON%20Schema-draft%202020--12-orange)](schema/mcp-contract.schema.json)
+[![Website](https://img.shields.io/badge/web-mcpcontracts.com-purple)](https://mcpcontracts.com)
+
+A specification for composable AI workflow bundles with typed contracts between layers.
+
+## The Problem
+
+MCP servers are monoliths. If you want to use one server's reasoning prompts with another server's tools and a third server's UI, you fork all three. MCP Contract fixes this by separating bundles into independently authored, versioned, and composable layers.
+
+## The Layers
+
+| Layer | Role | Analogy |
+|---|---|---|
+| **Prompts** | Reasoning logic | Source code |
+| **Tools** | State + execution | Runtime libraries |
+| **Apps** | Interactive views | UI framework |
+| **Skills** | Platform adaptation | Compiler flags |
+| **Compiler** | The LLM | gcc, clang, rustc |
+
+Layers are wired together through **contracts** — typed `provides`/`consumes` declarations backed by JSON Schema. A prompt layer provides an output shape. A tool layer provides data schemas. An app layer consumes both.
+
+## Quick Start
+
+```
+my-workflow/
+├── mcp-contract.json      # Manifest
+├── prompts/               # Markdown reasoning
+├── tools/                 # MCP server
+├── apps/                  # Interactive UIs
+├── schemas/               # JSON Schema contracts
+└── skills/                # Platform hints
+```
+
+See [SPEC.md](SPEC.md) for the full specification.
+
+## Reference Implementation
+
+[Synth Ops](https://github.com/jmfullerton96/synthops) — intelligent infrastructure operations built as an MCP Contract bundle.
+
+## Manifest Schema
+
+The JSON Schema for validating `mcp-contract.json` manifests is at [`schema/mcp-contract.schema.json`](schema/mcp-contract.schema.json).
+
+Reference it in your manifest:
+
+```json
+{
+  "$schema": "https://mcpcontracts.com/schema/0.1.0.json",
+  "name": "my-workflow",
+  "version": "0.1.0",
+  "layers": { ... }
+}
+```
+
+## Status
+
+**v0.1.0-draft** — Spec, manifest schema, CLI (`mcpc validate`, `init`, `pack`, `test`), and one reference implementation.
+
+## License
+
+Apache-2.0

mcpc_cli-0.1.0/mcpc/__init__.py

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

mcpc_cli-0.1.0/mcpc/__main__.py

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

mcpc_cli-0.1.0/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_cli-0.1.0/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