scrumdo-mcp 0.1.0__py3-none-any.whl

scrumdo_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: scrumdo-mcp
+Version: 0.1.0
+Summary: MCP server for ScrumDo boards — connect any AI tool directly to your board
+Project-URL: Homepage, https://www.scrumdo.com
+Project-URL: Documentation, https://github.com/ScrumDoLLC/scrumdo-mcp#readme
+Project-URL: Repository, https://github.com/ScrumDoLLC/scrumdo-mcp
+Project-URL: Bug Tracker, https://github.com/ScrumDoLLC/scrumdo-mcp/issues
+Author-email: ScrumDo LLC <support@scrumdo.com>
+License: MIT
+License-File: LICENSE
+Keywords: agile,ai,claude,cursor,kanban,llm,mcp,model-context-protocol,scrum,scrumdo,windsurf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.3.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scrumdo-mcp
+
+Connect any MCP-compatible AI tool (Claude Code, Cursor, Windsurf, and others) directly to your [ScrumDo](https://www.scrumdo.com) boards.
+
+Once installed, your AI assistant can read cards, move them, create tasks, post comments, and search across your board — without you copy-pasting anything.
+
+---
+
+## Installation
+
+```bash
+pip install scrumdo-mcp
+```
+
+> **Pre-release / before PyPI publish:** install directly from GitHub:
+> ```bash
+> pip install git+https://github.com/ScrumDoLLC/scrumdo-mcp.git
+> ```
+
+---
+
+## Cursor quick-start
+
+**1 — Install**
+```bash
+# To run the server only:
+pip install git+https://github.com/ScrumDoLLC/scrumdo-mcp.git
+
+# To run tests too:
+git clone https://github.com/ScrumDoLLC/scrumdo-mcp.git
+cd scrumdo-mcp
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+**2 — Get your token**
+
+Log in to ScrumDo → your org → **Settings → API Tokens → Create Token**. Copy it — shown once only.
+
+**3 — Add to `~/.cursor/mcp.json`**
+
+```json
+{
+  "mcpServers": {
+    "scrumdo": {
+      "command": "scrumdo-mcp",
+      "env": {
+        "SCRUMDO_TOKEN": "your-token-here",
+        "SCRUMDO_ORG": "your-org-slug",
+        "SCRUMDO_PROJECT": "your-default-project-slug"
+      }
+    }
+  }
+}
+```
+
+Your org and project slugs are the short names in your board URL:
+`app.scrumdo.com/`**`my-company`**`/`**`engineering`**
+
+**4 — Restart Cursor**
+
+Done. In any Cursor chat you can now ask:
+- *"What cards are in the current sprint?"*
+- *"Move ENG-42 to In Review"*
+- *"Add a comment to ENG-42: PR is up for review"*
+- *"List all cards assigned to me"*
+
+---
+
+## Setup
+
+### Step 1 — Get your token
+
+Log in to ScrumDo → your organization → **Settings → API Tokens → Create Token**.
+
+Copy the token — it is only shown once. This is your personal key; keep it private.
+
+### Step 2 — Configure your AI tool
+
+Find your tool's MCP config file and add the `scrumdo` server entry:
+
+| Tool | Config file |
+|------|-------------|
+| Claude Code | `~/.claude/claude.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+```json
+{
+  "mcpServers": {
+    "scrumdo": {
+      "command": "scrumdo-mcp",
+      "env": {
+        "SCRUMDO_TOKEN": "your-token-here",
+        "SCRUMDO_ORG": "your-org-slug",
+        "SCRUMDO_PROJECT": "your-default-project-slug"
+      }
+    }
+  }
+}
+```
+
+Your org slug and project slug are the short names in your board URL:
+`app.scrumdo.com/`**`my-company`**`/`**`engineering`**
+
+### Step 3 — Restart your AI tool
+
+Done. Your AI assistant now has direct access to your board.
+
+---
+
+## What you can do
+
+Once connected, just talk to your AI tool naturally:
+
+```
+"What's the status of ENG-42?"
+"Move ENG-42 to In Review and add a comment saying the PR is up"
+"List all cards assigned to me in the current sprint"
+"Create a sub-task on ENG-42: write release notes"
+"Search for cards about the login bug"
+"What did the team work on this week?"
+```
+
+---
+
+## Available tools (41 total)
+
+| Group | Tools |
+|-------|-------|
+| **Boards** | `list_boards`, `get_board`, `get_board_cells`, `list_iterations`, `list_labels`, `list_epics` |
+| **Cards** | `list_cards`, `get_card`, `find_card`, `create_card`, `update_card`, `move_card`, `set_card_field`, `archive_card`, `assign_card`, `add_card_label`, `remove_card_label` |
+| **Tasks** | `list_tasks`, `create_task`, `complete_task`, `reopen_task`, `update_task`, `delete_task` |
+| **Comments** | `list_comments`, `add_comment`, `delete_comment` |
+| **Fields** | `list_custom_fields`, `get_card_field`, `get_all_card_fields` |
+| **Members** | `list_members`, `find_member` |
+| **Search** | `search_cards`, `search_by_field_value` |
+| **Activity** | `log_activity`, `get_activity_log`, `get_workspace_activity` |
+| **Webhooks** | `list_webhooks`, `create_webhook`, `delete_webhook` |
+| **Time** | `list_time_entries`, `log_time` |
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SCRUMDO_TOKEN` | — | **Required.** API token from Settings → API Tokens |
+| `SCRUMDO_BASE_URL` | `https://app.spryng.io` | API base URL |
+| `SCRUMDO_ORG` | — | Your organization slug |
+| `SCRUMDO_PROJECT` | — | Default project slug |
+
+---
+
+## Token scope
+
+Your API token is restricted to your organization's board data only — cards, tasks, comments, members, iterations. It cannot access billing, account settings, or any other organization's data. Revoke it at any time from Settings → API Tokens.
+
+---
+
+## What is MCP?
+
+[Model Context Protocol](https://modelcontextprotocol.io) is an open standard for connecting AI tools to external services. Claude Code, Cursor, Windsurf, and other AI editors support it natively. Install the server once; any MCP-compatible tool can use it.
+
+---
+
+## License
+
+MIT

scrumdo_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+spryng_mcp/__init__.py,sha256=-WB8mkIUoSP6l6Q9IejOIcR4HZWXf7Dz0fk66RrwD1E,61
+spryng_mcp/client.py,sha256=LbT1TjLnEegVxLwKGlZKmNcmqL97jDgHMuJL6URgf-M,13284
+spryng_mcp/config.py,sha256=oIZSRrTNHv7MA0-zX3EtDQYe5rRLM_blU41mEUwbUSU,1691
+spryng_mcp/server.py,sha256=ByRilHOe6lcncLHRzKmnvd-m3hXOj3GbQs1eSalCHpU,3244
+spryng_mcp/tools/__init__.py,sha256=udfeBNbdGQGGVNTvl4v1NM4fNX9LvCfIuaKWzWN6BvA,67
+spryng_mcp/tools/activity.py,sha256=LS2PzhDUl2Vujg24VfopkGOeNPnihqX6rlKKKVgJhs0,8633
+spryng_mcp/tools/boards.py,sha256=N1uEf2ObCJ-tRIayRPP4EjYQ4MXu_wmA27hfT6C9stc,2636
+spryng_mcp/tools/cards.py,sha256=bl2ipsrncOBGUVG9g9a6mFVaCo5_wugY_PfH20jMZzs,9208
+spryng_mcp/tools/comments.py,sha256=usJMCcMY2OJiBwE7DQsxlUrDA0LgW_hFnDjVPTp2Gf4,1643
+spryng_mcp/tools/fields.py,sha256=GRrfNt1Dj4SyzYf781KjPfuRQH-bIiUBVTzSNlBxci4,1782
+spryng_mcp/tools/members.py,sha256=p5NsgrG_8NCKBYpeWwrOwcnDPqTVZ_F5VkrIobDyiiw,1341
+spryng_mcp/tools/search.py,sha256=5IQnMKEzl-Nskju0D91c9rT9b73zJWBBBJqPsq4oLBo,1601
+spryng_mcp/tools/tasks.py,sha256=rLW-O2AoLnMe-EjhcBY2SOK17cVuobdmCxTtkq805yA,3417
+spryng_mcp/tools/time_tracking.py,sha256=6gmK5OM5ugFjp9RvRHrkczkVQrZJs9lx44oq9qUBaK8,1482
+spryng_mcp/tools/webhooks.py,sha256=Q7V6vZT4joOOmGDmLbr9XEjkttBn3sTU8h-7nAX37LI,1629
+scrumdo_mcp-0.1.0.dist-info/METADATA,sha256=_mTZnpt4dlws6NFtRGPAHA0F-lxCMWTZJAUO1Tb99U8,6140
+scrumdo_mcp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+scrumdo_mcp-0.1.0.dist-info/entry_points.txt,sha256=DAX9wAWRMooYhwt1uPCmmUvwgUFi7QK5Z-0sB0faXPI,55
+scrumdo_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=GJflU7PUHt4423mGA-LqqAXsXZ-yiASRE0LqVreeKiM,1068
+scrumdo_mcp-0.1.0.dist-info/RECORD,,

scrumdo_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

scrumdo_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scrumdo-mcp = spryng_mcp.server:main

scrumdo_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScrumDo LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spryng_mcp/__init__.py

@@ -0,0 +1 @@
+"""spryng_mcp — MCP server for ScrumDo / Spryng boards."""

spryng_mcp/client.py

@@ -0,0 +1,272 @@
+"""Async HTTP client for the ScrumDo / Spryng REST API."""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import Config
+
+
+class SpryngClient:
+    """
+    Thin async wrapper around the ScrumDo API.
+
+    All methods raise httpx.HTTPStatusError on 4xx/5xx responses.
+    The caller (tool layer) is responsible for presenting errors to the LLM.
+    """
+
+    def __init__(self) -> None:
+        self._http = httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {Config.token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            timeout=30.0,
+        )
+        # Cache: human-readable card ref (e.g. "ON-914") → numeric story id
+        self._card_id_cache: dict[str, int] = {}
+
+    async def __aenter__(self) -> "SpryngClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self._http.aclose()
+
+    # ── Card-ref resolution ───────────────────────────────────────────────────
+
+    async def _resolve_card_id(self, card_ref: str) -> int:
+        """
+        Convert a human-readable card reference like 'ON-914' into the
+        numeric database story id required by the /stories/{id}/ endpoints.
+
+        The API does not expose a reference-based lookup; we resolve by
+        scanning the paginated story list and matching on the ``number``
+        field (which equals the local_id / project-scoped sequence number).
+
+        Results are cached on the client instance so each ref is resolved
+        only once per session.
+        """
+        # Fast path: caller already has a numeric id
+        if isinstance(card_ref, int) or (
+            isinstance(card_ref, str) and card_ref.lstrip("-").isdigit()
+        ):
+            return int(card_ref)
+
+        # Cache hit
+        if card_ref in self._card_id_cache:
+            return self._card_id_cache[card_ref]
+
+        # Parse the number portion from e.g. "ON-914" → 914
+        parts = card_ref.rsplit("-", 1)
+        if len(parts) != 2 or not parts[1].isdigit():
+            raise ValueError(
+                f"Cannot parse card reference {card_ref!r}. "
+                "Expected format: PREFIX-NUMBER (e.g. 'ON-914')."
+            )
+        target_number = int(parts[1])
+
+        # Scan story list pages (100 items/page, max ~10 pages for most boards)
+        page = 1
+        while True:
+            data = await self.get(
+                Config.project_url("stories/"), page=page, page_size=100
+            )
+            items = data.get("items", []) if isinstance(data, dict) else data
+            for story in items:
+                if story.get("number") == target_number:
+                    story_id: int = story["id"]
+                    self._card_id_cache[card_ref] = story_id
+                    return story_id
+            # Stop when there are no more pages
+            has_next = isinstance(data, dict) and bool(data.get("next"))
+            if not has_next or not items:
+                break
+            page += 1
+
+        raise ValueError(
+            f"Card {card_ref!r} (number={target_number}) not found in "
+            f"project {Config.project!r}."
+        )
+
+    # ── Generic helpers ───────────────────────────────────────────────────────
+
+    async def get(self, url: str, **params: Any) -> Any:
+        r = await self._http.get(url, params=params or None)
+        r.raise_for_status()
+        return r.json()
+
+    async def post(self, url: str, body: dict[str, Any]) -> Any:
+        r = await self._http.post(url, json=body)
+        r.raise_for_status()
+        return r.json()
+
+    async def patch(self, url: str, body: dict[str, Any]) -> Any:
+        r = await self._http.patch(url, json=body)
+        r.raise_for_status()
+        return r.json()
+
+    async def put(self, url: str, body: dict[str, Any]) -> Any:
+        r = await self._http.put(url, json=body)
+        r.raise_for_status()
+        return r.json()
+
+    async def delete(self, url: str) -> int:
+        r = await self._http.delete(url)
+        r.raise_for_status()
+        return r.status_code
+
+    # ── Boards / Projects ──────────────────────────────────────────────────────
+
+    async def list_boards(self) -> list[dict]:
+        data = await self.get(Config.org_url("projects/"))
+        return data if isinstance(data, list) else data.get("projects", data)
+
+    async def get_board(self, project_slug: str | None = None) -> dict:
+        slug = project_slug or Config.project
+        return await self.get(Config.org_url(f"projects/{slug}/"))
+
+    async def get_board_cells(self, project_slug: str | None = None) -> list[dict]:
+        slug = project_slug or Config.project
+        data = await self.get(Config.project_url("boardcell/") if not project_slug
+                              else Config.api(f"organizations/{Config.org}/projects/{slug}/boardcell/"))
+        return data if isinstance(data, list) else data.get("cells", data)
+
+    # ── Cards / Stories ────────────────────────────────────────────────────────
+
+    async def list_cards(self, **filters: Any) -> dict:
+        return await self.get(Config.project_url("stories/"), **filters)
+
+    async def get_card(self, card_ref: str) -> dict:
+        """card_ref is the full reference like 'ON-914'."""
+        story_id = await self._resolve_card_id(card_ref)
+        return await self.get(Config.project_url(f"stories/{story_id}/"))
+
+    async def create_card(self, body: dict[str, Any]) -> dict:
+        return await self.post(Config.project_url("stories/"), body)
+
+    async def update_card(self, card_ref: str, body: dict[str, Any]) -> dict:
+        story_id = await self._resolve_card_id(card_ref)
+        return await self.patch(Config.project_url(f"stories/{story_id}/"), body)
+
+    async def delete_card(self, card_ref: str) -> int:
+        story_id = await self._resolve_card_id(card_ref)
+        return await self.delete(Config.project_url(f"stories/{story_id}/"))
+
+    # ── Tasks ──────────────────────────────────────────────────────────────────
+
+    async def list_tasks(self, card_ref: str) -> list[dict]:
+        story_id = await self._resolve_card_id(card_ref)
+        data = await self.get(Config.project_url(f"stories/{story_id}/tasks/"))
+        return data if isinstance(data, list) else data.get("tasks", data)
+
+    async def create_task(self, card_ref: str, body: dict[str, Any]) -> dict:
+        story_id = await self._resolve_card_id(card_ref)
+        return await self.post(Config.project_url(f"stories/{story_id}/tasks/"), body)
+
+    async def update_task(self, card_ref: str, task_id: int, body: dict[str, Any]) -> dict:
+        story_id = await self._resolve_card_id(card_ref)
+        return await self.patch(Config.project_url(f"stories/{story_id}/tasks/{task_id}/"), body)
+
+    async def delete_task(self, card_ref: str, task_id: int) -> int:
+        story_id = await self._resolve_card_id(card_ref)
+        return await self.delete(Config.project_url(f"stories/{story_id}/tasks/{task_id}/"))
+
+    # ── Comments ───────────────────────────────────────────────────────────────
+
+    async def list_comments(self, card_id: int) -> list[dict]:
+        data = await self.get(Config.api("comments/story/"), story=card_id)
+        return data if isinstance(data, list) else data.get("comments", data)
+
+    async def add_comment(self, card_id: int, body: str) -> dict:
+        return await self.post(Config.api("comments/story/"), {"story": card_id, "comment": body})
+
+    async def delete_comment(self, comment_id: int) -> int:
+        return await self.delete(Config.api(f"comments/story/{comment_id}/"))
+
+    # ── Custom fields ──────────────────────────────────────────────────────────
+
+    async def list_custom_fields(self, project_slug: str | None = None) -> list[dict]:
+        slug = project_slug or Config.project
+        data = await self.get(
+            Config.api(f"organizations/{Config.org}/projects/{slug}/customfields/")
+        )
+        return data if isinstance(data, list) else data.get("customfields", data)
+
+    async def set_custom_field(self, card_ref: str, field_id: int, value: str) -> dict:
+        """
+        Sets a single custom field on a card.
+        Fetches the card first to preserve existing extra_fields.
+        """
+        story_id = await self._resolve_card_id(card_ref)
+        card = await self.get(Config.project_url(f"stories/{story_id}/"))
+        extra = card.get("extra_fields") or {}
+        extra[str(field_id)] = value
+        return await self.patch(
+            Config.project_url(f"stories/{story_id}/"),
+            {"extra_fields": extra},
+        )
+
+    # ── Members ────────────────────────────────────────────────────────────────
+
+    async def list_members(self, project_slug: str | None = None) -> list[dict]:
+        slug = project_slug or Config.project
+        data = await self.get(
+            Config.api(f"organizations/{Config.org}/projects/{slug}/members/")
+        )
+        return data if isinstance(data, list) else data.get("members", data)
+
+    # ── Iterations ─────────────────────────────────────────────────────────────
+
+    async def list_iterations(self) -> list[dict]:
+        data = await self.get(Config.project_url("iterations/"))
+        return data if isinstance(data, list) else data.get("iterations", data)
+
+    # ── Epics ──────────────────────────────────────────────────────────────────
+
+    async def list_epics(self) -> list[dict]:
+        data = await self.get(Config.project_url("epics/"))
+        return data if isinstance(data, list) else data.get("epics", data)
+
+    # ── Labels ─────────────────────────────────────────────────────────────────
+
+    async def list_labels(self) -> list[dict]:
+        data = await self.get(Config.project_url("labels/"))
+        return data if isinstance(data, list) else data.get("labels", data)
+
+    # ── Webhooks ───────────────────────────────────────────────────────────────
+
+    async def list_webhooks(self) -> list[dict]:
+        data = await self.get(Config.project_url("webhooks/"))
+        return data if isinstance(data, list) else data.get("webhooks", data)
+
+    async def create_webhook(self, body: dict[str, Any]) -> dict:
+        return await self.post(Config.project_url("webhooks/"), body)
+
+    async def delete_webhook(self, webhook_id: int) -> int:
+        return await self.delete(Config.project_url(f"webhooks/{webhook_id}/"))
+
+    # ── Search ─────────────────────────────────────────────────────────────────
+
+    async def search(self, query: str) -> list[dict]:
+        data = await self.get(Config.org_url("search/"), q=query)
+        if isinstance(data, list):
+            return data
+        # org search endpoint returns paginated {"items": [...], "count": N, ...}
+        return data.get("items", data.get("results", []))
+
+    # ── Time entries ───────────────────────────────────────────────────────────
+
+    async def list_time_entries(self, card_ref: str | None = None) -> list[dict]:
+        if card_ref:
+            story_id = await self._resolve_card_id(card_ref)
+            url = Config.project_url(f"stories/{story_id}/time_entries/")
+        else:
+            url = Config.project_url("time_entries/")
+        data = await self.get(url)
+        return data if isinstance(data, list) else data.get("time_entries", data)
+
+    async def log_time(self, card_ref: str, body: dict[str, Any]) -> dict:
+        story_id = await self._resolve_card_id(card_ref)
+        return await self.post(Config.project_url(f"stories/{story_id}/time_entries/"), body)

spryng_mcp/config.py

@@ -0,0 +1,53 @@
+"""Configuration — loaded from environment variables or .env file."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Load .env from the mcp/ directory if present
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+
+def _env(*keys: str, default: str = "") -> str:
+    """Return the first non-empty value from the given env var names."""
+    for key in keys:
+        val = os.getenv(key, "")
+        if val:
+            return val
+    return default
+
+
+class Config:
+    """Runtime configuration for the ScrumDo MCP server.
+
+    Accepts both SCRUMDO_* (preferred) and legacy SPRYNG_* env var names.
+    """
+
+    base_url: str = _env("SCRUMDO_BASE_URL", "SPRYNG_BASE_URL",
+                          default="https://app.spryng.io").rstrip("/")
+    token: str = _env("SCRUMDO_TOKEN", "SPRYNG_TOKEN")
+    org: str = _env("SCRUMDO_ORG", "SPRYNG_ORG", default="")
+    project: str = _env("SCRUMDO_PROJECT", "SPRYNG_PROJECT", default="")
+
+    @classmethod
+    def validate(cls) -> None:
+        if not cls.token:
+            raise RuntimeError(
+                "SCRUMDO_TOKEN is not set. "
+                "Set it in your MCP config env block or in a .env file."
+            )
+
+    @classmethod
+    def api(cls, path: str) -> str:
+        """Build a full API URL. path is relative to /api/scrumdo/."""
+        return f"{cls.base_url}/api/scrumdo/{path.lstrip('/')}"
+
+    @classmethod
+    def org_url(cls, path: str = "") -> str:
+        return cls.api(f"organizations/{cls.org}/{path.lstrip('/')}")
+
+    @classmethod
+    def project_url(cls, path: str = "") -> str:
+        return cls.org_url(f"projects/{cls.project}/{path.lstrip('/')}")

spryng_mcp/server.py

@@ -0,0 +1,98 @@
+"""
+spryng_mcp.server — FastMCP server entrypoint.
+
+Registers all tools and starts the MCP server over stdio.
+
+Usage:
+    # Run directly
+    python -m spryng_mcp.server
+
+    # Or via the installed CLI
+    spryng-mcp
+
+    # Add to Claude Code
+    claude mcp add spryng -- python -m spryng_mcp.server
+
+Environment variables (set in mcp/.env or export before running):
+    SPRYNG_TOKEN      Bearer token for the ScrumDo / Spryng API (required)
+    SPRYNG_BASE_URL   API base URL (default: https://app.spryng.io)
+    SPRYNG_ORG        Organisation slug (default: spryng-internal)
+    SPRYNG_PROJECT    Default project slug (default: onboarding)
+"""
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from .config import Config
+from .tools import (
+    activity,
+    boards,
+    cards,
+    comments,
+    fields,
+    members,
+    search,
+    tasks,
+    time_tracking,
+    webhooks,
+)
+
+# ── Server definition ──────────────────────────────────────────────────────────
+
+mcp = FastMCP(
+    name="spryng",
+    instructions=f"""
+You are connected to a ScrumDo / Spryng board.
+
+Default context:
+  Organisation: {Config.org}
+  Project:      {Config.project}
+  Base URL:     {Config.base_url}
+
+This MCP server gives you full Monday.com-level access to the board:
+  • Read and write cards (stories) with all custom fields
+  • Move cards between columns, assign members, manage labels
+  • Create, complete, and delete tasks (checklist items)
+  • Post and read comments
+  • Write and query structured activity log entries (log_activity / get_activity_log)
+  • Search cards by text or custom field value
+  • Manage webhooks, time tracking, custom fields, members, labels, and iterations
+
+Key conventions for this project:
+  - Card references are in the format ON-<number>, e.g. ON-914
+  - Custom field IDs: 5303=Feature Identity, 5304=Promotion Status,
+    5306=Branch Path, 5307=Human Review, 5422=Intended Promotion Path,
+    5425=Test Contract, 5426=Outcome, 5428=Run Evidence, 5430=Feature Statement,
+    5432=In Scope, 5433=Commit Links, 5436=Behavior Contract,
+    5437=Out of Scope, 5439=Repos Attached
+  - Board cells (columns): 18531=Analyze, 20132=Being Developed,
+    20133=Ready for Stage Pull, 16246=Integrated
+
+Use log_activity() to record agent actions against cards so the workspace
+activity log stays current and filterable.
+""".strip(),
+)
+
+# ── Register all tool groups ───────────────────────────────────────────────────
+
+boards.register(mcp)
+cards.register(mcp)
+tasks.register(mcp)
+comments.register(mcp)
+fields.register(mcp)
+members.register(mcp)
+search.register(mcp)
+activity.register(mcp)
+webhooks.register(mcp)
+time_tracking.register(mcp)
+
+
+# ── Entrypoint ─────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    Config.validate()
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

spryng_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool modules — each registers tools on the FastMCP server."""