moostack-mcp 0.1.0__tar.gz

moostack_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.3
+Name: moostack-mcp
+Version: 0.1.0
+Summary: MCP server for MooStack. Manage your studio conversationally via Claude
+Author: Kaushik LS
+Author-email: Kaushik LS <50703773+thekaushikls@users.noreply.github.com>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: click>=8.5.0
+Requires-Dist: fastmcp>=4.0.5
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: typing-extensions>=4.12.0
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/thekaushikls/moostack-mcp
+Description-Content-Type: text/markdown
+
+# moostack-mcp
+
+An MCP server that lets a MooStack studio owner manage their studio conversationally through Claude Desktop or Claude Code — no dashboard required.
+
+It's a thin client: every tool call is proxied to your studio's MooStack backend over HTTPS.
+
+## Requirements
+
+- Python 3.11+
+- A MooStack account (email + password) that owns or belongs to at least one studio
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```sh
+uv tool install git+https://github.com/thekaushikls/moostack-mcp
+```
+
+Or with pip:
+
+```sh
+pip install git+https://github.com/thekaushikls/moostack-mcp
+```
+
+## Set up
+
+```sh
+moostack-mcp setup
+```
+
+This will:
+1. Ask for your MooStack email, password, and backend URL (press Enter to accept the default).
+2. Validate the credentials against the backend.
+3. Save them to `~/.moostack/config.json` (created with `0600` permissions — readable only by you).
+4. Offer to auto-configure Claude Desktop by adding this server to `claude_desktop_config.json`.
+
+Restart Claude Desktop afterwards and it will pick up the new server.
+
+### Manual Claude Desktop setup
+
+If you skip auto-configure, or you're on an OS it doesn't recognize, add this to your `claude_desktop_config.json` yourself (merge it into the `mcpServers` object if one already exists):
+
+```json
+{
+  "mcpServers": {
+    "moostack": {
+      "command": "moostack-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Config file locations:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+## What you can do with it
+
+**Your account & studios**
+- `list_my_studios` — the studios you own or belong to, and your role in each
+- `get_my_profile` / `update_my_profile` — view or edit your account details
+- `list_members` — your studio's member roster
+
+**Classes & pricing**
+- `list_offerings` — every class you've set up, with its pricing tiers
+- `create_offering` / `update_offering` / `delete_offering` — create a class with pricing in one step, edit it, or remove it
+
+**Sessions & attendance**
+- `list_sessions` — occurrences of a class, past and upcoming
+- `create_session` — add a one-off extra session
+- `view_attendance` — see who's booked into a session
+- `mark_attendance` — mark students present/absent
+
+**Student enrollments**
+- `grant_sessions` — add bonus sessions to a student's enrollment
+- `adjust_enrollment` — manually change a student's session count or expiry
+- `override_attendance` — correct a single attendance record after the fact
+
+**Zoom**
+- `get_zoom_status` / `disconnect_zoom` — check or disconnect your studio's linked Zoom account (connecting Zoom itself is done from the MooStack web app, since it requires a browser OAuth flow)
+
+## Run it manually
+
+```sh
+moostack-mcp serve
+```
+
+Runs the server over stdio — this is what Claude Desktop launches automatically once configured; you shouldn't normally need to run it yourself.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

moostack_mcp-0.1.0/README.md

@@ -0,0 +1,95 @@
+# moostack-mcp
+
+An MCP server that lets a MooStack studio owner manage their studio conversationally through Claude Desktop or Claude Code — no dashboard required.
+
+It's a thin client: every tool call is proxied to your studio's MooStack backend over HTTPS.
+
+## Requirements
+
+- Python 3.11+
+- A MooStack account (email + password) that owns or belongs to at least one studio
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```sh
+uv tool install git+https://github.com/thekaushikls/moostack-mcp
+```
+
+Or with pip:
+
+```sh
+pip install git+https://github.com/thekaushikls/moostack-mcp
+```
+
+## Set up
+
+```sh
+moostack-mcp setup
+```
+
+This will:
+1. Ask for your MooStack email, password, and backend URL (press Enter to accept the default).
+2. Validate the credentials against the backend.
+3. Save them to `~/.moostack/config.json` (created with `0600` permissions — readable only by you).
+4. Offer to auto-configure Claude Desktop by adding this server to `claude_desktop_config.json`.
+
+Restart Claude Desktop afterwards and it will pick up the new server.
+
+### Manual Claude Desktop setup
+
+If you skip auto-configure, or you're on an OS it doesn't recognize, add this to your `claude_desktop_config.json` yourself (merge it into the `mcpServers` object if one already exists):
+
+```json
+{
+  "mcpServers": {
+    "moostack": {
+      "command": "moostack-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Config file locations:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+## What you can do with it
+
+**Your account & studios**
+- `list_my_studios` — the studios you own or belong to, and your role in each
+- `get_my_profile` / `update_my_profile` — view or edit your account details
+- `list_members` — your studio's member roster
+
+**Classes & pricing**
+- `list_offerings` — every class you've set up, with its pricing tiers
+- `create_offering` / `update_offering` / `delete_offering` — create a class with pricing in one step, edit it, or remove it
+
+**Sessions & attendance**
+- `list_sessions` — occurrences of a class, past and upcoming
+- `create_session` — add a one-off extra session
+- `view_attendance` — see who's booked into a session
+- `mark_attendance` — mark students present/absent
+
+**Student enrollments**
+- `grant_sessions` — add bonus sessions to a student's enrollment
+- `adjust_enrollment` — manually change a student's session count or expiry
+- `override_attendance` — correct a single attendance record after the fact
+
+**Zoom**
+- `get_zoom_status` / `disconnect_zoom` — check or disconnect your studio's linked Zoom account (connecting Zoom itself is done from the MooStack web app, since it requires a browser OAuth flow)
+
+## Run it manually
+
+```sh
+moostack-mcp serve
+```
+
+Runs the server over stdio — this is what Claude Desktop launches automatically once configured; you shouldn't normally need to run it yourself.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

moostack_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "moostack-mcp"
+version = "0.1.0"
+description = "MCP server for MooStack. Manage your studio conversationally via Claude"
+readme = "README.md"
+classifiers = ["License :: OSI Approved :: MIT License"]
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.5.0",
+    "fastmcp>=4.0.5",
+    "httpx>=0.28.1",
+    "typing-extensions>=4.12.0",
+]
+
+[project.license]
+text = "MIT"
+
+[[project.authors]]
+name = "Kaushik LS"
+email = "50703773+thekaushikls@users.noreply.github.com"
+
+[project.urls]
+Repository = "https://github.com/thekaushikls/moostack-mcp"
+
+[project.scripts]
+moostack-mcp = "moostack_mcp.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.8",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["src"]

moostack_mcp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,42 @@
+[project]
+name = "moostack-mcp"
+version = "0.1.0"
+description = "MCP server for MooStack. Manage your studio conversationally via Claude"
+
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Kaushik LS", email = "50703773+thekaushikls@users.noreply.github.com" }
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.5.0",
+    "fastmcp>=4.0.5",
+    "httpx>=0.28.1",
+    "typing-extensions>=4.12.0",
+]
+
+[project.urls]
+Repository = "https://github.com/thekaushikls/moostack-mcp"
+
+[project.scripts]
+moostack-mcp = "moostack_mcp.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.8",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["src"]
+

moostack_mcp-0.1.0/src/moostack_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

moostack_mcp-0.1.0/src/moostack_mcp/cli.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import platform
+from pathlib import Path
+from typing import Any
+
+import click
+
+from moostack_mcp.client import MooStackClient, MooStackClientError
+from moostack_mcp.config import DEFAULT_BASE_URL, Config, save_config
+
+MCP_SERVER_NAME = "moostack"
+
+
+@click.group()
+def main() -> None:
+    """MooStack MCP server - manage your studio conversationally via Claude."""
+
+
+@main.command()
+@click.option("--email", prompt="MooStack email")
+@click.option("--password", prompt="MooStack password", hide_input=True)
+@click.option("--base-url", prompt="Backend URL", default=DEFAULT_BASE_URL)
+def setup(email: str, password: str, base_url: str) -> None:
+    """Save your MooStack credentials, after validating them against the backend."""
+    click.echo("Checking your credentials...")
+    try:
+        asyncio.run(_validate_credentials(email, password, base_url))
+    except MooStackClientError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    save_config(email=email, password=password, base_url=base_url)
+    click.echo("Saved.")
+
+    if click.confirm("Auto-configure Claude Desktop?", default=True):
+        _configure_claude_desktop()
+    else:
+        click.echo("Skipped. Run `moostack-mcp serve` to start the MCP server.")
+
+
+async def _validate_credentials(email: str, password: str, base_url: str) -> None:
+    client = MooStackClient(Config(email=email, password=password, base_url=base_url))
+    try:
+        await client.get("/users/me")
+    finally:
+        await client.aclose()
+
+
+def _claude_desktop_config_path() -> Path:
+    system = platform.system()
+    if system == "Darwin":
+        return (
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "Claude"
+            / "claude_desktop_config.json"
+        )
+    if system == "Windows":
+        appdata = os.environ.get("APPDATA", str(Path.home()))
+        return Path(appdata) / "Claude" / "claude_desktop_config.json"
+    return Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+
+
+def _merge_mcp_server_config(existing: dict[str, Any]) -> dict[str, Any]:
+    """Add/overwrite this server's entry under 'mcpServers', preserving everything else."""
+    merged = dict(existing)
+    servers = dict(merged.get("mcpServers", {}))
+    servers[MCP_SERVER_NAME] = {"command": "moostack-mcp", "args": ["serve"]}
+    merged["mcpServers"] = servers
+    return merged
+
+
+def _configure_claude_desktop() -> None:
+    path = _claude_desktop_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict[str, Any] = {}
+    if path.exists():
+        try:
+            existing = json.loads(path.read_text())
+        except json.JSONDecodeError:
+            click.echo(f"Warning: {path} has invalid JSON, replacing it.")
+
+    path.write_text(json.dumps(_merge_mcp_server_config(existing), indent=2))
+    click.echo(f"Updated {path}.")
+    click.echo("Restart Claude Desktop to pick it up.")
+
+
+@main.command()
+def serve() -> None:
+    """Run the MCP server over stdio (used by Claude Desktop / Claude Code)."""
+    from moostack_mcp.server import mcp
+
+    mcp.run(transport="stdio")

moostack_mcp-0.1.0/src/moostack_mcp/client.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from moostack_mcp.config import Config
+
+
+class MooStackClientError(Exception):
+    """Base exception for all MooStack API client errors."""
+
+
+class AuthenticationError(MooStackClientError):
+    """Raised when login/refresh fails and credentials need to be re-entered."""
+
+
+class PermissionDeniedError(MooStackClientError):
+    """Raised on 403 — the authenticated user lacks permission for the action."""
+
+
+class NotFoundError(MooStackClientError):
+    """Raised on 404 — the requested resource doesn't exist."""
+
+
+class ValidationError(MooStackClientError):
+    """Raised on 422 — the request failed backend validation."""
+
+
+class ServerError(MooStackClientError):
+    """Raised on 5xx — the MooStack backend is unavailable."""
+
+
+def _extract_detail(response: httpx.Response, fallback: str) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return fallback
+    detail = body.get("detail") if isinstance(body, dict) else None  # type: ignore
+    if detail is None:
+        return fallback
+    if isinstance(detail, str):
+        return detail
+    if isinstance(detail, list):
+        # FastAPI 422 shape: [{"loc": [...], "msg": "...", "type": "..."}, ...]
+        messages = []
+        for item in detail:
+            loc = ".".join(str(part) for part in item.get("loc", []) if part != "body")
+            msg = item.get("msg", "")
+            messages.append(f"{loc}: {msg}" if loc else msg)
+        return "; ".join(messages) or fallback
+    return fallback
+
+
+class MooStackClient:
+    """Auth-aware async HTTP client for the MooStack API.
+
+    Handles login, access-token attachment, and transparent refresh/retry on 401.
+    One instance is meant to live for the lifetime of the MCP server process, so
+    its underlying httpx.AsyncClient keeps a single cookie jar — that's what lets
+    the refresh_token cookie set by /auth/login/email survive to /auth/refresh.
+    """
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._http = httpx.AsyncClient(base_url=config.base_url, timeout=15.0)
+        self._access_token: str | None = None
+        # Serializes the whole request lifecycle (not just login/refresh) so two
+        # concurrent tool calls never race to refresh/re-login at the same time.
+        # This means API calls run one at a time — fine for a single interactive
+        # session; narrow this to just the token-mutation section if that changes.
+        self._lock = asyncio.Lock()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _login(self) -> None:
+        response = await self._http.post(
+            "/auth/login/email",
+            json={"email": self._config.email, "password": self._config.password},
+        )
+        data = self._parse(response)
+        self._access_token = data["access_token"]
+
+    async def _refresh(self) -> bool:
+        response = await self._http.post("/auth/refresh")
+        if response.status_code != 200:
+            return False
+        self._access_token = response.json()["access_token"]
+        return True
+
+    async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {self._access_token}"
+        return await self._http.request(method, path, headers=headers, **kwargs)
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        async with self._lock:
+            if self._access_token is None:
+                await self._login()
+
+            response = await self._send(method, path, **kwargs)
+
+            if response.status_code == 401:
+                if await self._refresh():
+                    response = await self._send(method, path, **kwargs)
+
+                if response.status_code == 401:
+                    await self._login()
+                    response = await self._send(method, path, **kwargs)
+
+            return self._parse(response)
+
+    def _parse(self, response: httpx.Response) -> Any:
+        if response.status_code == 401:
+            raise AuthenticationError(
+                "Authentication failed. Please run `moostack-mcp setup` to update "
+                "your credentials."
+            )
+        if response.status_code == 403:
+            raise PermissionDeniedError(
+                _extract_detail(
+                    response,
+                    "You don't have permission for this action. You must be the "
+                    "studio owner.",
+                )
+            )
+        if response.status_code == 404:
+            raise NotFoundError(
+                _extract_detail(
+                    response, "Not found. Check the org_slug and try again."
+                )
+            )
+        if response.status_code == 422:
+            raise ValidationError(_extract_detail(response, "Invalid request."))
+        if response.status_code >= 500:
+            raise ServerError(
+                "The MooStack server is temporarily unavailable. Try again shortly."
+            )
+        response.raise_for_status()
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return await self._request("GET", path, params=params)
+
+    async def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        return await self._request("POST", path, json=json)
+
+    async def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        return await self._request("PATCH", path, json=json)
+
+    async def delete(self, path: str) -> Any:
+        return await self._request("DELETE", path)

moostack_mcp-0.1.0/src/moostack_mcp/config.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".moostack"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+DEFAULT_BASE_URL = "https://api.moostack.in"
+
+
+class ConfigNotFound(Exception):
+    """Raised when ~/.moostack/config.json is missing or unreadable."""
+
+
+@dataclass(frozen=True)
+class Config:
+    email: str
+    password: str
+    base_url: str = DEFAULT_BASE_URL
+
+
+def load_config() -> Config:
+    if not CONFIG_PATH.exists():
+        raise ConfigNotFound(
+            f"No config found at {CONFIG_PATH}. Run 'moostack-mcp setup' first."
+        )
+    try:
+        data = json.loads(CONFIG_PATH.read_text())
+        return Config(
+            email=data["email"],
+            password=data["password"],
+            base_url=data.get("base_url", DEFAULT_BASE_URL),
+        )
+    except (json.JSONDecodeError, KeyError) as ex:
+        raise ConfigNotFound(
+            f"Config at {CONFIG_PATH} is invalid ({ex}). Run 'moostack-mcp setup' to fix it"
+        ) from ex
+
+
+def save_config(email: str, password: str, base_url: str = DEFAULT_BASE_URL) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)  # Create folder path if non-existent
+    payload = json.dumps(
+        {"email": email, "password": password, "base_url": base_url},
+        indent=2,  # Human readable
+    )
+    CONFIG_PATH.write_text(payload)
+    os.chmod(CONFIG_PATH, 0o600)