Merge pull request 'chore(deps): update dependency python to 3.14' (#14) from renovate/python-3.x into main

Reviewed-on: #14

.gitea/workflows/docker-build.yaml

@@ -9,37 +9,78 @@ on:
     - cron: '0 0 * * *'
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
-        uses: actions/checkout@v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Start Qdrant
+        run: |
+          docker run -d --name qdrant \
+            --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
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt pytest
+      - name: Run integration tests
+        run: pytest tests/test_integration.py -v
+        env:
+          QDRANT_URL: http://localhost:6333
+          COLLECTION_NAME: test_mcp_maildir
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, integration-test]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4
 
       - name: Login to Docker Hub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@v4
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Docker metadata
         id: meta
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # 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@v7
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7
         with:
-          context: pkg
+          context: .
           file: pkg/Dockerfile
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}

pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+testpaths = tests
+pythonpath = src

renovate.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "customManagers": [
+    {
+      "customType": "regex",
+      "description": "Track qdrant/qdrant Docker image from docker-compose.yml (native manager missed it)",
+      "managerFilePatterns": ["/^docker-compose\\.ya?ml$/"],
+      "matchStrings": ["image:\\s*(?:docker\\.io/)?qdrant/qdrant:(?<currentValue>[^\\s]+)"],
+      "depNameTemplate": "qdrant/qdrant",
+      "datasourceTemplate": "docker"
+    }
+  ]
+}

requirements.txt

@@ -1,9 +1,9 @@
-mcp
+mcp==1.27.2
-fastmcp
+fastmcp==3.4.2
-qdrant-client
+qdrant-client==1.18.0
-fastembed
+fastembed==0.8.0
-python-dotenv
+python-dotenv==1.2.2
-uvicorn
+uvicorn==0.49.0
-starlette
+starlette==1.3.1
-beautifulsoup4
+beautifulsoup4==4.15.0
-python-dateutil
+python-dateutil==2.9.0.post0

tests/test_integration.py

@@ -0,0 +1,189 @@
+"""Integration tests for mcp-maildir with a real Qdrant instance."""
+
+import os
+import uuid
+import pytest
+
+os.environ["QDRANT_URL"] = "http://localhost:6333"
+os.environ["COLLECTION_NAME"] = "test_mcp_maildir"
+os.environ["EMBEDDING_MODEL_NAME"] = "BAAI/bge-small-en-v1.5"
+
+from server import get_qdrant_client, get_embedding_model, search_emails, read_email
+from qdrant_client.http import models
+
+
+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"]
+
+    # 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
+        ),
+    )
+
+    # 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,110 @@
+"""Unit tests for mcp-maildir server pure functions."""
+
+import os
+os.environ["QDRANT_URL"] = "http://localhost:6333"
+os.environ["COLLECTION_NAME"] = "test"
+
+from server import (
+    normalize_email_address,
+    payload_matches_participant,
+    format_search_result,
+)
+
+
+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"] == []