RFC: Plugin Extension System — runtime intelligence, hosted MCP, and plugin ecosystem

.env.example

@@ -34,3 +34,21 @@ PYTHONDONTWRITEBYTECODE=1
 
 # Optional: Database selection
 # DATABASE_TYPE=falkordb  # or falkordb-remote or neo4j
+
+# ── Plugin Configuration ───────────────────────────────────────────────────
+# Required when using docker-compose.plugins.yml or docker-compose.dev.yml
+
+# Your ingress domain (used by Traefik labels on plugin services)
+# DOMAIN=localhost
+
+# OTEL Plugin — span receiver and processor
+# OTEL_RECEIVER_PORT=5317
+# OTEL_FILTER_ROUTES=/health,/metrics,/ping,/favicon.ico
+
+# Xdebug Plugin — DBGp TCP listener (dev only)
+# XDEBUG_LISTEN_HOST=0.0.0.0
+# XDEBUG_LISTEN_PORT=9003
+# XDEBUG_DEDUP_CACHE_SIZE=10000
+
+# Log level for plugin containers (DEBUG, INFO, WARNING, ERROR)
+# LOG_LEVEL=INFO

.github/services.json

@@ -0,0 +1,34 @@
+[
+  {
+    "name": "cgc-core",
+    "path": ".",
+    "dockerfile": "Dockerfile",
+    "image": "cgc-core",
+    "health_check": "version",
+    "description": "CodeGraphContext MCP server core"
+  },
+  {
+    "name": "cgc-plugin-otel",
+    "path": "plugins/cgc-plugin-otel",
+    "dockerfile": "Dockerfile",
+    "image": "cgc-plugin-otel",
+    "health_check": "grpc_ping",
+    "description": "OpenTelemetry span receiver and graph writer"
+  },
+  {
+    "name": "cgc-plugin-xdebug",
+    "path": "plugins/cgc-plugin-xdebug",
+    "dockerfile": "Dockerfile",
+    "image": "cgc-plugin-xdebug",
+    "health_check": "tcp_connect",
+    "description": "Xdebug DBGp call-stack listener"
+  },
+  {
+    "name": "cgc-mcp",
+    "path": ".",
+    "dockerfile": "Dockerfile.mcp",
+    "image": "cgc-mcp",
+    "health_check": "http_get",
+    "description": "CGC hosted MCP server — HTTP transport with bundled plugins"
+  }
+]

.github/workflows/build.yml

@@ -15,6 +15,7 @@ jobs:
     name: Build on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
         include:
@@ -48,20 +49,17 @@ jobs:
         run: |
           pyinstaller cgc.spec --clean
 
-      - name: Build with PyInstaller (Linux - Manylinux)
+      - name: Install dependencies (Linux)
         if: runner.os == 'Linux'
         run: |
-          docker run --rm \
-            -v ${{ github.workspace }}:/src \
-            quay.io/pypa/manylinux2014_x86_64 \
-            /bin/bash -c "
-              set -e
-              cd /src
-              /opt/python/cp312-cp312/bin/python -m pip install --upgrade pip
-              /opt/python/cp312-cp312/bin/pip install . pyinstaller
-              /opt/python/cp312-cp312/bin/pyinstaller cgc.spec --clean
-            "
-          sudo chown -R $USER:$USER dist build
+          python -m pip install --upgrade pip
+          pip install .
+          pip install pyinstaller
+
+      - name: Build with PyInstaller (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          pyinstaller cgc.spec --clean
 
       - name: Rename artifact (Linux/Mac)
         if: runner.os != 'Windows'

.github/workflows/e2e-tests.yml

@@ -10,14 +10,26 @@ jobs:
   test:
     runs-on: ubuntu-latest
 
+    services:
+      falkordb:
+        image: falkordb/falkordb:latest
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
     steps:
     - name: Check out code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.12'
+        cache: 'pip'
 
     - name: Install dependencies
       run: |
@@ -26,6 +38,10 @@ jobs:
         pip install pytest
 
     - name: Run end-to-end tests
+      env:
+        FALKORDB_HOST: localhost
+        FALKORDB_PORT: 6379
+        DATABASE_TYPE: falkordb-remote
       run: |
         chmod +x tests/run_tests.sh
         ./tests/run_tests.sh e2e

.github/workflows/macos.yml

@@ -19,9 +19,10 @@ jobs:
           python-version: "3.12"
 
       - name: Install system deps
+        continue-on-error: true
         run: |
           brew update
-          brew install ripgrep || true
+          brew install ripgrep
 
       - name: Install CodeGraphContext
         run: |
@@ -35,12 +36,14 @@ jobs:
           df -h
 
       - name: Run index (verbose)
+        continue-on-error: true
         run: |
-          cgc index -f --debug || true
+          cgc index -f --debug
 
       - name: Try find
+        continue-on-error: true
         run: |
-          cgc find content "def" --debug || true
+          cgc find content "def" --debug
 
       - name: Upload logs
         if: always()

.github/workflows/plugin-publish.yml

@@ -0,0 +1,123 @@
+name: Build and Publish Plugin Images
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_PREFIX: ${{ github.repository_owner }}
+
+jobs:
+  # ── Read the service matrix from services.json ──────────────────────────
+  setup:
+    name: Load service matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.load.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Load services.json into matrix
+        id: load
+        run: |
+          # Filter to plugin services only (skip cgc-core — handled by docker-publish.yml)
+          MATRIX=$(cat .github/services.json | jq -c '[.[] | select(.name != "cgc-core")]')
+          echo "matrix=${MATRIX}" >> "$GITHUB_OUTPUT"
+
+  # ── Build, smoke-test, and optionally push each plugin image ────────────
+  build-plugins:
+    name: Build ${{ matrix.name }}
+    needs: setup
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      matrix:
+        include: ${{ fromJson(needs.setup.outputs.matrix) }}
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}/${{ matrix.image }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') }}
+            type=ref,event=pr
+            type=sha,prefix=sha-
+          labels: |
+            org.opencontainers.image.title=${{ matrix.name }}
+            org.opencontainers.image.description=${{ matrix.description }}
+            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
+
+      - name: Build image (load locally for smoke test)
+        id: build-local
+        uses: docker/build-push-action@v5
+        with:
+          context: ${{ matrix.path }}
+          file: ${{ matrix.path }}/${{ matrix.dockerfile }}
+          push: false
+          load: true
+          tags: smoke-test/${{ matrix.image }}:ci
+          cache-from: type=gha,scope=${{ matrix.name }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.name }}
+
+      - name: Smoke test — gRPC import
+        if: matrix.health_check == 'grpc_ping'
+        run: docker run --rm smoke-test/${{ matrix.image }}:ci python -c "import grpc; print('gRPC OK')"
+
+      - name: Smoke test — socket
+        if: matrix.health_check == 'tcp_connect'
+        run: docker run --rm smoke-test/${{ matrix.image }}:ci python -c "import socket; socket.socket(); print('socket OK')"
+
+      - name: Push image to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/build-push-action@v5
+        with:
+          context: ${{ matrix.path }}
+          file: ${{ matrix.path }}/${{ matrix.dockerfile }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha,scope=${{ matrix.name }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.name }}
+          platforms: linux/amd64,linux/arm64
+
+  # ── Summary ──────────────────────────────────────────────────────────────
+  build-summary:
+    name: Plugin build summary
+    needs: build-plugins
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Report overall status
+        run: |
+          if [ "${{ needs.build-plugins.result }}" = "success" ]; then
+            echo "✅ All plugin images built successfully."
+          else
+            echo "⚠️  One or more plugin images failed. Check individual job logs."
+            exit 1
+          fi

.github/workflows/test-plugins.yml

@@ -0,0 +1,84 @@
+name: Plugin Tests
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'plugins/**'
+      - 'src/codegraphcontext/plugin_registry.py'
+      - 'tests/unit/plugin/**'
+      - 'tests/integration/plugin/**'
+  push:
+    branches: [main]
+    paths:
+      - 'plugins/**'
+      - 'src/codegraphcontext/plugin_registry.py'
+  workflow_dispatch:
+
+jobs:
+  plugin-unit-tests:
+    name: Plugin unit + integration tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Install core CGC (no extras) and dev dependencies
+        run: |
+          pip install --no-cache-dir packaging pytest pytest-mock
+          pip install --no-cache-dir -e ".[dev]"
+
+      - name: Install stub plugin (editable)
+        run: pip install --no-cache-dir -e plugins/cgc-plugin-stub
+
+      - name: Run plugin unit tests
+        env:
+          PYTHONPATH: src
+        run: pytest tests/unit/plugin/ -v --tb=short
+
+      - name: Run plugin integration tests
+        env:
+          PYTHONPATH: src
+        run: pytest tests/integration/plugin/ -v --tb=short
+
+  plugin-import-check:
+    name: Verify plugin packages import cleanly
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        plugin: [cgc-plugin-stub, cgc-plugin-otel, cgc-plugin-xdebug]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install plugin
+        run: |
+          pip install --no-cache-dir typer neo4j packaging || true
+          pip install --no-cache-dir -e plugins/${{ matrix.plugin }} || true
+
+      - name: Check plugin PLUGIN_METADATA
+        env:
+          PYTHONPATH: src
+        run: |
+          PLUGIN_MOD=$(echo "${{ matrix.plugin }}" | tr '-' '_')
+          python -c "
+          import importlib
+          mod = importlib.import_module('${PLUGIN_MOD}')
+          meta = getattr(mod, 'PLUGIN_METADATA', None)
+          assert meta is not None, 'PLUGIN_METADATA missing'
+          for field in ('name', 'version', 'cgc_version_constraint', 'description'):
+              assert field in meta, f'PLUGIN_METADATA missing field: {field}'
+          print(f'✅ ${PLUGIN_MOD} PLUGIN_METADATA OK: {meta[\"name\"]} v{meta[\"version\"]}')
+          "

.github/workflows/test.yml

@@ -21,6 +21,7 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+          cache: 'pip'
 
       - name: Install dependencies
         run: |