Merge pull request #1027 from BobDickinson/tui-integration-design

Shared code architecture

Author: cliffhall

.dockerignore

@@ -7,10 +7,9 @@ node_modules
 npm-debug.log
 
 # Build artifacts
-client/dist
-client/build
-server/dist
-server/build
+web/dist
+cli/build
+tui/build
 
 # Environment variables
 .env
@@ -32,4 +31,4 @@ coverage
 
 # Docker
 Dockerfile
-.dockerignore
+.dockerignore

.github/workflows/cli_tests.yml

@@ -28,8 +28,17 @@ jobs:
           cd ..
           npm ci --ignore-scripts
 
+      - name: Build core package
+        working-directory: .
+        run: npm run build-core
+
+      - name: Build test package
+        working-directory: .
+        run: npm run build-test
+
       - name: Build CLI
-        run: npm run build
+        working-directory: .
+        run: npm run build-cli
 
       - name: Run tests
         run: npm test

.github/workflows/core_tests.yml

@@ -0,0 +1,33 @@
+name: Core Tests
+
+on:
+  push:
+    paths:
+      - "core/**"
+  pull_request:
+    paths:
+      - "core/**"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Build test package
+        run: npm run build-test
+
+      - name: Build core
+        run: npm run build-core
+
+      - name: Run core tests
+        run: npm run test-core

.github/workflows/e2e_tests.yml

@@ -56,17 +56,17 @@ jobs:
         with:
           name: playwright-report
           path: |
-            client/playwright-report/
-            client/test-results/
-            client/results.json
+            web/playwright-report/
+            web/test-results/
+            web/results.json
           retention-days: 2
 
       - name: Publish Playwright Test Summary
         uses: daun/playwright-report-summary@v3
         if: steps.playwright-tests.conclusion != 'skipped'
         with:
           create-comment: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
-          report-file: client/results.json
+          report-file: web/results.json
           comment-title: "🎭 Playwright E2E Test Results"
           job-summary: true
           icon-style: "emojis"

.github/workflows/main.yml

@@ -14,9 +14,6 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - name: Check formatting
-        run: npx prettier --check .
-
       - uses: actions/setup-node@v6
         with:
           node-version-file: package.json
@@ -29,15 +26,14 @@ jobs:
       - name: Check version consistency
         run: npm run check-version
 
-      - name: Check linting
-        working-directory: ./client
+      - name: Lint
         run: npm run lint
 
-      - name: Run client tests
-        working-directory: ./client
-        run: npm test
+      - name: Build
+        run: npm run build
 
-      - run: npm run build
+      - name: Run tests
+        run: npm test
 
   publish:
     runs-on: ubuntu-latest

.gitignore

@@ -3,19 +3,29 @@
 .idea
 node_modules/
 *-workspace/
-server/build
-client/dist
-client/tsconfig.app.tsbuildinfo
-client/tsconfig.node.tsbuildinfo
+web/tsconfig.app.tsbuildinfo
+web/tsconfig.node.tsbuildinfo
+web/tsconfig.jest.tsbuildinfo
+core/build
 cli/build
+tui/build
+test-servers/build
 test-output
 tool-test-output
 metadata-test-output
 # symlinked by `npm run link:sdk`:
 sdk
-client/playwright-report/
-client/results.json
-client/test-results/
-client/e2e/test-results/
-mcp.json
+web/playwright-report/
+web/results.json
+web/test-results/
+web/e2e/test-results/
+# Only ignore mcp.json at repo root (configs in configs/ are committed)
+/mcp.json
 .claude/settings.local.json
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.test
+.env.production

.prettierignore

@@ -1,5 +1,9 @@
 packages
-server/build
+core/build
+web/dist
+cli/build
+tui/build
+test-servers/build
 CODE_OF_CONDUCT.md
 SECURITY.md
 mcp.json

AGENTS.md

@@ -5,11 +5,10 @@
 ## Build Commands
 
 - Build all: `npm run build`
-- Build client: `npm run build-client`
-- Build server: `npm run build-server`
+- Build web: `npm run build-web`
 - Development mode: `npm run dev` (use `npm run dev:windows` on Windows)
 - Format code: `npm run prettier-fix`
-- Client lint: `cd client && npm run lint`
+- Web lint: `cd web && npm run lint`
 
 ## Code Style Guidelines
 
@@ -23,13 +22,15 @@
   - kebab-case for file names
 - Use async/await for asynchronous operations
 - Implement proper error handling with try/catch blocks
-- Use Tailwind CSS for styling in the client
+- Use Tailwind CSS for styling in the web app
 - Keep components small and focused on a single responsibility
 
 ## Project Organization
 
 The project is organized as a monorepo with workspaces:
 
-- `client/`: React frontend with Vite, TypeScript and Tailwind
-- `server/`: Express backend with TypeScript
+- `web/`: Web application (Vite, TypeScript, Tailwind)
+- `core/`: Core shared code used by web, CLI, and TUI
 - `cli/`: Command-line interface for testing and invoking MCP server methods directly
+- `tui/`: Terminal user interface
+- `test-servers/`: Composable MCP test servers, fixtures, and harness

Dockerfile

@@ -7,9 +7,10 @@ WORKDIR /app
 # Copy package files for installation
 COPY package*.json ./
 COPY .npmrc ./
-COPY client/package*.json ./client/
-COPY server/package*.json ./server/
+COPY web/package*.json ./web/
+COPY core/package*.json ./core/
 COPY cli/package*.json ./cli/
+COPY tui/package*.json ./tui/
 
 # Install dependencies
 RUN npm ci --ignore-scripts
@@ -28,25 +29,22 @@ WORKDIR /app
 # Copy package files for production
 COPY package*.json ./
 COPY .npmrc ./
-COPY client/package*.json ./client/
-COPY server/package*.json ./server/
+COPY web/package*.json ./web/
+COPY core/package*.json ./core/
 COPY cli/package*.json ./cli/
+COPY tui/package*.json ./tui/
 
 # Install only production dependencies
 RUN npm ci --omit=dev --ignore-scripts
 
 # Copy built files from builder stage
-COPY --from=builder /app/client/dist ./client/dist
-COPY --from=builder /app/client/bin ./client/bin
-COPY --from=builder /app/server/build ./server/build
+COPY --from=builder /app/web/dist ./web/dist
+COPY --from=builder /app/web/bin ./web/bin
 COPY --from=builder /app/cli/build ./cli/build
 
-# Set default port values as environment variables
-ENV CLIENT_PORT=6274
-ENV SERVER_PORT=6277
+# Set default port
+ENV PORT=6274
+EXPOSE ${PORT}
 
-# Document which ports the application uses internally
-EXPOSE ${CLIENT_PORT} ${SERVER_PORT}
-
-# Use ENTRYPOINT with CMD for arguments
-ENTRYPOINT ["npm", "start"]
+# Run web app
+CMD ["node", "web/bin/start.js"]

README.md

@@ -72,6 +72,8 @@ The inspector runs both an MCP Inspector (MCPI) client UI (default port 6274) an
 CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js
 ```
 
+**Environment variables:** The client UI port is set with `CLIENT_PORT`. The sandbox (MCP apps) port prefers `MCP_SANDBOX_PORT`; `SERVER_PORT` is accepted for backward compatibility. If neither is set, a dynamic port is used.
+
 For more details on ways to use the inspector, see the [Inspector section of the MCP docs site](https://modelcontextprotocol.io/docs/tools/inspector). For help with debugging, see the [Debugging guide](https://modelcontextprotocol.io/docs/tools/debugging).
 
 ### Servers File Export
@@ -182,7 +184,7 @@ The MCP Inspector proxy server requires authentication by default. When starting
 🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4
 
 🔗 Open inspector with token pre-filled:
-   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4
+   http://localhost:6274/?MCP_INSPECTOR_API_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4
 ```
 
 This token must be included as a Bearer token in the Authorization header for all requests to the server. The inspector will automatically open your browser with the token pre-filled in the URL.
@@ -213,10 +215,10 @@ Read more about the risks of this vulnerability on Oligo's blog: [Critical RCE V
 
 ---
 
-You can also set the token via the `MCP_PROXY_AUTH_TOKEN` environment variable when starting the server:
+You can also set the token via the `MCP_INSPECTOR_API_TOKEN` environment variable when starting the server (`MCP_PROXY_AUTH_TOKEN` is accepted for backward compatibility):
 
 ```bash
-MCP_PROXY_AUTH_TOKEN=$(openssl rand -hex 32) npm start
+MCP_INSPECTOR_API_TOKEN=$(openssl rand -hex 32) npm start
 ```
 
 #### Local-only Binding