pytyr-mcp 0.0.1__tar.gz

pytyr_mcp-0.0.1/.github/workflows/ci_pytest.yml

@@ -0,0 +1,43 @@
+name: CI Pytest
+
+on:
+  push:
+    branches-ignore:
+      - test-pypi
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --no-cache-dir --upgrade pip
+          python -m pip install --no-cache-dir --verbose .[dev]
+        env:
+          PIP_NO_CACHE_DIR: 1
+
+      - name: Import package
+        run: python -c "import pytyr_mcp; print(pytyr_mcp.__version__)"
+
+      - name: Test
+        run: |
+          if [ -d tests ]; then
+            pytest tests
+          else
+            echo "No tests directory yet; import check completed."
+          fi

pytyr_mcp-0.0.1/.github/workflows/ci_release.yml

@@ -0,0 +1,33 @@
+name: CI Release
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build_distributions:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build frontend
+        run: |
+          python -m pip install --no-cache-dir --upgrade pip
+          python -m pip install --no-cache-dir build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*

pytyr_mcp-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build_distributions:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build frontend
+        run: |
+          python -m pip install --no-cache-dir --upgrade pip
+          python -m pip install --no-cache-dir build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/*
+
+  publish:
+    needs:
+      - build_distributions
+    runs-on: ubuntu-latest
+
+    if: github.repository_owner == 'planning-and-learning'
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check version matches tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          TAG=${GITHUB_REF#refs/tags/v}
+
+          echo "Package version: $VERSION"
+          echo "Git tag: $TAG"
+
+          if [ "$VERSION" != "$TAG" ]; then
+            echo "Version mismatch: pyproject.toml=$VERSION tag=$TAG"
+            exit 1
+          fi
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+
+      - name: Inspect distributions
+        run: find dist -maxdepth 1 -type f
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true

pytyr_mcp-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+pytyr-mcp-output/
+
+venv/
+env/
+ENV/
+.env
+.env.*
+.mypy_cache/
+.pyre/
+.coverage
+coverage.xml
+htmlcov/
+.eggs/
+.wheelhouse/
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo

pytyr_mcp-0.0.1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: pytyr-mcp
+Version: 0.0.1
+Summary: MCP server exposing pytyr planning tools for planning-and-learning agents
+Author: Dominik Drexler
+Requires-Python: >=3.13
+Requires-Dist: fastmcp>=2
+Requires-Dist: pytyr<0.1,>=0.0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytyr-mcp
+
+MCP server exposing pytyr planning tools for planning-and-learning agents.
+
+## Roles
+
+Set `PYTYR_MCP_ROLE` before launching the server. The server and invoke CLI fail closed when the role is missing, so restricted agents must be launched with an explicit role:
+
+- `planning/sample`: generator inspection and sampling tools.
+- `planning/solvability`: solvability proof tool.
+- `planning`: both sampling and solvability planning tools.
+- `all`: every pytyr MCP tool; use only for trusted, unrestricted local maintenance.
+
+Slash roles also accept dotted aliases such as `planning.solvability`. The server rejects missing or unknown roles at startup.
+
+## Output Contract
+
+Sampling and solvability tools write layered artifacts under the requested `output_dir`. If that directory already contains output, the tool allocates a numbered child directory such as `run-002` instead of overwriting. Results include `primary` orchestration fields, a structured `summary`, and `items` with relative paths to generated tasks, invalid configs, or proof artifacts.

pytyr_mcp-0.0.1/README.md

@@ -0,0 +1,18 @@
+# pytyr-mcp
+
+MCP server exposing pytyr planning tools for planning-and-learning agents.
+
+## Roles
+
+Set `PYTYR_MCP_ROLE` before launching the server. The server and invoke CLI fail closed when the role is missing, so restricted agents must be launched with an explicit role:
+
+- `planning/sample`: generator inspection and sampling tools.
+- `planning/solvability`: solvability proof tool.
+- `planning`: both sampling and solvability planning tools.
+- `all`: every pytyr MCP tool; use only for trusted, unrestricted local maintenance.
+
+Slash roles also accept dotted aliases such as `planning.solvability`. The server rejects missing or unknown roles at startup.
+
+## Output Contract
+
+Sampling and solvability tools write layered artifacts under the requested `output_dir`. If that directory already contains output, the tool allocates a numbered child directory such as `run-002` instead of overwriting. Results include `primary` orchestration fields, a structured `summary`, and `items` with relative paths to generated tasks, invalid configs, or proof artifacts.

pytyr_mcp-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytyr-mcp"
+version = "0.0.1"
+description = "MCP server exposing pytyr planning tools for planning-and-learning agents"
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [
+    {name = "Dominik Drexler"},
+]
+dependencies = [
+    "fastmcp>=2",
+    "pytyr>=0.0.24,<0.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.8",
+]
+
+[project.scripts]
+pytyr-mcp-invoke = "pytyr_mcp.invoke:main"
+pytyr-mcp = "pytyr_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytyr_mcp"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"

pytyr_mcp-0.0.1/src/pytyr_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP tools for pytyr."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.1"

pytyr_mcp-0.0.1/src/pytyr_mcp/artifacts.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pytyr_mcp.paths import relative_to
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("x", encoding="utf-8") as fh:
+        fh.write(json.dumps(data, indent=2, sort_keys=True) + "\n")
+
+
+RESERVATION_MARKER = ".pytyr-mcp-output"
+
+
+def has_existing_output(output_dir: Path) -> bool:
+    return any(
+        (output_dir / name).exists()
+        for name in (RESERVATION_MARKER, "summary.json", "summary.md", "raw", "tasks", "domain.pddl")
+    )
+
+
+def _reserve_output_dir(output_dir: Path) -> bool:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    if has_existing_output(output_dir):
+        return False
+    try:
+        with (output_dir / RESERVATION_MARKER).open("x", encoding="utf-8") as fh:
+            fh.write("reserved\n")
+    except FileExistsError:
+        return False
+    return True
+
+
+def fresh_output_dir(output_dir: Path) -> Path:
+    if _reserve_output_dir(output_dir):
+        return output_dir
+    for index in range(2, 10000):
+        candidate = output_dir / f"run-{index:03d}"
+        if _reserve_output_dir(candidate):
+            return candidate
+    raise RuntimeError(f"could not allocate fresh Tyr MCP output directory under {output_dir}")
+
+
+def _summary_task_path(task: dict[str, Any], output_dir: Path) -> str:
+    raw_path = task.get("path")
+    if raw_path is None:
+        return ""
+    path = Path(str(raw_path))
+    if not path.is_absolute():
+        return path.as_posix()
+    try:
+        return path.relative_to(output_dir).as_posix()
+    except ValueError:
+        return "<omitted: outside output_dir>"
+
+
+def write_solvability_summary(
+    *,
+    tool: str,
+    status: str,
+    output_dir: Path,
+    metadata: dict[str, Any],
+    tasks: list[dict[str, Any]],
+    stdout: str = "",
+    stderr: str = "",
+) -> dict[str, Any]:
+    output_dir = fresh_output_dir(output_dir)
+    raw_dir = output_dir / "raw"
+    raw_dir.mkdir(parents=True, exist_ok=True)
+    with (raw_dir / "stdout.txt").open("x", encoding="utf-8") as fh:
+        fh.write(stdout)
+    with (raw_dir / "stderr.txt").open("x", encoding="utf-8") as fh:
+        fh.write(stderr)
+
+    by_status: dict[str, list[dict[str, Any]]] = {}
+    for task in tasks:
+        by_status.setdefault(str(task["status"]), []).append(task)
+
+    task_dir = output_dir / "tasks"
+    task_items = []
+    for index, task in enumerate(tasks, start=1):
+        task_id = f"task-{index:03d}"
+        task_path = task_dir / f"{task_id}.json"
+        task_data = dict(task)
+        task_data["path"] = _summary_task_path(task, output_dir)
+        task_data.setdefault("schema_version", 1)
+        task_data.setdefault("id", task_id)
+        write_json(task_path, task_data)
+        task_items.append(
+            {
+                "id": task_id,
+                "name": task["name"],
+                "status": task["status"],
+                "path": relative_to(task_path, output_dir),
+            }
+        )
+
+    summary = {
+        "schema_version": 1,
+        "tool": tool,
+        "status": status,
+        "metadata": metadata,
+        "counts": {
+            "tasks": len(tasks),
+            "solved": sum(1 for task in tasks if task.get("solved")),
+            "unsolved": sum(1 for task in tasks if not task.get("solved")),
+            "statuses": len(by_status),
+        },
+        "by_status": {
+            status_name: {
+                "count": len(values),
+                "tasks": [
+                    {
+                        "name": task["name"],
+                        "path": _summary_task_path(task, output_dir),
+                        "plan_length": task.get("plan_length"),
+                    }
+                    for task in values
+                ],
+            }
+            for status_name, values in sorted(by_status.items())
+        },
+        "tasks": task_items,
+        "raw": {
+            "stdout_path": "raw/stdout.txt",
+            "stderr_path": "raw/stderr.txt",
+        },
+    }
+    write_json(output_dir / "summary.json", summary)
+    write_solvability_markdown(output_dir / "summary.md", summary)
+    primary = {
+        "successful": status == "success",
+        "all_solved": status == "success",
+        "solved": [task["name"] for task in tasks if task.get("solved")],
+        "unsolved": [task["name"] for task in tasks if not task.get("solved")],
+        "task_statuses": [(task["name"], task["status"]) for task in tasks],
+    }
+    artifacts = {
+        "summary_json": relative_to(output_dir / "summary.json", output_dir),
+        "summary_md": relative_to(output_dir / "summary.md", output_dir),
+        "raw_stdout": "raw/stdout.txt",
+        "raw_stderr": "raw/stderr.txt",
+        "output_dir": output_dir.as_posix(),
+    }
+    return {
+        "schema_version": summary["schema_version"],
+        "tool": tool,
+        "status": status,
+        "primary": primary,
+        "summary": summary,
+        "artifacts": artifacts,
+        "items": task_items,
+        "tasks": summary["tasks"],
+        "summary_path": artifacts["summary_json"],
+        "summary_md_path": artifacts["summary_md"],
+        "output_dir": output_dir.as_posix(),
+        "counts": summary["counts"],
+        "by_status": summary["by_status"],
+    }
+
+
+def write_solvability_markdown(path: Path, summary: dict[str, Any]) -> None:
+    lines = [
+        f"# {summary['tool']}",
+        "",
+        f"Status: `{summary['status']}`",
+        "",
+        "## Counts",
+        "",
+        f"- Tasks: {summary['counts']['tasks']}",
+        f"- Solved: {summary['counts']['solved']}",
+        f"- Unsolved: {summary['counts']['unsolved']}",
+        "",
+        "## Tasks",
+        "",
+    ]
+    for item in summary["tasks"]:
+        lines.append(f"- `{item['name']}`: `{item['status']}` (`{item['path']}`)")
+    with path.open("x", encoding="utf-8") as fh:
+        fh.write("\n".join(lines).rstrip() + "\n")

pytyr_mcp-0.0.1/src/pytyr_mcp/config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _default_workspace_root() -> Path:
+    return Path(__file__).resolve().parents[3]
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    workspace_root: Path
+    output_root: Path
+    default_timeout_seconds: float = 600.0
+
+
+def load_config() -> ServerConfig:
+    workspace_root = Path(os.environ.get("PYTYR_MCP_WORKSPACE", _default_workspace_root())).resolve()
+    output_root = Path(os.environ.get("PYTYR_MCP_OUTPUT_ROOT", workspace_root / "pytyr-mcp-output")).resolve()
+    return ServerConfig(
+        workspace_root=workspace_root,
+        output_root=output_root,
+        default_timeout_seconds=float(os.environ.get("PYTYR_MCP_TIMEOUT", "600")),
+    )

pytyr_mcp-0.0.1/src/pytyr_mcp/invoke.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import argparse
+import io
+import json
+from contextlib import redirect_stdout
+from pathlib import Path
+from typing import Any, Callable
+
+from pytyr_mcp.planning.sample_generator.results import describe_generator_result, sample_generator_result
+from pytyr_mcp.planning.sample_generator.service import (
+    SampleGeneratorOptions,
+    describe_make_problem,
+    get_generator_path,
+    sample_generator,
+)
+from pytyr_mcp.planning.solvability.schemas import ProveSolvabilityOptions
+from pytyr_mcp.planning.solvability.service import prove_solvability
+from pytyr_mcp.roles import load_role
+
+
+def _sample(args: dict[str, Any]) -> dict[str, Any]:
+    result = sample_generator(
+        SampleGeneratorOptions(
+            domain_name=args["domain_name"],
+            output_dir=Path(args["output_dir"]).resolve(),
+            batch_name=args.get("batch_name", "sample"),
+            configs=args.get("configs", []),
+            allow_invalid=bool(args.get("allow_invalid", False)),
+        )
+    )
+    return sample_generator_result(result)
+
+
+def _describe(args: dict[str, Any]) -> dict[str, Any]:
+    domain_name = args["domain_name"]
+    return describe_generator_result(
+        domain_name=domain_name,
+        generator_path=get_generator_path(domain_name),
+        signature=describe_make_problem(domain_name),
+    )
+
+
+def _solvability(args: dict[str, Any]) -> dict[str, Any]:
+    return prove_solvability(
+        ProveSolvabilityOptions(
+            domain=args["domain"],
+            problem_dir=args["problem_dir"],
+            output_dir=args["output_dir"],
+            num_threads=int(args.get("num_threads", 1)),
+            max_num_states=int(args.get("max_num_states", 100_000)),
+            max_time_seconds=float(args.get("max_time_seconds", args.get("max_time", 5.0))),
+            include_plans=bool(args.get("include_plans", args.get("print_plan", False))),
+        )
+    )
+
+
+TOOLS: dict[str, Callable[[dict[str, Any]], dict[str, Any]]] = {
+    "tyr.planning.describe_generator": _describe,
+    "tyr.planning.sample_generator": _sample,
+    "tyr.planning.prove_solvability": _solvability,
+}
+
+
+def _write_result_json(path: Path, rendered: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("x", encoding="utf-8") as fh:
+        fh.write(rendered)
+
+
+def _ensure_tool_allowed(tool_name: str) -> None:
+    role = load_role()
+    if role.allows(tool_name):
+        return
+    allowed = ", ".join(sorted(role.allowed_tools))
+    raise PermissionError(
+        f"{tool_name} is not allowed for PYTYR_MCP_ROLE={role.name}; "
+        f"allowed tools: {allowed}"
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Invoke a pytyr-mcp tool with JSON arguments.")
+    parser.add_argument("tool", choices=sorted(TOOLS))
+    parser.add_argument("--args-json", required=True)
+    parser.add_argument("--result-json")
+    parsed = parser.parse_args()
+    try:
+        _ensure_tool_allowed(parsed.tool)
+    except (PermissionError, ValueError) as exc:
+        parser.error(str(exc))
+    args = json.loads(parsed.args_json)
+    if not isinstance(args, dict):
+        raise TypeError("--args-json must decode to an object")
+    captured_stdout = io.StringIO()
+    with redirect_stdout(captured_stdout):
+        result = TOOLS[parsed.tool](args)
+    tool_stdout = captured_stdout.getvalue()
+    if tool_stdout:
+        result = {**result, "_tool_stdout": tool_stdout}
+    rendered = json.dumps(result, indent=2, sort_keys=True) + "\n"
+    if parsed.result_json:
+        result_path = Path(parsed.result_json).resolve()
+        _write_result_json(result_path, rendered)
+    else:
+        print(rendered, end="")
+
+
+if __name__ == "__main__":
+    main()

pytyr_mcp-0.0.1/src/pytyr_mcp/paths.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def server_output_dir(output_root: Path, output_dir: str | Path) -> Path:
+    root = output_root.resolve()
+    requested = Path(output_dir)
+    resolved = requested.resolve() if requested.is_absolute() else (root / requested).resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(f"output_dir must resolve under configured output_root: {root}") from exc
+    return resolved
+
+
+def relative_to(path: Path, root: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.as_posix()

pytyr_mcp-0.0.1/src/pytyr_mcp/planning/__init__.py

@@ -0,0 +1 @@
+"""Planning tools."""