Shared code architecture

.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,13 @@ jobs:
           cd ..
           npm ci --ignore-scripts
 
+      - name: Build core package
+        working-directory: .
+        run: npm run build-core
+
       - name: Build CLI
-        run: npm run build
+        working-directory: .
+        run: npm run build-cli
 
       - name: Run tests
         run: npm test

.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

@@ -30,11 +30,11 @@ jobs:
         run: npm run check-version
 
       - name: Check linting
-        working-directory: ./client
+        working-directory: ./web
         run: npm run lint
 
-      - name: Run client tests
-        working-directory: ./client
+      - name: Run web tests
+        working-directory: ./web
         run: npm test
 
       - run: npm run build

.gitignore

@@ -3,19 +3,28 @@
 .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-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 (test configs in test/ are committed)
+/mcp.json
 .claude/settings.local.json
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.test
+.env.production

.prettierignore

@@ -1,5 +1,8 @@
 packages
-server/build
+core/build
+web/dist
+cli/build
+tui/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,14 @@
   - 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

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

cli/__tests__/cli.test.ts

@@ -12,12 +12,12 @@ import {
   createInvalidConfig,
   deleteConfigFile,
 } from "./helpers/fixtures.js";
-import { getTestMcpServerCommand } from "./helpers/test-server-stdio.js";
-import { createTestServerHttp } from "./helpers/test-server-http.js";
+import { getTestMcpServerCommand } from "../../core/test/test-server-stdio.js";
+import { createTestServerHttp } from "../../core/test/test-server-http.js";
 import {
   createEchoTool,
   createTestServerInfo,
-} from "./helpers/test-fixtures.js";
+} from "../../core/test/test-server-fixtures.js";
 
 describe("CLI Tests", () => {
   describe("Basic CLI Mode", () => {
@@ -59,6 +59,17 @@ describe("CLI Tests", () => {
 
       expectCliFailure(result);
     });
+
+    // Temporary: remove .skip to verify that expectCliSuccess shows CLI stdout/stderr when the CLI fails
+    it.skip("TEMP: expect success when CLI fails (validates error output in assertion)", async () => {
+      const result = await runCli([
+        NO_SERVER_SENTINEL,
+        "--cli",
+        "--method",
+        "tools/list",
+      ]);
+      expectCliSuccess(result); // will fail; failure message should include result.stdout and result.stderr
+    });
   });
 
   describe("Environment Variables", () => {
@@ -370,11 +381,9 @@ describe("CLI Tests", () => {
       });
 
       try {
-        const port = await server.start("http");
-        const serverUrl = `${server.getUrl()}/mcp`;
-
+        const port = await server.start();
         const result = await runCli([
-          serverUrl,
+          server.url,
           "--cli",
           "--method",
           "logging/setLevel",
@@ -741,11 +750,9 @@ describe("CLI Tests", () => {
       });
 
       try {
-        await server.start("http");
-        const serverUrl = `${server.getUrl()}/mcp`;
-
+        await server.start();
         const result = await runCli([
-          serverUrl,
+          server.url,
           "--cli",
           "--method",
           "tools/list",
@@ -768,11 +775,9 @@ describe("CLI Tests", () => {
       });
 
       try {
-        await server.start("http");
-        const serverUrl = `${server.getUrl()}/mcp`;
-
+        await server.start();
         const result = await runCli([
-          serverUrl,
+          server.url,
           "--transport",
           "http",
           "--cli",
@@ -797,11 +802,9 @@ describe("CLI Tests", () => {
       });
 
       try {
-        await server.start("http");
-        const serverUrl = `${server.getUrl()}/mcp`;
-
+        await server.start();
         const result = await runCli([
-          serverUrl,
+          server.url,
           "--transport",
           "http",
           "--cli",
@@ -826,11 +829,9 @@ describe("CLI Tests", () => {
       });
 
       try {
-        await server.start("http");
-        const serverUrl = `${server.getUrl()}/mcp`;
-
+        await server.start();
         const result = await runCli([
-          serverUrl,
+          server.url,
           "--transport",
           "sse",
           "--cli",