chore(deps): update docker.io/library/python docker tag to v3.15

Reviewed-on: #62

.gitea/workflows/cron.yaml

@@ -0,0 +1,102 @@
+name: Nightly Rebuild
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+
+jobs:
+  hadolint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: hadolint/hadolint-action@06be81baf89a55ffd0e24b8f04a4185738dd3387 # v3.5.0
+        continue-on-error: true
+        with:
+          dockerfile: pkg/Dockerfile
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest
+      - name: Run unit tests
+        run: pytest tests/ -v
+        env:
+          # indexer/server read env at import; unit tests need no real backend
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test
+
+  integration-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Cleanup old Qdrant container
+        run: |
+          docker rm -f qdrant-${{ github.run_id }} 2>/dev/null || true
+
+      - name: Start Qdrant
+        run: |
+          docker run -d --name qdrant-${{ github.run_id }} \
+            --network "container:$(hostname)" \
+            docker.io/qdrant/qdrant:latest
+
+      - name: Wait for Qdrant
+        run: |
+          for i in $(seq 1 30); do
+            curl -s http://localhost:6333/healthz \
+              && echo "QDRANT ready" && break
+            echo "Waiting for Qdrant... ($i/30)"
+            sleep 1
+          done
+          curl -s http://localhost:6333/healthz > /dev/null
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest
+      - name: Run integration tests
+        run: pytest tests/ -v -m integration
+        env:
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test_mcp_maildir
+
+      - name: Cleanup Qdrant
+        if: always()
+        run: docker rm -f qdrant-${{ github.run_id }} || true
+
+  build-push:
+    needs: [test, integration-test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - id: get-latest-tag
+        run: |
+          TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+      - id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
+        with:
+          images: jcabillot/mcp-maildir
+          tags: |
+            type=raw,value=${{ steps.get-latest-tag.outputs.tag }}-latest,enable=${{ steps.get-latest-tag.outputs.tag != '' }}
+      - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: pkg/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          pull: true

.gitea/workflows/docker-build.yaml

@@ -9,35 +9,107 @@ on:
     - cron: '0 0 * * *'
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt pytest
+      - name: Run unit tests
+        run: pytest tests/ -v --ignore=tests/test_integration.py
+
+  integration-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Start Qdrant
+        run: |
+          docker rm -f qdrant-${{ github.run_id }} 2>/dev/null || true
+          docker run -d --name qdrant-${{ github.run_id }} \
+            --network "container:$(hostname)" \
+            docker.io/qdrant/qdrant:v1.19
+
+      - name: Wait for Qdrant
+        run: |
+          # /healthz answers before the storage engine accepts writes, and a cold
+          # container on a loaded host can take several seconds to create its
+          # first collection. Gate on a real write round-trip, not on /healthz.
+          ready=""
+          for i in $(seq 1 60); do
+            if curl -sf "http://localhost:6333/healthz" > /dev/null 2>&1 \
+              && curl -sf -X PUT "http://localhost:6333/collections/ci_readiness_probe?timeout=60" \
+                   -H 'Content-Type: application/json' \
+                   -d '{"vectors":{"size":4,"distance":"Cosine"}}' > /dev/null 2>&1; then
+              curl -sf -X DELETE "http://localhost:6333/collections/ci_readiness_probe" > /dev/null 2>&1 || true
+              ready="yes"
+              echo "QDRANT ready: write path OK (attempt $i)"
+              break
+            fi
+            echo "Waiting for Qdrant... ($i/60)"
+            sleep 1
+          done
+          if [ -z "$ready" ]; then
+            echo "Qdrant write path never became ready"
+            docker logs --tail 100 qdrant-${{ github.run_id }} || true
+            exit 1
+          fi
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt pytest
+      - name: Run integration tests
+        run: pytest tests/ -v -m integration
+        env:
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test_mcp_maildir
+          # The qdrant client defaults to a 5s request timeout, which a cold
+          # collection on a shared runner can exceed; this job has no SLA.
+          QDRANT_TIMEOUT: "60"
+
+      - name: Qdrant diagnostics
+        if: failure()
+        run: |
+          docker ps -a || true
+          docker logs --tail 200 qdrant-${{ github.run_id }} || true
+
+      - name: Cleanup Qdrant
+        if: always()
+        run: docker rm -f qdrant-${{ github.run_id }} 2>/dev/null || true
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, integration-test]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to Docker Hub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Docker metadata
         id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
         with:
           images: jcabillot/mcp-maildir
           tags: |
-            #type=ref,event=branch
-            #type=ref,event=pr
-            #type=sha
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
 
       - name: Build and push
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: pkg/Dockerfile

.gitea/workflows/main.yaml

@@ -0,0 +1,123 @@
+name: Main Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  hadolint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: hadolint/hadolint-action@06be81baf89a55ffd0e24b8f04a4185738dd3387 # v3.5.0
+        continue-on-error: true
+        with:
+          dockerfile: pkg/Dockerfile
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest ruff==0.17.1
+      - name: Lint (undefined names)
+        run: ruff check src/ tests/ --select F821
+      - name: Run unit tests
+        run: pytest tests/ -v
+        env:
+          # indexer/server read env at import; unit tests need no real backend
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test
+
+  integration-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Cleanup old Qdrant container
+        run: |
+          docker rm -f qdrant-${{ github.run_id }} 2>/dev/null || true
+
+      - name: Start Qdrant
+        run: |
+          docker run -d --name qdrant-${{ github.run_id }} \
+            --network "container:$(hostname)" \
+            docker.io/qdrant/qdrant:v1.19
+
+      - name: Wait for Qdrant
+        run: |
+          # /healthz answers before the storage engine accepts writes, and a cold
+          # container on a loaded host can take several seconds to create its
+          # first collection. Gate on a real write round-trip, not on /healthz.
+          ready=""
+          for i in $(seq 1 60); do
+            if curl -sf "http://localhost:6333/healthz" > /dev/null 2>&1 \
+              && curl -sf -X PUT "http://localhost:6333/collections/ci_readiness_probe?timeout=60" \
+                   -H 'Content-Type: application/json' \
+                   -d '{"vectors":{"size":4,"distance":"Cosine"}}' > /dev/null 2>&1; then
+              curl -sf -X DELETE "http://localhost:6333/collections/ci_readiness_probe" > /dev/null 2>&1 || true
+              ready="yes"
+              echo "QDRANT ready: write path OK (attempt $i)"
+              break
+            fi
+            echo "Waiting for Qdrant... ($i/60)"
+            sleep 1
+          done
+          if [ -z "$ready" ]; then
+            echo "Qdrant write path never became ready"
+            docker logs --tail 100 qdrant-${{ github.run_id }} || true
+            exit 1
+          fi
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest
+      - name: Run integration tests
+        run: pytest tests/ -v -m integration
+        env:
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test_mcp_maildir
+          # The qdrant client defaults to a 5s request timeout, which a cold
+          # collection on a shared runner can exceed; this job has no SLA.
+          QDRANT_TIMEOUT: "60"
+
+      - name: Qdrant diagnostics
+        if: failure()
+        run: |
+          docker ps -a || true
+          docker logs --tail 200 qdrant-${{ github.run_id }} || true
+
+      - name: Cleanup Qdrant
+        if: always()
+        run: docker rm -f qdrant-${{ github.run_id }} || true
+
+  build:
+    needs: [test, integration-test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
+      - run: docker build -f pkg/Dockerfile -t jcabillot/mcp-maildir:${{ github.sha }} .
+
+  tag:
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - name: Configure git auth
+        run: |
+          git remote set-url origin "https://x-access-token:${{ secrets.SA_TOKEN_ACTION_PUSH_TAGS }}@scm.cabillot.eu/perso/mcp-maildir.git"
+      - uses: anothrNick/github-tag-action@4ed44965e0db8dab2b466a16da04aec3cc312fd8 # v1.75.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.SA_TOKEN_ACTION_PUSH_TAGS }}
+          DEFAULT_BUMP: patch
+          RELEASE_BRANCHES: main
+          WITH_V: true
+          GIT_API_TAGGING: false

.gitea/workflows/pr.yaml

@@ -0,0 +1,38 @@
+name: PR Checks
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  hadolint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: hadolint/hadolint-action@06be81baf89a55ffd0e24b8f04a4185738dd3387 # v3.5.0
+        continue-on-error: true
+        with:
+          dockerfile: pkg/Dockerfile
+
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest
+      - name: Run unit tests
+        run: pytest tests/ -v
+        env:
+          # indexer/server read env at import; unit tests need no real backend
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test
+
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
+      - run: docker build -f pkg/Dockerfile -t ci-image:${{ github.sha }} .

.gitea/workflows/renovate.yaml

@@ -0,0 +1,12 @@
+name: Renovate
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  renovate:
+    uses: perso/gitea-pipelines/.gitea/workflows/renovate.yaml@main
+    secrets: inherit

.gitea/workflows/tag.yaml

@@ -0,0 +1,116 @@
+name: Tag Release
+
+on:
+  push:
+    tags: ['*']
+
+jobs:
+  hadolint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: hadolint/hadolint-action@06be81baf89a55ffd0e24b8f04a4185738dd3387 # v3.5.0
+        continue-on-error: true
+        with:
+          dockerfile: pkg/Dockerfile
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest
+      - name: Run unit tests
+        run: pytest tests/ -v
+        env:
+          # indexer/server read env at import; unit tests need no real backend
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test
+
+  integration-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Cleanup old Qdrant container
+        run: |
+          docker rm -f qdrant-${{ github.run_id }} 2>/dev/null || true
+
+      - name: Start Qdrant
+        run: |
+          docker run -d --name qdrant-${{ github.run_id }} \
+            --network "container:$(hostname)" \
+            docker.io/qdrant/qdrant:latest
+
+      - name: Wait for Qdrant
+        run: |
+          for i in $(seq 1 30); do
+            curl -s http://localhost:6333/healthz \
+              && echo "QDRANT ready" && break
+            echo "Waiting for Qdrant... ($i/30)"
+            sleep 1
+          done
+          curl -s http://localhost:6333/healthz > /dev/null
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest
+      - name: Run integration tests
+        run: pytest tests/ -v -m integration
+        env:
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test_mcp_maildir
+
+      - name: Cleanup Qdrant
+        if: always()
+        run: docker rm -f qdrant-${{ github.run_id }} || true
+
+  build-push:
+    needs: [test, integration-test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
+        with:
+          images: jcabillot/mcp-maildir
+          tags: |
+            type=ref,event=tag
+            type=ref,event=tag,suffix=-latest
+      - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: pkg/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          pull: true
+
+  trigger-renovate:
+    # The deployment repo perso_private/tf-depl-kubernetes pins this image; its
+    # Renovate instance only scans hourly, so this dispatch opens the image bump
+    # PR within minutes of the release instead of up to an hour later.
+    needs: [build-push]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Renovate on perso_private/tf-depl-kubernetes
+        # needs: build-push — Renovate reads Docker Hub, so a scan started before
+        # the push lands would only see the previous release.
+        # RENOVATE_TOKEN is the org-level secret of this organisation.
+        run: |
+          curl -sS -f -X POST \
+            -u "renovate:${{ secrets.RENOVATE_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d '{{"ref":"main"}}' \
+            "https://scm.cabillot.eu/api/v1/repos/perso_private/tf-depl-kubernetes/actions/workflows/renovate.yaml/dispatches"
+          echo "Renovate dispatched on perso_private/tf-depl-kubernetes"

Jenkinsfile

@@ -1,38 +0,0 @@
-pipeline {
-  environment {
-    registry = 'https://registry.hub.docker.com'
-    registryCredential = 'dockerhub_jcabillot'
-    dockerImage = 'jcabillot/mcp-maildir'
-  }
-
-  agent any
-
-  triggers {
-    cron('@midnight')
-  }
-
-  stages {
-    stage('Clone repository') {
-      steps{
-        checkout scm
-      }
-    }
-
-    stage('Build image') {
-      steps{
-        sh 'docker build --force-rm=true --no-cache=true --pull -t ${dockerImage} -f pkg/Dockerfile .'
-      }
-    }
-
-    stage('Deploy Image') {
-      steps{
-        script {
-          withCredentials([usernamePassword(credentialsId: 'dockerhub_jcabillot', usernameVariable: 'DOCKER_USER', passwordVariable: 'DOCKER_PASS')]) {
-            sh 'docker login --username ${DOCKER_USER} --password ${DOCKER_PASS}'
-            sh 'docker push ${dockerImage}'
-          }
-        }
-      }
-    }
-  }
-}

TEA_TEST.md

@@ -0,0 +1 @@
+test

docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   qdrant:
-    image: docker.io/qdrant/qdrant:latest
+    image: docker.io/qdrant/qdrant:v1.19
     container_name: mcp_maildir_qdrant
     ports:
       - "127.0.0.1:6333:6333" # REST API
@@ -15,7 +15,7 @@ services:
       dockerfile: pkg/Dockerfile
     container_name: mcp_maildir_server
     ports:
-      - "127.0.0.1:8000:8000" # Expose the MCP HTTP (SSE) server
+      - "127.0.0.1:8000:8000" # Expose the MCP Streamable HTTP server (/mcp)
     env_file:
       - .env
     environment:

pkg/Dockerfile

@@ -1,5 +1,5 @@
 # 3.13, because with 3.14 it requires gcc (wheels not available)
-FROM docker.io/library/python:3.14-slim
+FROM docker.io/library/python:3.15-slim
 
 # Set environment variables
 ENV PYTHONDONTWRITEBYTECODE=1

pytest.ini

@@ -0,0 +1,8 @@
+[pytest]
+testpaths = tests
+pythonpath = src
+; Integration tests (tests/test_integration.py) require a live Qdrant on
+; localhost:6333 — they only run in the nightly CI job (or manually with -m integration).
+markers =
+    integration: requires a live Qdrant instance (deselected by default)
+addopts = -m "not integration" -p no:cacheprovider

renovate.json

@@ -1,12 +1,14 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
-  "regexManagers": [
+  "customManagers": [
     {
-      "description": "Track qdrant/qdrant Docker image from docker-compose.yml (native manager missed it)",
-      "fileMatch": ["^docker-compose\\.ya?ml$"],
-      "matchStrings": [
-        "image:\\s*(?:docker\\.io/)?qdrant/qdrant:(?<currentValue>[^\\s]+)"
+      "customType": "regex",
+      "description": "Track the pinned qdrant/qdrant image in docker-compose.yml and the CI workflows (native manager missed it)",
+      "managerFilePatterns": [
+        "/^docker-compose\\.ya?ml$/",
+        "/^\\.gitea/workflows/.*\\.ya?ml$/"
       ],
+      "matchStrings": ["(?:docker\\.io/)?qdrant/qdrant:(?<currentValue>[^\\s\"']+)"],
       "depNameTemplate": "qdrant/qdrant",
       "datasourceTemplate": "docker"
     }

requirements.txt

@@ -1,9 +1,8 @@
-mcp==1.26.0
-fastmcp==3.4.2
-qdrant-client==1.18.0
-fastembed==0.8.0
-python-dotenv==1.2.2
-uvicorn==0.41.0
-starlette==1.2.1
-beautifulsoup4==4.15.0
-python-dateutil==2.9.0.post0
+fastmcp>=4,<5
+qdrant-client>=1,<2
+fastembed>=0.8.0,<1
+python-dotenv>=1,<2
+uvicorn>=0.34,<1
+starlette>=1.2,<2
+beautifulsoup4>=4,<5
+python-dateutil>=2,<3

src/indexer.py

@@ -22,26 +22,34 @@ from bs4 import BeautifulSoup
 # Load .env config
 load_dotenv()
 
-# Configuration
+# Configuration (validated lazily in main() so the module can be imported
+# and unit-tested without environment variables)
 MAILDIR_PATH = os.environ.get("MAILDIR_PATH", "")
 MAILDIR_FOLDERS = os.environ.get("MAILDIR_FOLDERS", "")
 QDRANT_URL = os.environ.get("QDRANT_URL", "")
 COLLECTION_NAME = os.environ.get("COLLECTION_NAME", "")
 
-if not MAILDIR_PATH:
-    raise ValueError("MAILDIR_PATH environment variable is required.")
-if not QDRANT_URL:
-    raise ValueError("QDRANT_URL environment variable is required.")
-if not COLLECTION_NAME:
-    raise ValueError("COLLECTION_NAME environment variable is required.")
-
+# Embedding model and batching. EMBEDDING_MODEL_NAME MUST stay in sync with the
+# one used by server.py: indexer and server have to embed with the same model,
+# otherwise the vectors stored in Qdrant are not comparable with query vectors.
 EMBEDDING_MODEL_NAME = os.environ.get("EMBEDDING_MODEL_NAME", "BAAI/bge-small-en-v1.5")
 BATCH_SIZE = int(os.environ.get("BATCH_SIZE", "100"))
 EMBEDDING_BATCH_SIZE = int(os.environ.get("EMBEDDING_BATCH_SIZE", "64"))
+
 METADATA_COLLECTION = "mcp_indexer_metadata"
 INCREMENTAL_DAYS = int(os.environ.get("INCREMENTAL_DAYS", "7"))
 FORCE_REINDEX = os.environ.get("FORCE_REINDEX", "").lower() in ("1", "true", "yes")
 
+
+def _validate_config():
+    """Raises if required environment variables are missing. Called from main()."""
+    if not MAILDIR_PATH:
+        raise ValueError("MAILDIR_PATH environment variable is required.")
+    if not QDRANT_URL:
+        raise ValueError("QDRANT_URL environment variable is required.")
+    if not COLLECTION_NAME:
+        raise ValueError("COLLECTION_NAME environment variable is required.")
+
 def decode_mime_words(s: str) -> str:
     """Decodes MIME encoded strings (e.g. subjects, filenames)."""
     if not s:
@@ -251,6 +259,8 @@ def main():
     Main ingestion function.
     Reads Maildir, extracts text, generates local embeddings, and pushes to Qdrant.
     """
+    _validate_config()
+
     print(f"Indexing emails from {MAILDIR_PATH} into {QDRANT_URL}...")
 
     if not os.path.exists(MAILDIR_PATH):

src/server.py

@@ -9,6 +9,7 @@ from typing import Any, Optional
 import qdrant_client as qdrant_pkg
 from dateutil import parser as date_parser
 from email.utils import parseaddr
+import uvicorn
 from dotenv import load_dotenv
 from starlette.requests import Request
 from starlette.responses import JSONResponse
@@ -36,6 +37,10 @@ COLLECTION_NAME = os.environ.get("COLLECTION_NAME", "")
 EMBEDDING_MODEL_NAME = os.environ.get("EMBEDDING_MODEL_NAME", "BAAI/bge-small-en-v1.5")
 DEFAULT_LIMIT = int(os.environ.get("SEARCH_LIMIT", "50"))
 
+# Per-request timeout (seconds) for Qdrant. The client default is 5s, which is
+# tight for a cold collection or a busy host: unset means keep that default.
+QDRANT_TIMEOUT = int(os.environ["QDRANT_TIMEOUT"]) if os.environ.get("QDRANT_TIMEOUT") else None
+
 if not QDRANT_URL:
     raise ValueError("QDRANT_URL environment variable is required.")
 if not COLLECTION_NAME:
@@ -60,8 +65,8 @@ def get_qdrant_client() -> QdrantClient:
     """Returns a singleton Qdrant client."""
     global _qdrant_client
     if _qdrant_client is None:
-        logger.info(f"Connecting to Qdrant at {QDRANT_URL}")
-        _qdrant_client = QdrantClient(url=QDRANT_URL)
+        logger.info(f"Connecting to Qdrant at {QDRANT_URL} (timeout={QDRANT_TIMEOUT})")
+        _qdrant_client = QdrantClient(url=QDRANT_URL, timeout=QDRANT_TIMEOUT)
     return _qdrant_client
 
 
@@ -340,6 +345,23 @@ def read_email(message_id: str):
         return {"error": f"read_email failed: {exc}"}
 
 
+# Streamable HTTP is the transport supported by current MCP clients (OpenCode,
+# Claude, ...). The legacy SSE transport is deprecated and is also a POST
+# target for clients that only speak Streamable HTTP, which answers 405.
+MCP_HOST = "0.0.0.0"
+MCP_PORT = 8000
+MCP_HTTP_PATH = "/mcp"
+
+
+def build_app():
+    """Builds the ASGI app serving the MCP endpoint over Streamable HTTP.
+
+    The MCP endpoint lives at MCP_HTTP_PATH; the custom route declared above
+    keeps serving GET /health for the Kubernetes probes.
+    """
+    return mcp.http_app(path=MCP_HTTP_PATH)
+
+
 if __name__ == "__main__":
     logger.info("Initializing models before starting server...")
     try:
@@ -348,6 +370,5 @@ if __name__ == "__main__":
     except Exception as e:
         logger.error(f"Failed to load models: {e}")
 
-    logger.info("Starting SSE server on 0.0.0.0:8000...")
-    # Start the MCP server using SSE (Server-Sent Events) over HTTP
-    mcp.run(transport="sse", host="0.0.0.0", port=8000)
+    logger.info(f"Starting Streamable HTTP server on {MCP_HOST}:{MCP_PORT}{MCP_HTTP_PATH}...")
+    uvicorn.run(build_app(), host=MCP_HOST, port=MCP_PORT)

tests/conftest.py

@@ -0,0 +1,15 @@
+"""Shared test configuration — sets env vars ONCE before any test module runs.
+
+The env must be consistent for the whole pytest session: server.py freezes
+COLLECTION_NAME/QDRANT_URL at import time, while the integration fixture
+reads os.environ at fixture time. If any test module mutates os.environ after
+that (test_server.py used to set COLLECTION_NAME='test'), the fixture creates
+a different collection than the one server functions query → 404.
+Keep all env wiring here so import order no longer matters.
+"""
+
+import os
+
+os.environ.setdefault("QDRANT_URL", "http://localhost:6333")
+os.environ.setdefault("COLLECTION_NAME", "test_mcp_maildir")
+os.environ.setdefault("EMBEDDING_MODEL_NAME", "BAAI/bge-small-en-v1.5")

tests/test_indexer.py

@@ -0,0 +1,254 @@
+"""Unit tests for mcp-maildir indexer parsing functions.
+
+Pure-function tests: no Qdrant, no embedding model, no network.
+A throwaway Maildir is built in tmp_path for get_recent_keys().
+"""
+
+import mailbox
+import os
+import time
+import uuid
+from datetime import datetime, timezone, timedelta
+from email.message import EmailMessage
+from email.utils import format_datetime
+
+import pytest
+
+from indexer import (
+    decode_mime_words,
+    extract_text_from_html,
+    normalize_email_address,
+    parse_email_message,
+    get_recent_keys,
+    METADATA_COLLECTION,
+    EMBEDDING_MODEL_NAME,
+    BATCH_SIZE,
+    EMBEDDING_BATCH_SIZE,
+)
+
+
+# ---------------------------------------------------------------------------
+# decode_mime_words
+# ---------------------------------------------------------------------------
+
+class TestDecodeMimeWords:
+    def test_empty_and_none(self):
+        assert decode_mime_words("") == ""
+        assert decode_mime_words(None) == ""
+
+    def test_plain_ascii(self):
+        assert decode_mime_words("Hello World") == "Hello World"
+
+    def test_encoded_word_utf8(self):
+        # =?utf-8?q?...?= encoded word
+        assert decode_mime_words("=?utf-8?q?Caf=C3=A9_au_lait?=") == "Café au lait"
+
+    def test_encoded_word_iso8859(self):
+        # decode_mime_words does not strip whitespace around the words
+        assert decode_mime_words("=?iso-8859-1?q?caf=E9?=") == "café"
+
+    def test_mixed_encoded_and_plain(self):
+        assert decode_mime_words("Re: =?utf-8?q?planning_2026?=") == "Re: planning 2026"
+
+
+# ---------------------------------------------------------------------------
+# extract_text_from_html
+# ---------------------------------------------------------------------------
+
+class TestExtractTextFromHtml:
+    def test_simple_paragraphs(self):
+        html = "<html><body><p>Hello</p><p>World</p></body></html>"
+        assert extract_text_from_html(html) == "Hello World"
+
+    def test_strips_tags_and_scripts(self):
+        html = "<div>Sign<span>ature</span><script>evil()</script>End</div>"
+        text = extract_text_from_html(html)
+        assert "evil()" not in text
+        # get_text uses separator=" ", so tags become whitespace
+        assert "Sign" in text and "ature" in text and "End" in text
+
+    def test_fallback_on_invalid_content(self):
+        # Garbage that would make the parser blow up should not raise
+        assert extract_text_from_html(None) is None
+
+
+# ---------------------------------------------------------------------------
+# parse_email_message — real mailbox.Message objects (no mocks)
+# ---------------------------------------------------------------------------
+
+def build_email(
+    subject="Hello",
+    body="This is the body.",
+    html=None,
+    attachments=None,
+    charset="utf-8",
+):
+    """Builds a real EmailMessage, optionally multipart with attachments."""
+    msg = EmailMessage()
+    msg["Subject"] = subject
+    msg["From"] = "Alice <alice@example.com>"
+    msg["To"] = "Bob <bob@example.com>"
+    msg["Message-ID"] = "<build-email@example.com>"
+    msg["Date"] = format_datetime(datetime(2026, 1, 15, 10, 0, 0, tzinfo=timezone.utc))
+
+    if html:
+        msg.set_content(body)
+        msg.add_alternative(html, subtype="html")
+    else:
+        msg.set_content(body, charset=charset)
+
+    for filename, content in (attachments or {}).items():
+        payload = content if isinstance(content, bytes) else content.encode()
+        msg.add_attachment(payload, maintype="application",
+                           subtype="octet-stream", filename=filename)
+    return msg
+
+
+def build_raw_email(raw_bytes: bytes):
+    """Parses raw email bytes (for exotic headers without EmailMessage helpers)."""
+    import email as email_mod
+    return email_mod.message_from_bytes(raw_bytes)
+
+
+class TestParseEmailMessage:
+    def test_plain_text_body(self):
+        msg = build_email(body="Line one.\nLine two.")
+        body, attachments = parse_email_message(msg)
+        assert "Line one." in body and "Line two." in body
+        assert attachments == []
+
+    def test_attachments_detected_and_excluded_from_body(self):
+        msg = build_email(
+            body="See attached.",
+            attachments={"report.pdf": b"%PDF-fake", "notes.txt": b"notes"},
+        )
+        body, attachments = parse_email_message(msg)
+        assert attachments == ["report.pdf", "notes.txt"]
+        assert "%PDF" not in body
+        assert "See attached." in body
+
+    def test_html_alternative_extracts_text(self):
+        msg = build_email(
+            body="Fallback plain text.",
+            html="<html><body><b>Bold</b> intro</body></html>",
+        )
+        body, _ = parse_email_message(msg)
+        assert "Bold" in body and "intro" in body
+
+    def test_unknown_charset_falls_back_not_crash(self):
+        # A payload claiming an unknown charset must not raise.
+        # Built from raw bytes: EmailMessage.set_content(charset=...) would
+        # reject the unknown encoding at build time, real mail does not.
+        raw = (
+            b"Subject: broken charset\n"
+            b"From: alice@example.com\n"
+            b"To: bob@example.com\n"
+            b"Content-Type: text/plain; charset=x-unknown-charset\n"
+            b"Content-Transfer-Encoding: 8bit\n\n"
+            b"body with broken charset\n"
+        )
+        msg = build_raw_email(raw)
+        body, attachments = parse_email_message(msg)
+        # Whatever the fallback, we must get a string body and no exception
+        assert isinstance(body, str)
+        assert attachments == []
+
+    def test_encoded_attachment_filename_decoded(self):
+        msg = build_email(
+            body="body",
+            attachments={},
+        )
+        # Add attachment with non-ascii filename via encoded word
+        msg.add_attachment(b"data", maintype="application", subtype="pdf",
+                           filename="café-rapport.pdf")
+        body, attachments = parse_email_message(msg)
+        assert attachments == ["café-rapport.pdf"]
+
+
+# ---------------------------------------------------------------------------
+# normalize_email_address (indexer copy — same contract as server.py)
+# ---------------------------------------------------------------------------
+
+class TestIndexerNormalizeEmailAddress:
+    def test_display_name(self):
+        assert normalize_email_address("John Doe <john@example.com>") == "john@example.com"
+
+    def test_case_and_whitespace(self):
+        assert normalize_email_address("  USER@Example.COM ") == "user@example.com"
+
+    def test_empty(self):
+        assert normalize_email_address("") == ""
+        assert normalize_email_address(None) == ""
+
+
+# ---------------------------------------------------------------------------
+# get_recent_keys — real Maildir on disk (tmp_path), mtime-driven
+# ---------------------------------------------------------------------------
+
+def make_maildir(root):
+    """Opens a Maildir at root — pre-creates cur/new/tmp because mailbox.Maildir
+    (Python 3.11) does not create them when adding a message."""
+    for sub in ("cur", "new", "tmp"):
+        os.makedirs(os.path.join(str(root), sub), exist_ok=True)
+    return mailbox.Maildir(str(root), create=False)
+
+
+def write_maildir_message(maildir: mailbox.Maildir, msg: EmailMessage):
+    """Adds a message and returns its key."""
+    return maildir.add(msg)
+
+
+class TestGetRecentKeys:
+    def test_recent_file_selected(self, tmp_path):
+        md = make_maildir(tmp_path)
+        msg = build_email()
+        md.add(msg)
+        md.flush()
+        # mtime is now → within the window
+        keys = get_recent_keys(md, days=7)
+        assert len(keys) == 1
+
+    def test_old_file_excluded(self, tmp_path):
+        md = make_maildir(tmp_path)
+        md.add(build_email())
+        md.flush()
+        # Age every file beyond the cutoff
+        old = time.time() - 30 * 86400
+        for path in tmp_path.rglob("*.??*"):
+            if path.is_file():
+                os.utime(path, (old, old))
+        keys = get_recent_keys(md, days=7)
+        assert len(keys) == 0
+
+    def test_key_is_suffixless_filename(self, tmp_path):
+        """Maildir keys strip the ':2,S' info suffix — get_recent_keys must match."""
+        md = make_maildir(tmp_path)
+        key = md.add(build_email())
+        md.flush()
+        keys = get_recent_keys(md, days=7)
+        assert keys  # non-empty set of keys for fresh files
+        assert key.split(":")[0] in keys
+        for k in keys:
+            assert ":" not in k
+
+
+# ---------------------------------------------------------------------------
+# Regression: module-level constants consumed by main()
+# ---------------------------------------------------------------------------
+
+
+def test_indexer_module_constants_are_defined():
+    """Regression (e32806a): the "make indexer importable without env" refactor
+    dropped these three module-level definitions while main() kept using them,
+    so every indexer run died with NameError before touching Qdrant."""
+    assert isinstance(EMBEDDING_MODEL_NAME, str) and EMBEDDING_MODEL_NAME
+    assert isinstance(BATCH_SIZE, int) and BATCH_SIZE > 0
+    assert isinstance(EMBEDDING_BATCH_SIZE, int) and EMBEDDING_BATCH_SIZE > 0
+
+
+def test_embedding_model_is_the_same_as_the_server_one():
+    """Indexer and server must embed with the same model, otherwise the vectors
+    stored by the indexer are not comparable with the query vectors."""
+    from server import EMBEDDING_MODEL_NAME as server_embedding_model
+
+    assert EMBEDDING_MODEL_NAME == server_embedding_model

tests/test_integration.py

@@ -0,0 +1,217 @@
+"""Integration tests for mcp-maildir with a real Qdrant instance.
+
+Env vars (QDRANT_URL, COLLECTION_NAME, EMBEDDING_MODEL_NAME) are set in
+tests/conftest.py — don't set them here, they must match server.py's
+import-time snapshot for every module in the session.
+"""
+
+import os
+import uuid
+import pytest
+
+from server import get_qdrant_client, get_embedding_model, search_emails, read_email
+from qdrant_client.http import models
+
+# Requires a live Qdrant on localhost:6333 (see pytest.ini: deselected by
+# default; run with `pytest -m integration`, nightly CI does exactly that).
+pytestmark = pytest.mark.integration
+
+
+TEST_EMAILS = [
+    {
+        "message_id": "<test-001@example.com>",
+        "date": "2026-01-15T10:00:00",
+        "sender": "alice@example.com",
+        "sender_raw": "Alice <alice@example.com>",
+        "receiver": "bob@example.com",
+        "receiver_raw": "Bob <bob@example.com>",
+        "subject": "Hello World",
+        "body_text": "This is a test email about Python programming and vector databases.",
+        "attachments": [],
+    },
+    {
+        "message_id": "<test-002@example.com>",
+        "date": "2026-01-16T14:30:00",
+        "sender": "carol@other.com",
+        "sender_raw": "Carol <carol@other.com>",
+        "receiver": "alice@example.com",
+        "receiver_raw": "Alice <alice@example.com>",
+        "subject": "Qdrant setup help",
+        "body_text": "Can you help me set up Qdrant for semantic email search?",
+        "attachments": ["screenshot.png"],
+    },
+    {
+        "message_id": "<test-003@example.com>",
+        "date": "2026-02-01T09:00:00",
+        "sender": "bob@example.com",
+        "sender_raw": "Bob <bob@example.com>",
+        "receiver": "alice@example.com",
+        "receiver_raw": "Alice <alice@example.com>",
+        "subject": "Meeting next week",
+        "body_text": "Let's discuss the project roadmap and data pipeline.",
+        "attachments": [],
+    },
+]
+
+
+@pytest.fixture(scope="module")
+def qdrant_setup():
+    """Create collection and index test emails once per test run."""
+    client = get_qdrant_client()
+    model = get_embedding_model()
+    collection_name = os.environ["COLLECTION_NAME"]
+
+    # Debug instrumentalisation — truth about which server we are talking to
+    # and what it holds (CI 404 diagnosis).
+    import logging
+    dbg = logging.getLogger("integration.debug")
+    try:
+        dbg.warning("qdrant client url: %s", client.http._client.base_url)
+    except Exception:
+        dbg.warning("qdrant client url: <introspection failed>")
+    server_info = None
+    try:
+        server_info = client.get_collections()
+        dbg.warning("collections BEFORE: %s", [c.name for c in server_info.collections])
+    except Exception as e:
+        dbg.warning("get_collections FAILED: %s", e)
+
+    # Clean up from previous runs
+    try:
+        client.delete_collection(collection_name)
+    except Exception:
+        pass
+
+    # Create collection
+    probe = next(iter(model.embed(["dimension_probe"])))
+    client.create_collection(
+        collection_name=collection_name,
+        vectors_config=models.VectorParams(
+            size=len(probe), distance=models.Distance.COSINE
+        ),
+    )
+    # Assert the collection is actually visible right after creation
+    names_after = [c.name for c in client.get_collections().collections]
+    dbg.warning("collections AFTER create: %s", names_after)
+    if collection_name not in names_after:
+        raise RuntimeError(
+            f"Fixture created collection {collection_name} but it is not in "
+            f"get_collections(): {names_after}"
+        )
+
+    # Index test emails
+    for email in TEST_EMAILS:
+        vector_text = (
+            f"Date: {email['date']}\n"
+            f"From: {email['sender']}\n"
+            f"To: {email['receiver']}\n"
+            f"Subject: {email['subject']}\n\n"
+            f"{email['body_text']}\n\n"
+            f"Attachments: {', '.join(email['attachments']) if email['attachments'] else 'None'}"
+        )
+        vector = list(model.embed([vector_text]))[0].tolist()
+
+        # Create payload indexes on first upsert
+        client.create_payload_index(
+            collection_name=collection_name,
+            field_name="sender",
+            field_schema=models.PayloadSchemaType.KEYWORD,
+        )
+        client.create_payload_index(
+            collection_name=collection_name,
+            field_name="receiver",
+            field_schema=models.PayloadSchemaType.KEYWORD,
+        )
+        client.create_payload_index(
+            collection_name=collection_name,
+            field_name="date",
+            field_schema=models.PayloadSchemaType.DATETIME,
+        )
+
+        client.upsert(
+            collection_name=collection_name,
+            points=[
+                models.PointStruct(
+                    id=str(uuid.uuid5(uuid.NAMESPACE_OID, email["message_id"])),
+                    vector=vector,
+                    payload={
+                        "message_id": email["message_id"],
+                        "date": email["date"],
+                        "sender": email["sender"],
+                        "sender_raw": email["sender_raw"],
+                        "receiver": email["receiver"],
+                        "receiver_raw": email["receiver_raw"],
+                        "subject": email["subject"],
+                        "body_text": email["body_text"],
+                        "attachments": email["attachments"],
+                    },
+                )
+            ],
+        )
+
+    yield client
+
+    # Cleanup
+    try:
+        client.delete_collection(collection_name)
+    except Exception:
+        pass
+
+
+class TestSearchEmails:
+    def test_search_by_content(self, qdrant_setup):
+        """Semantic search returns the most relevant email first.
+
+        Searching for 'Python programming' should match email 001
+        which discusses Python and vector databases.
+        """
+        result = search_emails(query="Python programming")
+        assert result["count"] >= 1
+        assert "results" in result
+        # The top result should be email 001 (most semantically relevant)
+        messages = [r["message_id"] for r in result["results"]]
+        assert "<test-001@example.com>" in messages
+
+    def test_search_with_participant_filter(self, qdrant_setup):
+        """Search emails sent by alice."""
+        result = search_emails(query="help", participant="alice@example.com")
+        assert result["count"] >= 1
+        messages = [r["message_id"] for r in result["results"]]
+        assert "<test-001@example.com>" in messages
+
+    def test_search_with_date_filter(self, qdrant_setup):
+        """Search emails after a specific date."""
+        result = search_emails(query="meeting", start_date="2026-02-01")
+        assert result["count"] >= 1
+        for r in result["results"]:
+            date = r.get("date", "")
+            assert date >= "2026-02-01"
+
+    def test_search_no_results_by_date(self, qdrant_setup):
+        """Search with a filter that matches no emails returns empty results.
+
+        With semantic (vector) search, any text query always has nearest
+        neighbors, so we use a date filter that matches nothing instead.
+        """
+        result = search_emails(
+            query="anything",
+            start_date="2099-01-01",
+            end_date="2099-12-31",
+        )
+        assert result["count"] == 0
+        assert result["results"] == []
+
+
+class TestReadEmail:
+    def test_read_existing_email(self, qdrant_setup):
+        """Read an email by its message_id."""
+        result = read_email(message_id="<test-001@example.com>")
+        assert "error" not in result
+        assert result["message_id"] == "<test-001@example.com>"
+        assert "This is a test email" in result.get("body_text", "")
+
+    def test_read_nonexistent_email(self, qdrant_setup):
+        """Read an email that doesn't exist."""
+        result = read_email(message_id="<nonexistent@ghost.com>")
+        assert "error" in result
+        assert "No email found" in result["error"]

tests/test_server.py

@@ -0,0 +1,163 @@
+"""Unit tests for mcp-maildir server pure functions.
+
+Env vars are set in tests/conftest.py (shared session-wide) — see the
+conftest docstring for why test modules must not touch os.environ.
+"""
+
+from server import (
+    normalize_email_address,
+    payload_matches_participant,
+    format_search_result,
+    build_filter,
+)
+
+
+class TestNormalizeEmailAddress:
+    def test_empty_value(self):
+        assert normalize_email_address("") == ""
+        assert normalize_email_address(None) == ""
+
+    def test_simple_email(self):
+        assert normalize_email_address("user@example.com") == "user@example.com"
+
+    def test_display_name_with_email(self):
+        assert normalize_email_address("John Doe <john@example.com>") == "john@example.com"
+
+    def test_whitespace_and_case(self):
+        assert normalize_email_address("  USER@Example.COM  ") == "user@example.com"
+
+    def test_invalid_email_fallback(self):
+        result = normalize_email_address("not-an-email")
+        # Returns stripped lowercase version of the input
+        assert result == "not-an-email"
+
+
+class TestPayloadMatchesParticipant:
+    def test_sender_match_normalized(self):
+        payload = {"sender": "alice@example.com"}
+        assert payload_matches_participant(payload, "alice@example.com") is True
+
+    def test_receiver_match_normalized(self):
+        payload = {"receiver": "bob@example.com"}
+        assert payload_matches_participant(payload, "bob@example.com") is True
+
+    def test_sender_raw_match(self):
+        payload = {"sender_raw": "alice@other.com"}
+        assert payload_matches_participant(payload, "alice@other.com") is True
+
+    def test_no_match(self):
+        payload = {"sender": "alice@example.com", "receiver": "bob@example.com"}
+        assert payload_matches_participant(payload, "carol@example.com") is False
+
+    def test_display_name_in_sender(self):
+        payload = {"sender": "Alice <alice@example.com>"}
+        assert payload_matches_participant(payload, "alice@example.com") is True
+
+    def test_display_name_in_receiver(self):
+        payload = {"receiver": "Bob Smith <bob@example.com>"}
+        assert payload_matches_participant(payload, "bob@example.com") is True
+
+    def test_empty_payload(self):
+        assert payload_matches_participant({}, "someone@example.com") is False
+
+    def test_case_insensitive(self):
+        payload = {"sender": "ALICE@EXAMPLE.COM"}
+        assert payload_matches_participant(payload, "alice@example.com") is True
+
+
+class TestFormatSearchResult:
+    def test_basic_formatting(self):
+        class MockPoint:
+            payload = {
+                "message_id": "<abc@def>",
+                "date": "2026-01-15T10:00:00",
+                "sender": "alice@example.com",
+                "receiver": "bob@example.com",
+                "subject": "Hello",
+                "attachments": ["file.pdf"],
+            }
+            score = 0.95
+
+        result = format_search_result(MockPoint())
+        assert result["message_id"] == "<abc@def>"
+        assert result["date"] == "2026-01-15T10:00:00"
+        assert result["sender"] == "alice@example.com"
+        assert result["receiver"] == "bob@example.com"
+        assert result["subject"] == "Hello"
+        assert result["attachments"] == ["file.pdf"]
+        assert result["score"] == 0.95
+
+    def test_empty_payload(self):
+        class MockPoint:
+            payload = None
+            score = None
+
+        result = format_search_result(MockPoint())
+        assert result["message_id"] is None
+        assert result["score"] is None
+        assert result["attachments"] == []
+
+    def test_missing_fields(self):
+        class MockPoint:
+            payload = {"message_id": "<123>"}
+            score = 0.5
+
+        result = format_search_result(MockPoint())
+        assert result["message_id"] == "<123>"
+        assert result["date"] is None
+        assert result["sender"] is None
+        assert result["receiver"] is None
+        assert result["subject"] is None
+        assert result["attachments"] == []
+
+
+class TestBuildFilter:
+    def test_no_filters_returns_none(self):
+        assert build_filter(None, None, None) is None
+
+    def test_empty_strings_return_none(self):
+        assert build_filter("", "", "") is None
+
+    def test_participant_filter_is_should_clause_on_sender_and_receiver(self):
+        f = build_filter("alice@example.com", None, None)
+        assert f is not None
+        # The date conditions list must be absent and only the participant filter present
+        assert len(f.must) == 1
+        participant = f.must[0]
+        keys = [c.key for c in participant.should]
+        assert keys == ["sender", "receiver"]
+        assert all(c.match.value == "alice@example.com" for c in participant.should)
+
+    def test_participant_normalized_before_match(self):
+        f = build_filter("Alice <Alice@Example.COM>", None, None)
+        should = f.must[0].should
+        assert all(c.match.value == "alice@example.com" for c in should)
+
+    def test_date_range_only(self):
+        f = build_filter(None, "2026-01-01", "2026-06-30")
+        assert len(f.must) == 1
+        cond = f.must[0]
+        assert cond.key == "date"
+        assert cond.range.gte is not None
+        assert cond.range.lte is not None
+
+    def test_start_date_only(self):
+        f = build_filter(None, "2026-03-15", None)
+        cond = f.must[0]
+        assert cond.range.gte is not None
+        assert cond.range.lte is None
+
+    def test_end_date_only(self):
+        f = build_filter(None, None, "2026-03-15")
+        cond = f.must[0]
+        assert cond.range.gte is None
+        assert cond.range.lte is not None
+
+    def test_combined_participant_and_date(self):
+        f = build_filter("bob@example.org", "2026-01-01", "2026-12-31")
+        assert len(f.must) == 2
+        # One is the participant should-filter, the other the date range
+        kinds = sorted(
+            "participant" if getattr(c, "should", None) else "date" for c in f.must
+        )
+        assert kinds == ["date", "participant"]

tests/test_transport.py

@@ -0,0 +1,27 @@
+"""Transport-level tests for the mcp-maildir ASGI app.
+
+Current MCP clients (OpenCode, Claude, ...) only speak Streamable HTTP: they
+POST JSON-RPC to the configured URL. Serving the legacy SSE transport alone
+makes those clients fail with `405 Method Not Allowed`, so the app built by
+`server.build_app()` must expose the MCP endpoint at /mcp.
+
+Env vars are set in tests/conftest.py (shared session-wide).
+"""
+
+from server import build_app, MCP_HTTP_PATH
+
+
+def app_paths() -> set:
+    return {getattr(route, "path", None) for route in build_app().routes}
+
+
+class TestTransport:
+    def test_mcp_endpoint_is_streamable_http(self):
+        assert MCP_HTTP_PATH == "/mcp"
+        assert MCP_HTTP_PATH in app_paths()
+
+    def test_health_endpoint_is_exposed_for_probes(self):
+        assert "/health" in app_paths()
+
+    def test_legacy_sse_endpoint_is_gone(self):
+        assert "/sse" not in app_paths()