ci: Add MCP server tests workflow (#1506)

* ci: Add MCP server tests workflow

Add dedicated CI workflow for testing the MCP (Model Context Protocol)
server implementation. This workflow:

- Runs on changes to MCP-related files
- Verifies MCP module loads correctly
- Tests discovery tools (list_strategies, list_search_engines, get_configuration)
- Runs full MCP unit test suite with mocks
- Tests MCP strategy (ReAct pattern) implementation
- Verifies server startup behavior

The tests use mocks to avoid requiring an LLM backend, making them
fast and reliable in CI environments.

Prepares CI infrastructure for PR #1366 (MCP server feature).

* refactor: Move MCP smoke tests to external script

Address review feedback from djpetti:
- Extract MCP module loading test to scripts/mcp_smoke_test.sh
- Extract MCP server startup test to the same script
- Update workflow to call the external script
- Add script path to workflow triggers

* ci: skip MCP tests when server module not implemented

The MCP server module (src/local_deep_research/mcp/server.py) is in a
separate feature branch. This change makes the MCP test workflow skip
gracefully when the module doesn't exist, with a clear notice.

Tests will automatically run once the MCP feature branch is merged.

.github/workflows/mcp-tests.yml

@@ -0,0 +1,124 @@
+name: MCP Server Tests
+
+on:
+  push:
+    branches: [ main, dev ]
+    paths:
+      - 'src/local_deep_research/mcp/**'
+      - 'src/local_deep_research/advanced_search_system/strategies/mcp_strategy.py'
+      - 'tests/mcp/**'
+      - 'scripts/mcp_smoke_test.sh'
+      - '.github/workflows/mcp-tests.yml'
+  pull_request:
+    branches: [ main, dev ]
+    paths:
+      - 'src/local_deep_research/mcp/**'
+      - 'src/local_deep_research/advanced_search_system/strategies/mcp_strategy.py'
+      - 'tests/mcp/**'
+      - 'scripts/mcp_smoke_test.sh'
+      - '.github/workflows/mcp-tests.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  mcp-tests:
+    name: MCP Server Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@df199fb7be9f65074067a9eb93f12bb4c5547cf2 # v2.13.3
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install pip==25.0
+          pip install pdm==2.26.2
+          pdm install --dev --no-editable
+          # Install MCP optional dependency
+          pdm run pip install "mcp[cli]>=1.2.0"
+
+      - name: Check if MCP server module exists
+        id: check-mcp
+        run: |
+          if [ -f "src/local_deep_research/mcp/server.py" ]; then
+            echo "mcp_exists=true" >> "$GITHUB_OUTPUT"
+            echo "MCP server module found, will run tests"
+          else
+            echo "mcp_exists=false" >> "$GITHUB_OUTPUT"
+            echo "MCP server module not found (feature not yet merged), skipping tests"
+          fi
+
+      - name: Run MCP smoke tests
+        if: steps.check-mcp.outputs.mcp_exists == 'true'
+        run: pdm run bash scripts/mcp_smoke_test.sh
+
+      - name: Run MCP unit tests
+        if: steps.check-mcp.outputs.mcp_exists == 'true'
+        run: |
+          pdm run pytest tests/mcp/ -v --tb=short -n auto \
+            --ignore=tests/mcp/test_mcp_strategy.py
+        env:
+          LDR_USE_FALLBACK_LLM: "true"
+          LDR_TESTING_WITH_MOCKS: "true"
+
+      - name: Run MCP strategy tests
+        if: steps.check-mcp.outputs.mcp_exists == 'true'
+        run: |
+          pdm run pytest tests/mcp/test_mcp_strategy.py -v --tb=short -n auto
+        env:
+          LDR_USE_FALLBACK_LLM: "true"
+          LDR_TESTING_WITH_MOCKS: "true"
+
+      - name: Skip notice
+        if: steps.check-mcp.outputs.mcp_exists != 'true'
+        run: |
+          echo "::notice::MCP server module not yet implemented. Tests will run once feature/mcp-server is merged."
+
+      - name: Generate test summary
+        if: always()
+        env:
+          MCP_EXISTS: ${{ steps.check-mcp.outputs.mcp_exists }}
+        run: |
+          {
+            echo "## MCP Server Test Summary"
+            echo ""
+            if [ "$MCP_EXISTS" != "true" ]; then
+              echo "### ⏭️ Tests Skipped"
+              echo ""
+              echo "MCP server module (\`src/local_deep_research/mcp/server.py\`) not yet implemented."
+              echo "Tests will run automatically once the MCP feature branch is merged."
+            else
+              echo "### What was tested:"
+              echo "- 🔌 MCP server module loading"
+              echo "- 🔧 Discovery tools (list_strategies, list_search_engines, get_configuration)"
+              echo "- 🧪 Unit tests for all MCP tools"
+              echo "- 🤖 MCP strategy (ReAct pattern) tests"
+              echo "- 🚀 Server startup verification"
+              echo ""
+              echo "### MCP Tools Tested:"
+              echo "| Tool | Description |"
+              echo "|------|-------------|"
+              echo "| \`quick_research\` | Fast research summary (1-5 min) |"
+              echo "| \`detailed_research\` | Comprehensive analysis (5-15 min) |"
+              echo "| \`generate_report\` | Full markdown report (10-30 min) |"
+              echo "| \`analyze_documents\` | Search local collections |"
+              echo "| \`list_search_engines\` | List available search engines |"
+              echo "| \`list_strategies\` | List research strategies |"
+              echo "| \`get_configuration\` | Get current config |"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"

scripts/mcp_smoke_test.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# MCP Server Smoke Test
+# Verifies that the MCP server module loads correctly and basic tools work
+
+set -e
+
+echo "=== MCP Server Smoke Test ==="
+echo ""
+
+# Test 1: Verify MCP module loads
+echo "1. Testing MCP module loading..."
+python -c "
+from local_deep_research.mcp.server import mcp, list_strategies, get_configuration
+print('   MCP server module loaded successfully')
+print(f'   Server name: {mcp.name}')
+
+# Test discovery tools
+result = list_strategies()
+assert result['status'] == 'success', f'list_strategies failed: {result}'
+print(f'   list_strategies: {len(result[\"strategies\"])} strategies available')
+
+config = get_configuration()
+assert config['status'] == 'success', f'get_configuration failed: {config}'
+print('   get_configuration: works correctly')
+"
+echo "   PASSED"
+echo ""
+
+# Test 2: Verify MCP server startup
+echo "2. Testing MCP server startup..."
+timeout 5 python -m local_deep_research.mcp 2>&1 || {
+    exit_code=$?
+    if [ $exit_code -eq 124 ]; then
+        echo "   Server started correctly (timed out waiting for STDIO input as expected)"
+        echo "   PASSED"
+    else
+        echo "   FAILED: MCP server failed to start with exit code $exit_code"
+        exit 1
+    fi
+}
+
+echo ""
+echo "=== All MCP smoke tests passed ==="