kobo-mcp 0.1.0__py3-none-any.whl

kobo_mcp/__init__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+__all__ = ["main"]

kobo_mcp/server.py

@@ -0,0 +1,366 @@
+"""KoboToolbox MCP Server - Deploy surveys and fetch submissions."""
+
+import json
+import os
+import sys
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+# Server instance
+mcp = FastMCP("kobotoolbox")
+
+# Configuration from environment
+KOBO_API_TOKEN = os.environ.get("KOBO_API_TOKEN", "")
+KOBO_SERVER = os.environ.get("KOBO_SERVER", "https://kf.kobotoolbox.org")
+
+
+def get_headers() -> dict[str, str]:
+    """Get authorization headers for API requests."""
+    if not KOBO_API_TOKEN:
+        raise ValueError("KOBO_API_TOKEN environment variable is not set")
+    return {"Authorization": f"Token {KOBO_API_TOKEN}"}
+
+
+def format_asset(asset: dict[str, Any]) -> dict[str, Any]:
+    """Format an asset object for display."""
+    return {
+        "uid": asset.get("uid"),
+        "name": asset.get("name"),
+        "asset_type": asset.get("asset_type"),
+        "deployment_status": asset.get("deployment_status"),
+        "submission_count": asset.get("deployment__submission_count", 0),
+        "date_created": asset.get("date_created"),
+        "date_modified": asset.get("date_modified"),
+        "owner": asset.get("owner__username"),
+    }
+
+
+@mcp.tool()
+async def list_forms(search: str | None = None) -> str:
+    """List all KoboToolbox forms/surveys.
+
+    Args:
+        search: Optional search term to filter forms by name.
+
+    Returns:
+        JSON list of forms with uid, name, status, and submission count.
+    """
+    params: dict[str, Any] = {"asset_type": "survey"}
+    if search:
+        params["q"] = search
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{KOBO_SERVER}/api/v2/assets/",
+            headers=get_headers(),
+            params=params,
+            timeout=30.0,
+        )
+        response.raise_for_status()
+        data = response.json()
+
+    results = data.get("results", [])
+    forms = [format_asset(asset) for asset in results]
+    return json.dumps(forms, indent=2)
+
+
+@mcp.tool()
+async def get_form(form_uid: str) -> str:
+    """Get detailed information about a specific form.
+
+    Args:
+        form_uid: The unique identifier (uid) of the form.
+
+    Returns:
+        JSON object with form details including questions/fields.
+    """
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{KOBO_SERVER}/api/v2/assets/{form_uid}/",
+            headers=get_headers(),
+            timeout=30.0,
+        )
+        response.raise_for_status()
+        data = response.json()
+
+    # Extract key information
+    result = {
+        "uid": data.get("uid"),
+        "name": data.get("name"),
+        "deployment_status": data.get("deployment_status"),
+        "submission_count": data.get("deployment__submission_count", 0),
+        "date_created": data.get("date_created"),
+        "date_modified": data.get("date_modified"),
+        "owner": data.get("owner__username"),
+        "content": data.get("content"),  # Contains survey structure
+    }
+    return json.dumps(result, indent=2)
+
+
+@mcp.tool()
+async def get_submissions(
+    form_uid: str,
+    limit: int = 100,
+    start: int = 0,
+    query: str | None = None,
+) -> str:
+    """Get submissions (responses) for a form.
+
+    Args:
+        form_uid: The unique identifier (uid) of the form.
+        limit: Maximum number of submissions to return (default 100).
+        start: Offset for pagination (default 0).
+        query: Optional JSON query string to filter submissions (e.g., '{"field": "value"}').
+
+    Returns:
+        JSON object with count and list of submissions.
+    """
+    params: dict[str, Any] = {"limit": limit, "start": start}
+    if query:
+        params["query"] = query
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{KOBO_SERVER}/api/v2/assets/{form_uid}/data/",
+            headers=get_headers(),
+            params=params,
+            timeout=60.0,
+        )
+        response.raise_for_status()
+        data = response.json()
+
+    return json.dumps(
+        {"count": data.get("count", 0), "results": data.get("results", [])},
+        indent=2,
+    )
+
+
+@mcp.tool()
+async def deploy_form(file_path: str, form_name: str | None = None) -> str:
+    """Upload and deploy an XLSForm to KoboToolbox.
+
+    Args:
+        file_path: Path to the XLSForm (.xlsx) file.
+        form_name: Optional name for the form (defaults to filename).
+
+    Returns:
+        JSON object with the created form's uid and deployment status.
+    """
+    import os.path
+
+    if not os.path.exists(file_path):
+        return json.dumps({"error": f"File not found: {file_path}"})
+
+    name = form_name or os.path.splitext(os.path.basename(file_path))[0]
+
+    async with httpx.AsyncClient() as client:
+        # Step 1: Upload the XLSForm to create an asset
+        with open(file_path, "rb") as f:
+            files = {"file": (os.path.basename(file_path), f, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")}
+            data = {"name": name}
+            response = await client.post(
+                f"{KOBO_SERVER}/api/v2/assets/",
+                headers=get_headers(),
+                files=files,
+                data=data,
+                timeout=60.0,
+            )
+            response.raise_for_status()
+            asset = response.json()
+
+        uid = asset.get("uid")
+
+        # Step 2: Deploy the form
+        deploy_response = await client.post(
+            f"{KOBO_SERVER}/api/v2/assets/{uid}/deployment/",
+            headers=get_headers(),
+            json={"active": True},
+            timeout=30.0,
+        )
+        deploy_response.raise_for_status()
+
+    return json.dumps(
+        {
+            "uid": uid,
+            "name": name,
+            "status": "deployed",
+            "url": f"{KOBO_SERVER}/#/forms/{uid}",
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+async def replace_form(form_uid: str, file_path: str) -> str:
+    """Replace an existing form with a new XLSForm version.
+
+    This updates the form definition while preserving the form UID and existing submissions.
+
+    Args:
+        form_uid: The unique identifier (uid) of the form to replace.
+        file_path: Path to the new XLSForm (.xlsx) file.
+
+    Returns:
+        JSON object with the updated form's uid and deployment status.
+    """
+    import asyncio
+    import os.path
+
+    if not os.path.exists(file_path):
+        return json.dumps({"error": f"File not found: {file_path}"})
+
+    async with httpx.AsyncClient() as client:
+        # Step 1: Create an import task targeting the existing asset
+        with open(file_path, "rb") as f:
+            files = {"file": (os.path.basename(file_path), f, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")}
+            data = {"destination": f"{KOBO_SERVER}/api/v2/assets/{form_uid}/"}
+            response = await client.post(
+                f"{KOBO_SERVER}/api/v2/imports/",
+                headers=get_headers(),
+                files=files,
+                data=data,
+                timeout=60.0,
+            )
+            response.raise_for_status()
+            import_task = response.json()
+
+        import_uid = import_task.get("uid")
+
+        # Step 2: Poll for import completion (max 60 seconds)
+        for _ in range(60):
+            status_response = await client.get(
+                f"{KOBO_SERVER}/api/v2/imports/{import_uid}/",
+                headers=get_headers(),
+                timeout=30.0,
+            )
+            status_response.raise_for_status()
+            status_data = status_response.json()
+
+            if status_data.get("status") == "complete":
+                break
+            elif status_data.get("status") == "error":
+                return json.dumps(
+                    {"status": "error", "message": status_data.get("messages", {})},
+                    indent=2,
+                )
+
+            await asyncio.sleep(1)
+        else:
+            return json.dumps(
+                {"status": "timeout", "message": "Import is still processing."},
+                indent=2,
+            )
+
+        # Step 3: Redeploy the form to make changes live
+        deploy_response = await client.patch(
+            f"{KOBO_SERVER}/api/v2/assets/{form_uid}/deployment/",
+            headers=get_headers(),
+            json={"active": True},
+            timeout=30.0,
+        )
+        deploy_response.raise_for_status()
+
+        # Step 4: Get updated asset info
+        asset_response = await client.get(
+            f"{KOBO_SERVER}/api/v2/assets/{form_uid}/",
+            headers=get_headers(),
+            timeout=30.0,
+        )
+        asset_response.raise_for_status()
+        asset = asset_response.json()
+
+    return json.dumps(
+        {
+            "uid": form_uid,
+            "name": asset.get("name"),
+            "status": "redeployed",
+            "submission_count": asset.get("deployment__submission_count", 0),
+            "url": f"{KOBO_SERVER}/#/forms/{form_uid}",
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+async def export_data(
+    form_uid: str,
+    export_type: str = "csv",
+    include_labels: bool = True,
+) -> str:
+    """Create and download a data export for a form.
+
+    Args:
+        form_uid: The unique identifier (uid) of the form.
+        export_type: Export format - 'csv' or 'xls' (default 'csv').
+        include_labels: Include question labels in headers (default True).
+
+    Returns:
+        JSON object with export download URL or the data itself for small exports.
+    """
+    export_settings = {
+        "fields_from_all_versions": True,
+        "group_sep": "/",
+        "hierarchy_in_labels": include_labels,
+        "multiple_select": "both",
+        "type": export_type,
+    }
+
+    async with httpx.AsyncClient() as client:
+        # Create export
+        response = await client.post(
+            f"{KOBO_SERVER}/api/v2/assets/{form_uid}/exports/",
+            headers=get_headers(),
+            json=export_settings,
+            timeout=30.0,
+        )
+        response.raise_for_status()
+        export_data = response.json()
+
+        export_uid = export_data.get("uid")
+
+        # Poll for completion (max 30 seconds)
+        import asyncio
+
+        for _ in range(30):
+            status_response = await client.get(
+                f"{KOBO_SERVER}/api/v2/assets/{form_uid}/exports/{export_uid}/",
+                headers=get_headers(),
+                timeout=30.0,
+            )
+            status_response.raise_for_status()
+            status_data = status_response.json()
+
+            if status_data.get("status") == "complete":
+                return json.dumps(
+                    {
+                        "status": "complete",
+                        "download_url": status_data.get("result"),
+                        "type": export_type,
+                    },
+                    indent=2,
+                )
+            elif status_data.get("status") == "error":
+                return json.dumps(
+                    {"status": "error", "message": status_data.get("messages", {})},
+                    indent=2,
+                )
+
+            await asyncio.sleep(1)
+
+    return json.dumps(
+        {"status": "pending", "message": "Export is still processing. Try again later."},
+        indent=2,
+    )
+
+
+def main():
+    """Run the MCP server."""
+    # Log to stderr (stdout is reserved for MCP protocol)
+    print("Starting KoboToolbox MCP server...", file=sys.stderr)
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

kobo_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: kobo-mcp
+Version: 0.1.0
+Summary: MCP server for KoboToolbox - deploy surveys and fetch submissions
+Project-URL: Homepage, https://github.com/bbdaniels/kobo-mcp
+Project-URL: Documentation, https://bbdaniels.github.io/kobo-mcp/
+Project-URL: Repository, https://github.com/bbdaniels/kobo-mcp
+Project-URL: Issues, https://github.com/bbdaniels/kobo-mcp/issues
+Author-email: Benjamin Daniels <bbdaniels@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,kobo,kobotoolbox,mcp,survey,xlsform
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# Kobo MCP
+
+[![PyPI version](https://badge.fury.io/py/kobo-mcp.svg)](https://pypi.org/project/kobo-mcp/)
+
+An MCP server for KoboToolbox that enables Claude to deploy surveys and fetch submissions.
+
+**[Documentation](https://bbdaniels.github.io/kobo-mcp/)**
+
+## Features
+
+- **list_forms** - List all KoboToolbox surveys
+- **get_form** - Get detailed form information
+- **get_submissions** - Fetch survey responses
+- **deploy_form** - Upload and deploy XLSForm files
+- **replace_form** - Update existing forms preserving submissions
+- **export_data** - Export data as CSV or Excel
+
+## Installation
+
+```bash
+pip install kobo-mcp
+```
+
+Or run directly with uvx (no install):
+
+```bash
+uvx kobo-mcp
+```
+
+## Configuration
+
+### 1. Get your API token
+
+Go to [KoboToolbox](https://kf.kobotoolbox.org) → Account Settings → Security → Display
+
+### 2. Add to Claude
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "kobotoolbox": {
+      "type": "stdio",
+      "command": "kobo-mcp",
+      "env": {
+        "KOBO_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+Or with uvx:
+
+```json
+{
+  "mcpServers": {
+    "kobotoolbox": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["kobo-mcp"],
+      "env": {
+        "KOBO_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+For EU server, add `"KOBO_SERVER": "https://eu.kobotoolbox.org"` to env.
+
+## Development
+
+```bash
+git clone https://github.com/bbdaniels/kobo-mcp.git
+cd kobo-mcp
+pip install -e .
+```
+
+## License
+
+MIT

kobo_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+kobo_mcp/__init__.py,sha256=kd5Da6RpqW39wTlqulTHiEdOPNmPaxxs4Ke14XeuyIg,45
+kobo_mcp/server.py,sha256=XfsAt83ZBT7Ts3g1Mzf2vAZosOA7LZVRVA3FXwWUQV4,11464
+kobo_mcp-0.1.0.dist-info/METADATA,sha256=kGVWbEW9lfMCLJ1kt41SSSO_wAncDlNZk8IVewFU-WU,2646
+kobo_mcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kobo_mcp-0.1.0.dist-info/entry_points.txt,sha256=rTE1u4k2Y3_uPFS-posQICKWs2J5hIuhyes4rnxMlMg,43
+kobo_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=rAOeMCaTN7BZ21NpEoTbIRI134qQbKjwo580nvv3c7k,1073
+kobo_mcp-0.1.0.dist-info/RECORD,,

kobo_mcp-0.1.0.dist-info/WHEEL

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

kobo_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kobo-mcp = kobo_mcp:main

kobo_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Daniels
+
+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.