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

[ductiletoaster]

This PR is an RFC / proposal. The intent is to highlight a possible new direction for CGC and gather feedback on whether this is something the project is interested in pursuing. Nothing here needs to be merged as-is.

What this proposes

A plugin extension system for CodeGraphContext that enables independently installable packages to contribute CLI commands and MCP tools — without modifying core CGC code. The system ships with two first-party plugins (OTEL span processor and Xdebug trace listener), a shared CI/CD pipeline, sample applications, and a hosted MCP server container image.

Why

CGC currently provides static code graph analysis. This proposal extends it with runtime intelligence — the ability to overlay execution traces (OTEL spans, Xdebug call stacks) onto the static code graph, enabling cross-layer queries like "which methods executed during this request that have no test coverage" or "show code paths never observed at runtime."

The plugin architecture ensures this complexity is opt-in and composable: install only what you need, and broken plugins never crash the host.

Scope of changes

140 files changed, ~14,000 lines added, ~86 lines modified in existing files.

The change footprint on existing code is deliberately minimal:

Area	Files	What changed
Core CGC (src/)	4 files	plugin_registry.py (new), http_transport.py (new), server.py (refactored handle_request()), cli/main.py (plugin loading + --transport option)
Plugins (plugins/)	23 files	3 plugin packages: cgc-plugin-stub (test fixture), cgc-plugin-otel (OTEL spans), cgc-plugin-xdebug (Xdebug traces)
Tests (tests/)	12 files	Unit, integration, and E2E tests for plugin registry, OTEL processor, Xdebug parser, HTTP transport, container lifecycle
Samples (samples/)	~40 files	3 sample apps (PHP/Laravel, Python/FastAPI, TypeScript/Express) + smoke script + docker-compose
Infrastructure	~15 files	Dockerfiles, docker-compose, K8s manifests, CI/CD workflows, Neo4j schema
Specs & docs	~30 files	Feature specification, implementation plan, research, data model, contracts, plugin authoring guide, deployment guide
Root config	2 files	pyproject.toml (added packaging dep + plugin extras), .gitignore (scoped docker-compose ignore)

What it does NOT change

• No existing tests are modified or broken
• No existing CLI commands are altered
• The MCP stdio transport is completely unchanged (backwards compatible)
• No existing graph schema is modified (new node types are additive)

Architecture overview

┌─────────────────────────────────────────────────────────┐
│                    CGC Core                              │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │PluginRegistry│  │  MCPServer   │  │ HTTPTransport │  │
│  │ (discovery)  │→ │ (tools/call) │← │ (POST /mcp)   │  │
│  └──────┬───────┘  └──────────────┘  └───────────────┘  │
│         │ entry-points                                   │
├─────────┼───────────────────────────────────────────────┤
│         ▼                                                │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐   │
│  │  stub plugin │  │  OTEL plugin │  │ Xdebug plugin │   │
│  │  (testing)   │  │  (runtime)   │  │  (dev traces) │   │
│  └─────────────┘  └──────────────┘  └───────────────┘   │
└─────────────────────────────────────────────────────────┘
                          │
                    ┌─────▼─────┐
                    │  Neo4j /  │
                    │ FalkorDB  │  ← Static + Runtime nodes
                    └───────────┘

Plugin discovery: Uses Python importlib.metadata entry-points (cgc_cli_plugins + cgc_mcp_plugins). Install a plugin with pip install cgc-plugin-otel → CGC discovers it automatically at startup.

Isolation: Each plugin load is wrapped in try/except with a 5-second SIGALRM timeout. A broken plugin logs a warning; CGC and all other plugins continue normally.

HTTP transport: cgc mcp start --transport http exposes a JSON-RPC endpoint at POST /mcp with a health check at GET /healthz. No auth at the application layer — designed to sit behind a reverse proxy.

The 6 user stories

#	Story	Priority	Status
US1	Plugin Extensibility Foundation	P1 (MVP)	Complete
US2	Runtime Intelligence via OTEL Plugin	P2	Complete
US3	Development Traces via Xdebug Plugin	P3	Complete
US4	Automated Container Builds (CI/CD)	P4	Complete
US5	Sample Applications (E2E validation)	P5	Complete
US6	Hosted MCP Server Container Image	P6	Complete

Full specification: specs/001-cgc-plugin-extension/spec.md

Proposed PR decomposition

If this direction is accepted, this branch could be broken into 6 independently reviewable PRs following the user story boundaries:

PR 1: Plugin Foundation (US1) — ~800 lines

The core infrastructure. Smallest possible reviewable unit.

• src/codegraphcontext/plugin_registry.py
• Modifications to server.py and cli/main.py
• plugins/cgc-plugin-stub/ (test fixture)
• Unit + integration tests for plugin discovery/loading
• pyproject.toml changes

PR 2: OTEL Plugin (US2) — ~1,500 lines

Depends on PR 1.

• plugins/cgc-plugin-otel/ (span processor, gRPC receiver, Neo4j writer)
• config/neo4j/init.cypher (schema), config/otel-collector/config.yaml
• Docker services (docker-compose additions)
• Unit + integration tests

PR 3: Xdebug Plugin (US3) — ~1,000 lines

Depends on PR 1. Independent of PR 2.

• plugins/cgc-plugin-xdebug/ (DBGp server, frame writer)
• Docker dev service
• Unit tests

PR 4: CI/CD Pipeline (US4) — ~500 lines

Depends on PRs 2+3 (needs Dockerfiles).

• .github/workflows/ (docker-publish, test-plugins)
• .github/services.json
• Dockerfiles for plugins
• K8s manifests for OTEL plugin

PR 5: Sample Applications (US5) — ~2,500 lines

Depends on PR 2. Could be reviewed independently as reference material.

• samples/ (PHP/Laravel, Python/FastAPI, TypeScript/Express)
• smoke-all.sh validation script
• KNOWN-LIMITATIONS.md

PR 6: Hosted MCP Server (US6) — ~2,000 lines

Depends on PR 1 only. Can be reviewed in parallel with PRs 2-5.

• src/codegraphcontext/http_transport.py
• Dockerfile.mcp, K8s manifests, docker-compose additions
• docs/deployment/MCP_SERVER_HOSTING.md
• Unit + integration + E2E tests

Standalone: Specs & Documentation — ~3,000 lines

Could land first or alongside PR 1 as context.

• specs/001-cgc-plugin-extension/ (spec, plan, research, data model, contracts, tasks)
• docs/plugins/ (authoring guide, cross-layer queries, manual testing)

How to explore this branch

# Clone and checkout
git checkout 001-cgc-plugin-extension

# Set up local dev environment
uv venv --python 3.12 .venv && source .venv/bin/activate
uv pip install -e ".[dev]" -e plugins/cgc-plugin-stub

# Run plugin tests (no database needed)
PYTHONPATH=src pytest tests/unit/plugin/ tests/unit/test_http_transport.py -v

# Run the full stack with Docker
docker compose -f docker-compose.plugin-stack.yml up -d
# Then: http://localhost:7474 (Neo4j Browser)
# Then: curl http://localhost:8045/healthz (MCP server health)

Open questions for maintainers

1. Is runtime intelligence in scope? The core value proposition is overlaying execution data onto the static graph. Is this a direction the project wants to go?
2. Plugin architecture vs. monorepo modules? The entry-points approach enables third-party plugins, but if extensibility isn't a goal, simpler module imports might suffice.
3. Graph database assumptions — The OTEL and Xdebug plugins assume Neo4j with specific schema. Should they also support FalkorDB?
4. Sample apps — Are PHP/Laravel + Python/FastAPI + TypeScript/Express the right choices for demonstrating the pipeline, or would different stacks be more relevant?

Test plan

• All 23 HTTP transport tests pass (unit + integration)
• All 57 plugin tests pass (registry, OTEL processor, Xdebug parser, plugin lifecycle)
• Existing CGC tests unaffected
• Docker-based E2E tests (require docker compose up)
• Full sample app smoke script (samples/smoke-all.sh)

🤖 Generated with Claude Code