cooperage-sdk 0.1.0__tar.gz

cooperage_sdk-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

cooperage_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: cooperage-sdk
+Version: 0.1.0
+Summary: Lightweight helpers for writing Cooperage-compatible MCP servers
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: uvicorn>=0.27.0

cooperage_sdk-0.1.0/README.md

@@ -0,0 +1,111 @@
+# Cooperage SDK
+
+Lightweight helpers for writing [Cooperage](https://github.com/cooperage-io/cooperage)-compatible MCP servers.
+
+## Install
+
+```bash
+pip install cooperage-sdk
+```
+
+## Usage
+
+```python
+from mcp.server.fastmcp import FastMCP
+from cooperage_sdk import workspace, serve, register_docs
+
+mcp = FastMCP("my-server", json_response=True, stateless_http=True)
+
+@mcp.tool()
+def process_data(input_file: str, output_file: str) -> str:
+    """Process a data file from the workspace and write results."""
+    data = workspace.path(input_file).read_text()
+    workspace.path(output_file).write_text(data.upper())
+    return f"Processed {input_file} → {output_file}"
+
+register_docs(mcp)  # expose docs/ directory as MCP Resources
+serve(mcp)
+```
+
+## API
+
+### workspace
+
+```python
+from cooperage_sdk import workspace
+
+# Get safe paths — blocks traversal, hides the env var
+workspace.path("file.txt")              # returns a Path
+workspace.path("file.txt").read_text()  # read
+workspace.path("out.txt").write_text()  # write
+
+# Works with any library
+Image.open(workspace.path("photo.png"))
+pd.read_csv(workspace.path("data.csv"))
+plt.savefig(workspace.path("chart.png"))
+
+# Helpers
+workspace.exists("file.txt")           # check existence
+workspace.list()                        # list all files
+workspace.list("subdir")               # list files in subdir
+workspace.root                          # raw Path to /workspace
+```
+
+### serve
+
+```python
+from cooperage_sdk import serve
+
+serve(mcp)                              # start on port 8000
+serve(mcp, port=9000)                   # custom port
+```
+
+### register_docs
+
+Expose a `docs/` directory as MCP Resources so the LLM can discover and read
+server documentation on demand.
+
+```python
+from cooperage_sdk import register_docs
+
+register_docs(mcp)              # scans docs/ directory (default)
+register_docs(mcp, "manuals")   # custom directory
+```
+
+Each file in the directory becomes an MCP Resource:
+- **URI**: `docs://<filename>` (e.g. `docs://quickstart.md`)
+- **Name**: derived from filename (e.g. "Quickstart")
+- **Description**: first line of the file — lets the LLM preview contents
+  before reading
+
+#### Example
+
+```
+my-server/
+  server.py
+  Dockerfile
+  docs/
+    quickstart.md          "Getting started with the image analyzer"
+    scene-types.md         "Supported scene types: terrain, urban, coastal"
+    api-reference.md       "Full API reference for all tools"
+```
+
+The LLM sees:
+```
+cooperage_list_server_resources("session-1", "my-server")
+→ [
+    {"uri": "docs://quickstart.md",     "name": "Quickstart",     "description": "Getting started with the image analyzer"},
+    {"uri": "docs://scene-types.md",    "name": "Scene Types",    "description": "Supported scene types: terrain, urban, coastal"},
+    {"uri": "docs://api-reference.md",  "name": "Api Reference",  "description": "Full API reference for all tools"},
+  ]
+
+cooperage_read_server_resource("session-1", "my-server", "docs://scene-types.md")
+→ (full markdown content)
+```
+
+The LLM reads the descriptions, decides which docs are relevant, and only
+pulls what it needs — no wasted context tokens.
+
+## License
+
+MIT

cooperage_sdk-0.1.0/cooperage_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""
+Cooperage SDK — lightweight helpers for writing Cooperage-compatible MCP servers.
+
+Usage:
+    from mcp.server.fastmcp import FastMCP
+    from cooperage_sdk import workspace, serve, register_docs
+
+    mcp = FastMCP("my-server", json_response=True, stateless_http=True)
+
+    @mcp.tool()
+    def my_tool(input_file: str) -> str:
+        data = workspace.path(input_file).read_text()
+        workspace.path("output.txt").write_text(data.upper())
+        return "Done"
+
+    register_docs(mcp)
+    serve(mcp)
+"""
+
+from cooperage_sdk.workspace import workspace
+from cooperage_sdk.server import serve
+from cooperage_sdk.docs import register_docs
+
+__all__ = ["workspace", "serve", "register_docs"]

cooperage_sdk-0.1.0/cooperage_sdk/docs.py

@@ -0,0 +1,56 @@
+"""Helpers for exposing server documentation as MCP Resources."""
+
+from pathlib import Path
+
+
+def register_docs(mcp, docs_dir: str = "docs") -> None:
+    """Register all markdown files in a directory as MCP Resources.
+
+    Each file becomes a resource with:
+    - URI: docs://<filename>
+    - Name: derived from filename (e.g. "scene-types.md" → "Scene Types")
+    - Description: first non-empty line of the file
+
+    Usage:
+        from cooperage_sdk import register_docs
+
+        mcp = FastMCP("my-server", json_response=True, stateless_http=True)
+        register_docs(mcp)
+
+    Args:
+        mcp: A FastMCP instance.
+        docs_dir: Path to the docs directory (default: "docs").
+    """
+    docs_path = Path(docs_dir)
+    if not docs_path.is_dir():
+        return
+
+    for filepath in sorted(docs_path.rglob("*")):
+        if not filepath.is_file():
+            continue
+
+        relative = str(filepath.relative_to(docs_path))
+        uri = f"docs://{relative}"
+        content = filepath.read_text()
+
+        # Derive a human-readable name from the filename
+        name = filepath.stem.replace("-", " ").replace("_", " ").title()
+
+        # Use first non-empty line as description
+        description = ""
+        for line in content.splitlines():
+            stripped = line.strip().lstrip("#").strip()
+            if stripped:
+                description = stripped[:200]
+                break
+
+        # Register as a resource — capture content in closure
+        _register_one(mcp, uri, name, description, content)
+
+
+def _register_one(mcp, uri: str, name: str, description: str, content: str) -> None:
+    """Register a single doc resource. Separate function to capture closure correctly."""
+
+    @mcp.resource(uri, name=name, description=description)
+    def _read() -> str:
+        return content

cooperage_sdk-0.1.0/cooperage_sdk/server.py

@@ -0,0 +1,19 @@
+"""Server helpers for Cooperage MCP servers."""
+
+import os
+
+
+def serve(mcp, host: str = "0.0.0.0", port: int | None = None) -> None:
+    """Start the MCP server. Replaces the uvicorn boilerplate.
+
+    Args:
+        mcp: A FastMCP instance.
+        host: Bind address (default: 0.0.0.0).
+        port: Port to listen on (default: PORT env var or 8000).
+    """
+    import uvicorn
+
+    if port is None:
+        port = int(os.environ.get("PORT", "8000"))
+
+    uvicorn.run(mcp.streamable_http_app(), host=host, port=port)

cooperage_sdk-0.1.0/cooperage_sdk/workspace.py

@@ -0,0 +1,55 @@
+"""Workspace helpers for Cooperage MCP servers."""
+
+import os
+from pathlib import Path
+
+
+class Workspace:
+    """Interface for the shared /workspace volume.
+
+    Handles path resolution, traversal protection, and the
+    COOPERAGE_WORKSPACE env var so server devs don't have to.
+    """
+
+    def __init__(self):
+        self._root = Path(os.environ.get("COOPERAGE_WORKSPACE", "/workspace"))
+
+    @property
+    def root(self) -> Path:
+        """The workspace root as a Path."""
+        return self._root
+
+    def path(self, path: str) -> Path:
+        """Resolve a relative path within the workspace.
+
+        Returns a full Path you can use with any library:
+
+            data = workspace.path("input.csv").read_text()
+            image = Image.open(workspace.path("photo.png"))
+            df = pd.read_csv(workspace.path("data.csv"))
+            plt.savefig(workspace.path("chart.png"))
+
+        Raises ValueError on path traversal attempts.
+        """
+        full = (self._root / path).resolve()
+        if not str(full).startswith(str(self._root.resolve())):
+            raise ValueError(f"Path {path!r} escapes the workspace")
+        return full
+
+    def exists(self, path: str) -> bool:
+        """Check if a file exists in the workspace."""
+        return self.path(path).exists()
+
+    def list(self, subdir: str = "") -> list[str]:
+        """List files in the workspace (or a subdirectory), relative to root."""
+        target = self.path(subdir) if subdir else self._root
+        if not target.exists():
+            return []
+        return sorted(
+            str(p.relative_to(self._root))
+            for p in target.rglob("*")
+            if p.is_file()
+        )
+
+
+workspace = Workspace()

cooperage_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cooperage-sdk"
+version = "0.1.0"
+description = "Lightweight helpers for writing Cooperage-compatible MCP servers"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "uvicorn>=0.27.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cooperage_sdk"]