Merge pull request #1222 from getlarge/issue-1209-mcp-apps-ext-apps

refactor(mcp-server): prepare shared MCP app UI foundation

Author: getlarge

.github/workflows/ci.yml

@@ -696,6 +696,7 @@ jobs:
       MCP_SERVER_IMAGE: ghcr.io/getlarge/themoltnet/mcp-server:ci-${{ github.sha }}
       DB_MIGRATE_IMAGE: ghcr.io/getlarge/themoltnet/db-migrate:ci-${{ github.sha }}
       CONSOLE_IMAGE: ghcr.io/getlarge/themoltnet/console:ci-${{ github.sha }}
+      MCP_HOST_IMAGE: ghcr.io/getlarge/themoltnet/mcp-host:ci-${{ github.sha }}
       # Pre-set the URLs the e2e tests need. Without this, Nx's bin/nx.js
       # loads workspace-root .env at startup; our .env is dotenvx-encrypted,
       # so plain-dotenv pulls ciphertext into DATABASE_URL and pg silently
@@ -762,6 +763,7 @@ jobs:
       MCP_SERVER_IMAGE: ghcr.io/getlarge/themoltnet/mcp-server:ci-${{ github.sha }}
       DB_MIGRATE_IMAGE: ghcr.io/getlarge/themoltnet/db-migrate:ci-${{ github.sha }}
       CONSOLE_IMAGE: ghcr.io/getlarge/themoltnet/console:ci-${{ github.sha }}
+      MCP_HOST_IMAGE: ghcr.io/getlarge/themoltnet/mcp-host:ci-${{ github.sha }}
     steps:
       - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v5
@@ -801,6 +803,19 @@ jobs:
           CONSOLE_BASE_URL: http://localhost:5174
           MAILSLURPER_API_URL: http://localhost:4437
         run: pnpm exec nx run @moltnet/console:e2e
+      - name: Run MCP Host Browser E2E tests
+        env:
+          BASE_URL: http://127.0.0.1:8082
+          MCP_SERVER_URL: http://127.0.0.1:8001
+          REST_API_URL: http://127.0.0.1:8080
+          DATABASE_URL: postgresql://moltnet:moltnet_secret@127.0.0.1:5433/moltnet
+          ORY_HYDRA_PUBLIC_URL: http://127.0.0.1:4444
+          ORY_HYDRA_ADMIN_URL: http://127.0.0.1:4445
+          ORY_KETO_PUBLIC_URL: http://127.0.0.1:4466
+          ORY_KETO_ADMIN_URL: http://127.0.0.1:4467
+          ORY_KRATOS_PUBLIC_URL: http://127.0.0.1:4433
+          ORY_KRATOS_ADMIN_URL: http://127.0.0.1:4434
+        run: pnpm exec nx run @moltnet/mcp-host-e2e:e2e
       - name: Docker Compose logs
         if: failure()
         run: docker compose -f docker-compose.e2e.yaml -f docker-compose.e2e.ci.yaml logs --tail=50
@@ -826,6 +841,7 @@ jobs:
       MCP_SERVER_IMAGE: ghcr.io/getlarge/themoltnet/mcp-server:ci-${{ github.sha }}
       DB_MIGRATE_IMAGE: ghcr.io/getlarge/themoltnet/db-migrate:ci-${{ github.sha }}
       CONSOLE_IMAGE: ghcr.io/getlarge/themoltnet/console:ci-${{ github.sha }}
+      MCP_HOST_IMAGE: ghcr.io/getlarge/themoltnet/mcp-host:ci-${{ github.sha }}
     steps:
       - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v5
@@ -974,6 +990,9 @@ jobs:
           - image: console
             dockerfile: apps/console/Dockerfile
             needed-when: e2e-any
+          - image: mcp-host
+            dockerfile: apps/mcp-host/Dockerfile
+            needed-when: e2e-any
     steps:
       - name: Skip if image not needed
         id: gate

AGENTS.md

@@ -159,7 +159,7 @@ See `libs/database/drizzle/README.md` for the full workflow, rollback strategy,
 - **NEVER use `paths` aliases** in any `tsconfig.json` (root or workspace). Package resolution must go through pnpm workspace symlinks and `package.json` `exports`, not TypeScript path mappings.
 - **Source exports**: All workspace packages export source directly via `"import": "./src/index.ts"` and `"types": "./src/index.ts"` in conditional exports. The `main` and `types` top-level fields point to `./dist/` as fallback. TypeScript, Vite, and vitest all resolve via the `import` condition to source files. No custom conditions needed.
 - **Incremental builds**: Lib packages use `tsc -b` for incremental compilation with `.tsbuildinfo` caching. App packages (server, rest-api, mcp-server) use `vite build` with SSR mode to produce self-contained bundles where workspace deps are inlined and third-party deps stay external. The root `build` script runs `pnpm -r run build` which executes in topological order (libs first, then apps).
-- **Project references**: The root `tsconfig.json` is a solution file (`files: []` + `references` to all packages). Each workspace tsconfig has `composite: true`. References are auto-synced from `workspace:*` dependencies by `update-ts-references` (runs in postinstall).
+- **Project references**: The root `tsconfig.json` is a solution file (`files: []` + `references` to all packages). Each workspace tsconfig has `composite: true`. References are synced by Nx TypeScript sync; `pnpm install` runs `nx sync` in `postinstall`, and Nx can also validate sync during task execution.
 - **Typecheck**: Each workspace runs `tsc -b --emitDeclarationOnly` via `pnpm -r run typecheck`. This emits `.d.ts` + `.tsbuildinfo` to a directory determined by the workspace's group (see "Build cache contract" below), which is required because `composite: true` and project references don't support `--noEmit`.
 - **Workspace linking**: `inject-workspace-packages=false` in `.npmrc` — workspace dependencies are symlinked (not hardlinked copies), so changes propagate instantly without re-running `pnpm install`.
 
@@ -190,7 +190,7 @@ When creating a new `libs/` or `apps/` package:
 
 1. Add a `tsconfig.json` extending root (`"extends": "../../tsconfig.json"`) with `composite: true`, `outDir` and `rootDir`
    - For frontend apps with JSX: also add `"jsx": "react-jsx"`, `"lib": ["ES2022", "DOM"]`
-   - tsconfig `references` are auto-synced by `update-ts-references` on `pnpm install`
+   - tsconfig `references` are synced by Nx TypeScript sync on `pnpm install` via `nx sync`
 2. Set `main`/`types` to `./dist/index.js`/`./dist/index.d.ts` and `exports` with source-direct format:
    ```json
    "exports": { ".": { "import": "./src/index.ts", "types": "./src/index.ts" } }

apps/mcp-host-e2e/eslint.config.mjs

@@ -0,0 +1,12 @@
+import playwright from 'eslint-plugin-playwright';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  playwright.configs['flat/recommended'],
+  ...baseConfig,
+  {
+    files: ['**/*.ts', '**/*.js'],
+    // Override or add rules here
+    rules: {},
+  },
+];

apps/mcp-host-e2e/global-setup.ts

@@ -0,0 +1,52 @@
+async function waitForHealthy(url: string, maxAttempts = 60): Promise<void> {
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return;
+      }
+    } catch {
+      // Service not ready yet.
+    }
+
+    await new Promise((resolve) => {
+      setTimeout(resolve, 2000);
+    });
+  }
+
+  throw new Error(
+    `Service at ${url} did not become healthy after ${maxAttempts} attempts`,
+  );
+}
+
+const E2E_LOCAL_DEFAULTS = {
+  BASE_URL: 'http://127.0.0.1:8082',
+  MCP_SERVER_URL: 'http://127.0.0.1:8001',
+  REST_API_URL: 'http://127.0.0.1:8080',
+  DATABASE_URL: 'postgresql://moltnet:moltnet_secret@127.0.0.1:5433/moltnet',
+  ORY_HYDRA_PUBLIC_URL: 'http://127.0.0.1:4444',
+  ORY_HYDRA_ADMIN_URL: 'http://127.0.0.1:4445',
+  ORY_KETO_PUBLIC_URL: 'http://127.0.0.1:4466',
+  ORY_KETO_ADMIN_URL: 'http://127.0.0.1:4467',
+  ORY_KRATOS_PUBLIC_URL: 'http://127.0.0.1:4433',
+  ORY_KRATOS_ADMIN_URL: 'http://127.0.0.1:4434',
+} as const;
+
+function applyLocalFallbackEnv(): void {
+  for (const [name, value] of Object.entries(E2E_LOCAL_DEFAULTS)) {
+    process.env[name] ??= value;
+  }
+}
+
+export default async function globalSetup() {
+  applyLocalFallbackEnv();
+
+  await Promise.all([
+    waitForHealthy(`${process.env['ORY_KRATOS_PUBLIC_URL']}/health/alive`),
+    waitForHealthy(`${process.env['ORY_HYDRA_PUBLIC_URL']}/health/alive`),
+    waitForHealthy(`${process.env['ORY_KETO_PUBLIC_URL']}/health/alive`),
+    waitForHealthy(`${process.env['REST_API_URL']}/health`),
+    waitForHealthy(`${process.env['MCP_SERVER_URL']}/healthz`),
+    waitForHealthy(`${process.env['BASE_URL']}/healthz`),
+  ]);
+}

apps/mcp-host-e2e/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@moltnet/mcp-host-e2e",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@moltnet/mcp-test-harness": "workspace:*"
+  },
+  "nx": {
+    "tags": [
+      "type:e2e",
+      "scope:tooling",
+      "platform:cli"
+    ],
+    "implicitDependencies": [
+      "@moltnet/mcp-host"
+    ]
+  }
+}

apps/mcp-host-e2e/playwright.config.ts

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'node:url';
+
+import { nxE2EPreset } from '@nx/playwright/preset';
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  ...nxE2EPreset(fileURLToPath(import.meta.url), { testDir: './src' }),
+  globalSetup: './global-setup.ts',
+  use: {
+    baseURL: process.env['BASE_URL'] || 'http://127.0.0.1:8082',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});

apps/mcp-host-e2e/src/example.spec.ts

@@ -0,0 +1,35 @@
+import {
+  createMcpTestHarness,
+  type McpTestHarness,
+} from '@moltnet/mcp-test-harness';
+import { expect, test } from '@playwright/test';
+
+let harness: McpTestHarness;
+
+test.beforeAll(async () => {
+  harness = await createMcpTestHarness();
+});
+
+test.afterAll(async () => {
+  await harness?.teardown();
+});
+
+test('loads the tasks MCP app through the host bridge', async ({ page }) => {
+  const url = new URL('/', 'http://127.0.0.1:8082');
+  url.searchParams.set('tool', 'tasks_app_open');
+  url.searchParams.set('autorun', '1');
+  url.searchParams.set('args', '{}');
+  url.searchParams.set('server', `${harness.mcpBaseUrl}/mcp`);
+  url.searchParams.set('clientId', harness.agent.clientId);
+  url.searchParams.set('clientSecret', harness.agent.clientSecret);
+
+  await page.goto(url.toString());
+
+  await expect(page.locator('h1')).toContainText('Basic Host Fixture');
+  await expect(page.locator('#status')).toContainText('completed');
+  await expect(page.locator('#app-state')).toContainText('app-ready');
+  await expect(page.locator('#app-frame')).toBeVisible();
+  await expect(page.locator('#result')).toContainText(
+    'ui://moltnet/tasks.html',
+  );
+});

apps/mcp-host-e2e/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "module": "ESNext",
+    "outDir": "../../dist/out-tsc",
+    "sourceMap": false
+  },
+  "extends": "../../tsconfig.json",
+  "include": [
+    "**/*.ts",
+    "**/*.js",
+    "playwright.config.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.spec.js",
+    "src/**/*.test.ts",
+    "src/**/*.test.js",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "../../libs/mcp-test-harness"
+    }
+  ]
+}

apps/mcp-host/Dockerfile

@@ -0,0 +1,24 @@
+FROM node:22.19.0-slim AS base
+RUN npm install -g pnpm@10.29.3
+WORKDIR /app
+
+FROM base AS deps
+COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
+COPY apps/mcp-host/package.json apps/mcp-host/
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+    pnpm install --frozen-lockfile --ignore-scripts
+
+FROM deps AS build
+COPY . .
+RUN pnpm --filter @moltnet/mcp-host exec vite build
+
+FROM node:22.19.0-slim AS production
+LABEL org.opencontainers.image.source="https://github.com/getlarge/themoltnet"
+LABEL org.opencontainers.image.description="MoltNet MCP host e2e fixture"
+LABEL org.opencontainers.image.licenses="MIT"
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/dist/apps/mcp-host ./dist
+COPY --from=build /app/apps/mcp-host/server.mjs ./server.mjs
+EXPOSE 8080 8081
+CMD ["node", "server.mjs"]

apps/mcp-host/eslint.config.mjs

@@ -0,0 +1,3 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [...baseConfig];