nextcloud-organizer-mcp 0.1.0__tar.gz

nextcloud_organizer_mcp-0.1.0/.env.example

@@ -0,0 +1,96 @@
+# Required. Base URL of your Nextcloud instance (no path), e.g. https://cloud.example.com.
+# Used for the Notes app's REST API and as the base from which NEXTCLOUD_CALDAV_URL is
+# derived when unset. Reuses NEXTCLOUD_USERNAME/NEXTCLOUD_APP_PASSWORD.
+# Must be https:// - the server refuses to start with a http:// URL unless it
+# points at a local address (localhost/127.0.0.1/::1) or
+# NEXTCLOUD_ALLOW_INSECURE_HTTP=1 is set (see below), since http:// sends this
+# app password in cleartext Basic Auth on every request.
+NEXTCLOUD_BASE_URL=https://cloud.example.com
+NEXTCLOUD_USERNAME=your-nextcloud-username
+NEXTCLOUD_APP_PASSWORD=your-nextcloud-app-password
+
+# Optional. DAV endpoint root. Defaults to <NEXTCLOUD_BASE_URL>/remote.php/dav/.
+# Only needed when the DAV endpoint is not <base>/remote.php/dav/ (e.g. custom reverse
+# proxy or different host). Both NEXTCLOUD_BASE_URL and NEXTCLOUD_CALDAV_URL must point
+# at the same Nextcloud instance.
+# NEXTCLOUD_CALDAV_URL=https://cloud.example.com/remote.php/dav/
+
+# Optional. How long (in seconds) to wait for a CalDAV or Notes API HTTP
+# request to Nextcloud before giving up. Without a timeout, a hung Nextcloud
+# server would hang this server forever. Default: 30.
+# NEXTCLOUD_HTTP_TIMEOUT_SECONDS=30
+
+# Only needed if NEXTCLOUD_CALDAV_URL or NEXTCLOUD_BASE_URL above is genuinely
+# http:// and does NOT point at localhost/127.0.0.1/::1 (e.g. an
+# internal-network Nextcloud without its own TLS). WARNING: this sends your
+# Nextcloud app password in cleartext on every request - do not set this for
+# a real deployment.
+# NEXTCLOUD_ALLOW_INSECURE_HTTP=1
+
+# OAuth 2.1 authentication (PersonalAuthProvider). The server is a Claude
+# custom connector, authenticated via OAuth + PKCE instead of a static token.
+
+# Required. The exact public URL clients (Claude) use to reach this server -
+# must match precisely, including scheme, or the OAuth discovery/redirect
+# flow will fail. Locally this is http://127.0.0.1:8000; in production it's
+# your public Tailscale Funnel HTTPS URL, e.g.
+# https://your-host.your-tailnet.ts.net
+PUBLIC_BASE_URL=http://127.0.0.1:8000
+
+# Password gate on the OAuth /authorize step. Required (the server refuses
+# to start without it) whenever PUBLIC_BASE_URL above is not localhost, or
+# MCP_HOST below is bound to a non-local address (e.g. 0.0.0.0) - the
+# redirect-domain allow-list alone does NOT stop a scripted client from
+# registering itself via the (intentionally open) DCR endpoint and
+# self-issuing a valid access token, since it never has to actually control
+# the redirect domain, only claim one that's on the allow-list. This password
+# is the only real gate once the server is reachable from the public
+# internet (Tailscale Funnel). Not needed for local-only use
+# (PUBLIC_BASE_URL=http://127.0.0.1:... or http://localhost:... AND
+# MCP_HOST=127.0.0.1/localhost).
+#
+# Uncomment and set this to a long random secret for any non-localhost
+# deployment - the server will refuse to start with the placeholder value
+# below, and will also refuse to start with no password at all once it's
+# reachable from anywhere but localhost. Generate a value with:
+#   python3 -c "import secrets; print(secrets.token_urlsafe(24))"
+# MCP_OAUTH_PASSWORD=change-me-to-a-long-random-password
+
+# Optional, comma-separated. Only these domains (and subdomains) may
+# complete the OAuth redirect. Default when unset: claude.ai,claude.com for a
+# non-localhost PUBLIC_BASE_URL (a "localhost" entry in a public deployment's
+# allow-list can never be reached by a real OAuth redirect anyway); for a
+# localhost PUBLIC_BASE_URL, claude.ai,claude.com,localhost.
+# MCP_OAUTH_ALLOWED_REDIRECT_DOMAINS=claude.ai,claude.com,localhost
+
+# Optional. How long issued access tokens are valid, in seconds.
+# Default: 2592000 (30 days).
+# MCP_OAUTH_ACCESS_TOKEN_EXPIRY_SECONDS=2592000
+
+# Optional. How long issued refresh tokens are valid, in seconds, before a
+# client must fully re-authorize (D5) - bounds how long a leaked
+# oauth_tokens.json grants access for. Default: 15552000 (180 days).
+# MCP_OAUTH_REFRESH_TOKEN_EXPIRY_SECONDS=15552000
+
+# Optional. Directory where OAuth client registrations and tokens are
+# persisted (oauth_tokens.json) so they survive server restarts.
+# Default: .oauth-state (relative to the working directory).
+# MCP_OAUTH_STATE_DIR=.oauth-state
+
+# Networking (optional, defaults shown). The server only needs to bind to
+# a local port - tailscale funnel handles TLS termination in front of it.
+MCP_HOST=127.0.0.1
+MCP_PORT=8000
+
+# Optional. Default timezone for naive datetime inputs, day windows (agenda/filter bounds),
+# and output timestamps returned to callers. Default: Europe/Berlin.
+# Setting MCP_DEFAULT_TIMEZONE=UTC restores the previous UTC behavior.
+# MCP_DEFAULT_TIMEZONE=Europe/Berlin
+
+# Set to 1 to enable integration tests that hit the real Nextcloud instance
+# configured above (see README for details). Leave unset for unit tests only.
+# RUN_INTEGRATION_TESTS=1
+
+# Name of an existing (ideally disposable) task list to use for integration
+# tests. Tasks are created and deleted in this list during the test run.
+# INTEGRATION_TEST_LIST=Test

nextcloud_organizer_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns: ["*"]

nextcloud_organizer_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint with ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Type check with mypy
+        run: uv run mypy src tests
+
+      - name: Run unit tests
+        run: |
+          uv run pytest -q --cov=src/nextcloud_organizer_mcp --cov-report=term-missing \
+            --cov-fail-under=90

nextcloud_organizer_mcp-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,104 @@
+# Scheduled integration test run against a real (containerized) Nextcloud
+# instance (E11). This complements ci.yml's unit tests, which mock the
+# `caldav` library entirely and never touch a real CalDAV server.
+#
+# NOTE: this workflow could not be executed/verified end-to-end while writing
+# it (no way to run GitHub Actions service containers in this environment).
+# The env vars it sets are wired to exactly what tests/test_integration.py
+# reads (NEXTCLOUD_CALDAV_URL / NEXTCLOUD_USERNAME / NEXTCLOUD_APP_PASSWORD /
+# INTEGRATION_TEST_LIST / RUN_INTEGRATION_TESTS), and the Nextcloud
+# auto-setup env vars below follow the documented `nextcloud` Docker image
+# contract - but the full flow (image boot, auto-install, calendar creation,
+# first real test run) has only been reviewed, not observed. If it fails on
+# its first scheduled/dispatched run, start by checking the "Wait for
+# Nextcloud to be ready" and "Provision the test task list" steps' output.
+name: Integration tests
+
+on:
+  schedule:
+    # Mondays at 04:00 UTC.
+    - cron: "0 4 * * 1"
+  workflow_dispatch: {}
+
+# Deliberately no `push`/`pull_request` trigger: this hits a real (if
+# ephemeral, containerized) Nextcloud instance and is too slow/flaky to gate
+# every PR on.
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    # Fail the workflow (and surface it) on any test failure - no silent
+    # green runs.
+    continue-on-error: false
+
+    services:
+      nextcloud:
+        image: nextcloud:latest
+        ports:
+          - 8080:80
+        env:
+          # Auto-setup env vars documented by the official `nextcloud` image's
+          # entrypoint: presence of NEXTCLOUD_ADMIN_USER/PASSWORD plus a
+          # database config (SQLITE_DATABASE here, to avoid needing a
+          # separate DB service container for a throwaway test instance)
+          # triggers `occ maintenance:install` automatically on first boot.
+          SQLITE_DATABASE: nextcloud
+          NEXTCLOUD_ADMIN_USER: admin
+          NEXTCLOUD_ADMIN_PASSWORD: ${{ secrets.INTEGRATION_NEXTCLOUD_ADMIN_PASSWORD || 'nextcloud-ci-admin-pw' }}
+
+    env:
+      NEXTCLOUD_USERNAME: admin
+      # Real deployments use a per-app password generated under Settings ->
+      # Security; for this disposable, network-isolated CI instance the admin
+      # account password is used directly to keep provisioning simple - it
+      # only exists for the lifetime of the job's service container.
+      NEXTCLOUD_APP_PASSWORD: ${{ secrets.INTEGRATION_NEXTCLOUD_ADMIN_PASSWORD || 'nextcloud-ci-admin-pw' }}
+      NEXTCLOUD_CALDAV_URL: "http://localhost:8080/remote.php/dav/"
+      INTEGRATION_TEST_LIST: "Test"
+      RUN_INTEGRATION_TESTS: "1"
+      # The container is plain http:// (no TLS) - Settings.from_env() would
+      # normally refuse that (D8), but tests/test_integration.py builds
+      # CalDavService directly and never goes through Settings, so this
+      # isn't actually read today. Set anyway in case that changes.
+      NEXTCLOUD_ALLOW_INSECURE_HTTP: "1"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Wait for Nextcloud to be ready
+        run: |
+          for i in $(seq 1 60); do
+            if curl -sf http://localhost:8080/status.php | grep -q '"installed":true'; then
+              echo "Nextcloud is up and installed."
+              exit 0
+            fi
+            echo "Waiting for Nextcloud... ($i/60)"
+            sleep 5
+          done
+          echo "Nextcloud did not become ready in time." >&2
+          exit 1
+
+      - name: Provision the test task list
+        run: |
+          container_id="$(docker ps -q --filter ancestor=nextcloud:latest)"
+          # The calendar app (bundled with Nextcloud, provides the CalDAV
+          # VTODO backend Tasks/this server both use) may ship disabled by
+          # default - make sure it's on before creating a calendar in it.
+          docker exec "$container_id" php occ app:enable calendar
+          # `dav:create-calendar` (part of the bundled DAV app) creates a
+          # calendar (= task list, from this server's point of view) for a
+          # user by uid.
+          docker exec "$container_id" php occ dav:create-calendar "$NEXTCLOUD_USERNAME" "$INTEGRATION_TEST_LIST"
+
+      - name: Run integration tests
+        run: uv run pytest tests/test_integration.py -q

nextcloud_organizer_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Check tag matches project version
+        run: |
+          version="$(uv version --short)"
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match project version ${version}" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nextcloud-organizer-mcp
+    permissions:
+      # Required for PyPI trusted publishing (OIDC); no API token is stored.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nextcloud_organizer_mcp-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+.venv/
+venv/
+env/
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+.env
+.env.local
+
+# Persisted OAuth clients/tokens (PersonalAuthProvider), contains secrets.
+.oauth-state/
+
+.DS_Store
+
+# graphify skill output (generated knowledge-graph artifacts, not project source).
+graphify-out/

nextcloud_organizer_mcp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# Local hooks that shell out to `uv run`, so the tool versions used here are
+# always the ones pinned in uv.lock - no separate, potentially-drifting
+# pre-commit-managed toolchain to keep in sync (E10). Run `pre-commit install`
+# once (see CONTRIBUTING.md) to wire these into `git commit`.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check --fix
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+
+      - id: mypy
+        name: mypy src tests
+        entry: uv run mypy src tests
+        language: system
+        pass_filenames: false
+        types: [python]