mcp-pcloud-crunchtools 2.1.0__tar.gz

mcp_pcloud_crunchtools-2.1.0/.containerignore

@@ -0,0 +1,9 @@
+.venv
+.git
+.mypy_cache
+.ruff_cache
+.pytest_cache
+.gourmand-cache
+dist
+build
+*.egg-info

mcp_pcloud_crunchtools-2.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,67 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of the bug
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this bug?
+      placeholder: |
+        1. Call tool '...' with args '...'
+        2. Observe error '...'
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages if available.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport
+      description: How are you running the MCP server?
+      options:
+        - stdio (uvx / pip)
+        - streamable-http (container / systemd)
+        - SSE
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Server Version
+      description: Output of `mcp-pcloud-crunchtools --version` or pip show
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information (logs, config, environment)

mcp_pcloud_crunchtools-2.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: fastembed Documentation
+    url: https://qdrant.github.io/fastembed/
+    about: Check fastembed docs for embedding model questions

mcp_pcloud_crunchtools-2.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,50 @@
+name: Feature Request
+description: Suggest a new tool or enhancement
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve?
+      placeholder: I need to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the tool or change you'd like
+      placeholder: |
+        Tool name: `pcloud_something`
+        Parameters: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What alternatives have you considered?
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Tool Category
+      description: Which area does this feature belong to?
+      options:
+        - Search
+        - Index Management
+        - Status
+        - File Extraction
+        - New Category
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information or examples

mcp_pcloud_crunchtools-2.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run linter
+        run: uv run ruff check src tests
+      - name: Run type checker
+        run: uv run mypy src
+      - name: Run tests
+        run: uv run pytest -v
+
+  gourmand:
+    name: Code Quality (Gourmand)
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/crunchtools/gourmand:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Gourmand
+        run: gourmand --full
+
+  build-container:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build container image
+        run: docker build -f Containerfile -t mcp-pcloud:test .
+      - name: Verify container
+        run: timeout 5 docker run --rm mcp-pcloud:test || true
+
+  validate-constitution:
+    name: Constitution Validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: crunchtools/constitution
+          path: .constitution
+      - name: Validate constitution
+        run: python3 .constitution/validate-constitution.py .specify/memory/constitution.md --verbose

mcp_pcloud_crunchtools-2.1.0/.github/workflows/container.yml

@@ -0,0 +1,101 @@
+name: Container Build & Push
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  QUAY_IMAGE: quay.io/crunchtools/mcp-pcloud
+  GHCR_IMAGE: ghcr.io/crunchtools/mcp-pcloud
+
+jobs:
+  build-and-push-quay:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Log in to Quay.io
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: quay.io
+          username: ${{ secrets.QUAY_USERNAME }}
+          password: ${{ secrets.QUAY_PASSWORD }}
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.QUAY_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Containerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: Run Trivy vulnerability scanner
+        continue-on-error: true
+        if: github.event_name != 'pull_request'
+        uses: aquasecurity/trivy-action@0.35.0
+        with:
+          image-ref: ${{ env.QUAY_IMAGE }}:latest
+          format: "table"
+          exit-code: "0"
+          severity: "CRITICAL,HIGH"
+          version: "v0.68.2"
+
+  build-and-push-ghcr:
+    runs-on: ubuntu-latest
+    needs: build-and-push-quay
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ github.token }}
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.GHCR_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Containerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha

mcp_pcloud_crunchtools-2.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_pcloud_crunchtools-2.1.0/.github/workflows/security.yml

@@ -0,0 +1,94 @@
+name: Security Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  security-events: write
+
+jobs:
+  dependency-audit:
+    name: Dependency CVE Scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync
+      - name: Install pip-audit
+        run: uv pip install pip-audit
+      - name: Run pip-audit
+        id: audit
+        continue-on-error: true
+        run: |
+          uv run pip-audit --format=json --output=audit-results.json || true
+          uv run pip-audit --format=markdown --output=audit-results.md || true
+          if [ -f audit-results.json ]; then
+            VULN_COUNT=$(cat audit-results.json | python -c "import sys,json; data=json.load(sys.stdin); print(len([d for d in data if d.get('vulns', [])]))" 2>/dev/null || echo "0")
+            echo "vuln_count=$VULN_COUNT" >> $GITHUB_OUTPUT
+          else
+            echo "vuln_count=0" >> $GITHUB_OUTPUT
+          fi
+      - name: Upload audit results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-audit-results
+          path: |
+            audit-results.json
+            audit-results.md
+          retention-days: 30
+      - name: Fail on vulnerabilities (PRs only)
+        if: steps.audit.outputs.vuln_count != '0' && github.event_name == 'pull_request'
+        run: |
+          echo "::error::Security vulnerabilities found in dependencies."
+          exit 1
+
+  container-scan:
+    name: Container Security Scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build container image
+        run: docker build -f Containerfile -t mcp-pcloud:scan .
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: "mcp-pcloud:scan"
+          format: "sarif"
+          output: "trivy-results.sarif"
+          severity: "CRITICAL,HIGH"
+      - name: Upload Trivy scan results
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: "trivy-results.sarif"
+
+  codeql:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          queries: security-extended
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:python"

mcp_pcloud_crunchtools-2.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.gourmand-cache/
+.coverage
+htmlcov/
+uv.lock

mcp_pcloud_crunchtools-2.1.0/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+        stages: [pre-commit, pre-merge-commit]
+      - id: ruff-format
+        stages: [pre-commit, pre-merge-commit]

mcp_pcloud_crunchtools-2.1.0/.specify/memory/constitution.md

@@ -0,0 +1,200 @@
+# mcp-pcloud-crunchtools Constitution
+
+> **Version:** 1.1.0
+> **Ratified:** 2026-09-05
+> **Last Amended:** 2026-09-05
+> **Status:** Active
+> **Inherits:** [crunchtools/constitution](https://github.com/crunchtools/constitution) v1.10.0
+> **Profile:** MCP Server
+
+This constitution establishes the core principles, constraints, and workflows that govern all development on mcp-pcloud-crunchtools.
+
+---
+
+## I. Core Principles
+
+### 1. Five-Layer Security Model
+
+Every change MUST preserve all five security layers. No exceptions.
+
+**Layer 1 — Credential Protection:**
+- The pCloud OAuth access token is held as a Pydantic `SecretStr` and is never logged.
+- `PCLOUD_ACCESS_TOKEN_FILE` is supported and takes precedence over `PCLOUD_ACCESS_TOKEN`. File contents are stripped on read; a token file readable beyond its owner raises a warning, never a failure.
+- `Config.__repr__` and `Config.__str__` render the token as `***`.
+- `errors._scrub` removes any configured credential value from every outgoing error message.
+
+**Layer 2 — Input Validation:**
+- Every tool validates input through a Pydantic v2 model with `extra="forbid"`.
+- Paths MUST be absolute, free of NUL bytes, length-bounded, and free of `..` traversal segments. Traversal rejection is what keeps a caller from escaping a folder they were scoped to by a gateway tool allowlist.
+- Search queries are length-bounded and non-empty.
+
+**Layer 3 — API Hardening:**
+- Credentials MUST NOT appear in a URL. An OAuth access token is sent in an `Authorization: Bearer` header; a pCloud session token is sent in a POST body. Password-derived tokens travelled in the query string; that authentication mode was removed in 2.0.0 and MUST NOT return.
+- TLS certificate validation is left at httpx defaults and MUST NOT be made configurable off.
+- Requests carry a 30 second timeout; responses above 10 MB are rejected.
+- pCloud result codes are mapped onto the safe error hierarchy rather than surfaced raw.
+
+**Layer 4 — Dangerous Operation Prevention:**
+- No shell execution, no code evaluation, no `eval()`/`exec()`, no local filesystem access beyond reading the credential file.
+- Tools are pure pCloud API wrappers.
+
+**Layer 5 — Supply Chain Security:**
+- Weekly automated CVE scanning via GitHub Actions.
+- Hummingbird FIPS container base images, distroless runtime.
+- Gourmand AI slop detection gates every PR at zero violations.
+
+### 2. Two-Layer Tool Architecture
+
+- `server.py` holds `@mcp.tool()` wrappers that validate arguments and delegate.
+- `tools/*.py` holds pure async functions that call `client.py`.
+
+Business logic MUST NOT live in `server.py`. MCP registration MUST NOT live in `tools/*.py`.
+
+### 3. Authentication Is Token-Based, OAuth Preferred
+
+pCloud accounts with two-factor authentication enabled cannot complete the legacy digest login, and that flow placed the resulting token in the URL query string. This server never derives a credential from a password and never places one in a URL.
+
+Two credential kinds are accepted:
+
+| Kind | Variable | Transport |
+|------|----------|-----------|
+| OAuth access token | `PCLOUD_ACCESS_TOKEN` | `Authorization: Bearer` header, GET |
+| pCloud session token | `PCLOUD_AUTH_TOKEN` | `auth` field in a POST body |
+
+Both honor the `_FILE` convention. When both are configured the OAuth token wins; the session token is a fallback for accounts that have no OAuth application provisioned.
+
+A session token is accepted because pCloud issues it to its own desktop client and rejects it as an `access_token` (`result 2094`), so it cannot be exchanged for an OAuth token. It carries the same authority as an OAuth token and MUST be protected identically. The security property the constitution actually defends is that a credential never enters a URL, where it would leak into access logs, proxies, and referrers; a POST body preserves that property.
+
+Reintroducing username/password authentication, or moving any credential into a URL or query string, requires a constitutional amendment.
+
+### 4. Three Distribution Channels
+
+Every release ships through uvx, pip (PyPI), and container (Quay.io + GHCR) simultaneously.
+
+### 5. Three Transport Modes
+
+stdio (default), SSE, and streamable-http MUST all remain supported.
+
+---
+
+## II. Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| Language | Python 3.11+ |
+| MCP Framework | FastMCP (`fastmcp>=2.0,<3.0`) |
+| HTTP Client | httpx |
+| Validation | Pydantic v2 |
+| Container Base | Hummingbird FIPS |
+| Package Manager | uv |
+| Build System | hatchling |
+| Linter | ruff |
+| Type Checker | mypy (strict) |
+| Tests | pytest + pytest-asyncio |
+| Slop Detector | gourmand |
+
+`fastmcp` is pinned below 3.0 deliberately: fastmcp 3.x pulls `mcp>=2.0`, which renames `FastMCP` to `MCPServer` and changes the client stream contract. The lotor backend fleet runs the v1 protocol.
+
+---
+
+## III. Container Conventions
+
+- Build file is `Containerfile`.
+- Multi-stage venv build; builder and runtime MUST both be Hummingbird FIPS images.
+- Runtime is distroless — no shell-form `RUN` in the runtime stage.
+- Required labels: `name`, `version`, `summary`, `maintainer`, plus `org.opencontainers.image.source`, `.description`, and `.licenses`.
+- `EXPOSE 8028` — the assigned HTTP port for this server.
+
+---
+
+## IV. Testing Standards
+
+- Every tool has a mocked test; no live pCloud calls in CI and no token required.
+- `httpx.AsyncClient.get` is patched; tool functions are called directly rather than through the MCP wrapper.
+- An autouse fixture resets the `config` and `client` singletons between every test.
+- `test_tool_count` MUST be updated whenever tools are added or removed.
+- Error-code mapping, token scrubbing, and identifier truncation MUST each retain explicit tests.
+
+---
+
+## V. Code Quality Gates
+
+| Gate | Command |
+|------|---------|
+| Lint | `uv run ruff check src tests` |
+| Type Check | `uv run mypy src` |
+| Tests | `uv run pytest -v` |
+| Gourmand | `gourmand --full` (zero violations) |
+| Code Review | Gatehouse AI code review on every PR |
+| Container Build | `podman build -f Containerfile .` |
+
+### Gourmand Exception Policy
+
+Exceptions MUST carry a documented justification in `gourmand-exceptions.toml`. Acceptable reasons are standard API patterns, test-specific patterns, and framework requirements. Unacceptable reasons are "the code is special", "the threshold is too strict", and rewording to evade detection. This repository currently declares no exceptions and MUST stay at zero violations without them.
+
+---
+
+## VI. Naming
+
+| Context | Value |
+|---------|-------|
+| GitHub repo | `crunchtools/mcp-pcloud` |
+| PyPI package | `mcp-pcloud-crunchtools` |
+| Python module | `mcp_pcloud_crunchtools` |
+| Container | `quay.io/crunchtools/mcp-pcloud`, `ghcr.io/crunchtools/mcp-pcloud` |
+| MCP Registry | `io.github.crunchtools/pcloud` |
+| systemd service | `mcp-pcloud.crunchtools.com.service` |
+| License | AGPL-3.0-or-later |
+
+---
+
+## VII. Semantic Versioning
+
+Releases follow Semantic Versioning 2.0.0. MAJOR for incompatible changes to tool signatures or authentication, MINOR for backwards-compatible tools or capabilities, PATCH for backwards-compatible fixes. Version 2.0.0 records the removal of username/password authentication and the port from TypeScript to Python.
+
+The version MUST be identical in `pyproject.toml`, `__init__.py`, `server.py`, `server.json`, and the `Containerfile` label.
+
+---
+
+## VIII. Development Workflow
+
+### Adding a Tool
+
+1. Add the async function to the appropriate `tools/*.py`.
+2. Export it from `tools/__init__.py`.
+3. Register an `@mcp.tool()` wrapper in `server.py` that validates through a Pydantic model.
+4. Add a mocked test in `tests/test_tools.py`.
+5. Update `EXPECTED_TOOL_COUNT` and `EXPECTED_TOOLS` in `tests/test_server.py`.
+6. Run all quality gates.
+
+### Deprecation Policy
+
+A removed or renamed tool is announced in the release notes of one MINOR release before removal, and removal lands in the next MAJOR.
+
+---
+
+## IX. Governance
+
+This repository carries the full text of its governance. The `Inherits` header declares alignment with the MCP Server profile, not a runtime dependency on it.
+
+Files:
+- `.specify/memory/constitution.md` — this document
+- `.specify/specs/000-baseline/spec.md` — tool inventory and architecture baseline
+- `.specify/templates/` — `plan-template.md` and `spec-template.md`
+
+### Specification-Driven Development
+
+New tool groups, new subsystems, changes to the security model, and changes spanning multiple modules each require a numbered spec under `.specify/specs/` before implementation. Bug fixes, dependency updates, CI changes, documentation, and single-tool additions following Section VIII are exempt.
+
+---
+
+## X. Amendment Process
+
+Amendments follow the universal constitution's process. Changes to the five-layer security model or to the authentication principle require an explicit version bump of this document and a recorded justification.
+
+### Amendment History
+
+| Version | Date | Change |
+|---------|------|--------|
+| 1.0.0 | 2026-09-05 | Initial ratification alongside the 2.0.0 Python rewrite. |
+| 1.1.0 | 2026-09-05 | Section I.3 widened from "OAuth only" to "token-based, OAuth preferred", admitting pCloud session tokens transported in a POST body. Rationale: pCloud rejects its own desktop-client session token as an `access_token` (`result 2094`), so an account without a provisioned OAuth application had no usable credential. The no-credentials-in-URL rule is unchanged and is what Layer 3 continues to enforce. |