feat(x2a): X2A MCP tools (#2733)

* feat(x2a): X2A MCP tools

- Add x2a-mcp-extras backend plugin with MCP tools
- Add x2a-dcr frontend plugin: legacy-frontend reimplementation
  of @backstage/plugin-auth for RHDH 1.9 DCR consent flow
  (to be replaced by upstream plugin in RHDH 1.10+)

* x2a-dcr plugin

* Move X2AConfig to types.ts

* Move shared backend code to x2a-node

* avoid orphaned init jobs and other fixes

* x2a-create-project instructs about init-phase run

* x2a-trigger-next-phase links to manual action

* cleanup

* share RBAC checks between MCP and HTTP

* Add #runinit and #runnext deeplinks to x2a/projects/[projectid] URL

* Update documentation for authZ resolution in MCP tools

Author: mareklibra

workspaces/x2a/.changeset/loud-buttons-sleep.md

@@ -0,0 +1,10 @@
+---
+'@red-hat-developer-hub/backstage-plugin-x2a-mcp-extras': minor
+'@red-hat-developer-hub/backstage-plugin-x2a-backend': minor
+'@red-hat-developer-hub/backstage-plugin-x2a-dcr': minor
+'@red-hat-developer-hub/backstage-plugin-x2a-node': minor
+'@red-hat-developer-hub/backstage-plugin-x2a-common': patch
+'@red-hat-developer-hub/backstage-plugin-x2a': patch
+---
+
+Add x2a-mcp-extras backend plugin exposing MCP tools for AI clients, x2a-dcr frontend plugin for RHDH 1.9 DCR OAuth consent flow, and x2a-node shared node-library. Refactor x2a-backend to use shared service refs from x2a-node via a feature loader.

workspaces/x2a/app-config.yaml

@@ -22,7 +22,9 @@ backend:
     # Content-Security-Policy directives follow the Helmet format: https://helmetjs.github.io/#reference
     # Default Helmet Content-Security-Policy values can be removed by setting the key to false
   cors:
-    origin: http://localhost:3000
+    origin:
+      - http://localhost:3000
+      - http://localhost:6274
     methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
     credentials: true
   # This is for local development only, it is not recommended to use this in production
@@ -32,6 +34,22 @@ backend:
     connection: ':memory:'
   # workingDirectory: /tmp # Use this to configure a working directory for the scaffolder, defaults to the OS temp-dir
 
+  # MCP Actions: expose x2a tools to AI clients (Cursor, Claude, etc.)
+  actions:
+    pluginSources:
+      - 'catalog'
+      - 'software-catalog-mcp-tool'
+      - 'x2a-mcp-extras'
+  # Enable following for non-DCR flow for MCP tools
+  # auth:
+  #   externalAccess:
+  #     - type: static
+  #       options:
+  #         token: ${MCP_TOKEN}
+  #         subject: mcp-clients
+  #       accessRestrictions:
+  #         - plugin: mcp-actions
+
 proxy:
   ### Example for how to add a proxy endpoint for the frontend.
   ### A typical reason to do this is to handle HTTPS and CORS for internal services.
@@ -74,6 +92,17 @@ integrations:
 auth:
   # see https://backstage.io/docs/auth/ to learn about auth providers
   environment: development
+  # Uncomment to enable OAuth DCR for MCP clients (user-identity auth).
+  # Narrow allowedRedirectUriPatterns to match your specific needs.
+  # Requires either @backstage/plugin-auth or x2a-dcr frontend plugin.
+  experimentalDynamicClientRegistration:
+    enabled: true
+    allowedRedirectUriPatterns:
+      # Keeping those generic for development. Narrow to specific patterns in production.
+      - cursor://*
+      - https://*
+      - http://*
+      # - http://localhost:*
   providers:
     # See https://backstage.io/docs/auth/guest/provider
     guest: {}

workspaces/x2a/examples/example-rbac-policy.csv

@@ -17,6 +17,7 @@ g, user:development/guest, role:default/x2aUser
 
 # the account to play with the admin roles
 #g, user:default/mareklibra, role:default/x2aViewerAdmin
+g, user:default/mareklibra, role:default/x2aAdmin
 g, group:default/x2a-admin-group, role:default/x2aAdmin
 
 g, user:default/elai-shalev, role:default/x2aAdmin

workspaces/x2a/package.json

@@ -17,13 +17,13 @@
     "openapi-generate": "cd plugins/x2a-backend && yarn openapi-generate",
     "tsc": "tsc",
     "tsc:full": "tsc --skipLibCheck true --incremental false",
-    "clean": "backstage-cli repo clean",
+    "clean": "backstage-cli repo clean && find plugins -mindepth 2 -maxdepth 2 -type d -name dist-dynamic -exec rm -rf {} +",
     "test": "backstage-cli repo test",
     "test:pg": "CI=true backstage-cli repo test",
     "test:all": "yarn openapi-generate && yarn prettier:check && yarn lint:all && backstage-cli repo test --coverage",
     "test:all:pg": "yarn openapi-generate && yarn prettier:check && yarn lint:all && CI=true backstage-cli repo test --coverage",
     "test:e2e": "echo Skipping until we have tests: playwright test",
-    "fix": "backstage-cli repo fix",
+    "fix": "backstage-cli repo fix --publish",
     "lint": "backstage-cli repo lint --since origin/main",
     "lint:all": "backstage-cli repo lint",
     "prettier:check": "prettier --check .",

workspaces/x2a/packages/app/e2e-tests/app.test.ts

@@ -20,15 +20,3 @@ import { test, expect } from '@playwright/test';
 test('noop test', async () => {
   expect(true).toBe(true);
 });
-
-/*
-test('App should render the welcome page', async ({ page }) => {
-  await page.goto('/');
-
-  const enterButton = page.getByRole('button', { name: 'Enter' });
-  await expect(enterButton).toBeVisible();
-  await enterButton.click();
-
-  await expect(page.getByText('My Company Catalog')).toBeVisible();
-});
-*/

workspaces/x2a/packages/app/package.json

@@ -51,6 +51,7 @@
     "@material-ui/core": "^4.12.2",
     "@material-ui/icons": "^4.9.1",
     "@red-hat-developer-hub/backstage-plugin-x2a": "workspace:*",
+    "@red-hat-developer-hub/backstage-plugin-x2a-dcr": "workspace:*",
     "react": "^18.0.2",
     "react-dom": "^18.0.2",
     "react-router": "^6.3.0",

workspaces/x2a/packages/app/src/App.tsx

@@ -59,6 +59,7 @@ import {
   RepoAuthenticationExtension,
   X2ARepoUrlPickerExtension,
 } from '@red-hat-developer-hub/backstage-plugin-x2a';
+import { DcrConsentPage } from '@red-hat-developer-hub/backstage-plugin-x2a-dcr';
 import {
   bitbucketAuthApiRef,
   githubAuthApiRef,
@@ -154,6 +155,7 @@ const routes = (
     <Route path="/settings" element={<UserSettingsPage />} />
     <Route path="/catalog-graph" element={<CatalogGraphPage />} />
     <Route path="/notifications" element={<NotificationsPage />} />
+    <Route path="/oauth2/*" element={<DcrConsentPage />} />
 
     {/* At RHDH runtime, this is replaced by dynamicPlugin configuration:
       https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.9/html/installing_and_viewing_plugins_in_red_hat_developer_hub/assembly-front-end-plugin-wiring.adoc_rhdh-extensions-plugins#con-providing-custom-scaffolder-field-extensions.adoc_assembly-front-end-plugin-wiring

workspaces/x2a/packages/backend/README.md

@@ -1,59 +1,47 @@
-# example-backend
+# x2a backend
 
-This package is an EXAMPLE of a Backstage backend.
+Backstage backend for local development of the **x2a** workspace.
 
-The main purpose of this package is to provide a test bed for Backstage plugins
-that have a backend part. Feel free to experiment locally or within your fork by
-adding dependencies and routes to this backend, to try things out.
+This package wires together the x2a plugins and the standard Backstage
+infrastructure so you can run a fully functional backend on your machine.
 
-Our goal is to eventually amend the create-app flow of the CLI, such that a
-production ready version of a backend skeleton is made alongside the frontend
-app. Until then, feel free to experiment here!
+## x2a service factories
 
-## Development
+The x2a plugins share service refs defined in
+`@red-hat-developer-hub/backstage-plugin-x2a-node` (the `x2a-node`
+node-library). Those refs carry **no `defaultFactory`**.
 
-To run the example backend, first go to the project root and run
+The `x2a-backend` default export is a `createBackendFeatureLoader` that yields
+both the plugin and the matching service factories (`x2aDatabaseServiceFactory`,
+`kubeServiceFactory`). This means a single `backend.add(...)` call registers
+everything:
 
-```bash
-yarn install
+```ts
+backend.add(import('@red-hat-developer-hub/backstage-plugin-x2a-backend'));
 ```
 
-You should only need to do this once.
+This design works in both local development and in RHDH dynamic plugin mode,
+because RHDH's dynamic plugin loader only reads the default export of each
+plugin package.
 
-After that, go to the `packages/backend` directory and run
+## Development
+
+From the workspace root:
 
 ```bash
+yarn install
 yarn start
 ```
 
-If you want to override any configuration locally, for example adding any secrets,
-you can do so in `app-config.local.yaml`.
-
-The backend starts up on port 7007 per default.
-
-## Populating The Catalog
-
-If you want to use the catalog functionality, you need to add so called
-locations to the backend. These are places where the backend can find some
-entity descriptor data to consume and serve. For more information, see
-[Software Catalog Overview - Adding Components to the Catalog](https://backstage.io/docs/features/software-catalog/#adding-components-to-the-catalog).
-
-To get started quickly, this template already includes some statically configured example locations
-in `app-config.yaml` under `catalog.locations`. You can remove and replace these locations as you
-like, and also override them for local development in `app-config.local.yaml`.
-
-## Authentication
+Override secrets or local configuration in `app-config.local.yaml`.
+The backend starts on port **7007** by default.
 
-We chose [Passport](http://www.passportjs.org/) as authentication platform due
-to its comprehensive set of supported authentication
-[strategies](http://www.passportjs.org/packages/).
+## Populating the catalog
 
-Read more about the
-[auth-backend](https://github.com/backstage/backstage/blob/master/plugins/auth-backend/README.md)
-and
-[how to add a new provider](https://github.com/backstage/backstage/blob/master/docs/auth/add-auth-provider.md)
+Add location entries under `catalog.locations` in `app-config.yaml`.
+See [Adding Components to the Catalog](https://backstage.io/docs/features/software-catalog/#adding-components-to-the-catalog)
+for details.
 
 ## Documentation
 
-- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
 - [Backstage Documentation](https://backstage.io/docs)

workspaces/x2a/packages/backend/package.json

@@ -35,6 +35,7 @@
     "@backstage/plugin-catalog-backend-module-logs": "0.1.16",
     "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "0.2.14",
     "@backstage/plugin-kubernetes-backend": "0.20.4",
+    "@backstage/plugin-mcp-actions-backend": "0.1.9",
     "@backstage/plugin-notifications-backend": "0.6.0",
     "@backstage/plugin-permission-backend": "0.7.3",
     "@backstage/plugin-permission-common": "^0.9.3",
@@ -54,6 +55,7 @@
     "@backstage/plugin-techdocs-backend": "2.1.2",
     "@red-hat-developer-hub/backstage-plugin-scaffolder-backend-module-x2a": "workspace:^",
     "@red-hat-developer-hub/backstage-plugin-x2a-backend": "workspace:*",
+    "@red-hat-developer-hub/backstage-plugin-x2a-mcp-extras": "workspace:^",
     "app": "link:../app",
     "better-sqlite3": "^12.0.0",
     "node-gyp": "^9.0.0",

workspaces/x2a/packages/backend/src/index.ts

@@ -84,9 +84,16 @@ backend.add(import('@backstage/plugin-kubernetes-backend'));
 backend.add(import('@backstage/plugin-notifications-backend'));
 backend.add(import('@backstage/plugin-signals-backend'));
 
+// x2a-backend's default export is a feature loader that yields the plugin
+// together with service factories for the x2a-node canonical refs.
 backend.add(import('@red-hat-developer-hub/backstage-plugin-x2a-backend'));
 
 backend.add(
   import('@red-hat-developer-hub/backstage-plugin-scaffolder-backend-module-x2a'),
 );
+
+// MCP server + x2a MCP tools
+backend.add(import('@backstage/plugin-mcp-actions-backend'));
+backend.add(import('@red-hat-developer-hub/backstage-plugin-x2a-mcp-extras'));
+
 backend.start();