feat: implement quickmock registry protocol and integrate with mcp and vscode extension

Author: Ivanruii

package-lock.json

@@ -31,6 +31,7 @@
   },
   "devDependencies": {
     "@lemoncode/quickmock-bridge-protocol": "*",
+    "@lemoncode/quickmock-registry-protocol": "*",
     "@lemoncode/typescript-config": "*",
     "@lemoncode/tsdown-config": "*",
     "@lemoncode/vitest-config": "*",

packages/mcp/package.json

@@ -1,3 +1,2 @@
 export * from './registry.client';
 export * from './registry.models';
-export * from './registry.utils';

packages/mcp/src/core/index.ts

@@ -1,33 +1,40 @@
 import { readFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import {
+  buildPortFilePath,
+  DOCUMENT_ROUTE,
+  LOOPBACK_HOST,
+  parsePortFile,
+  TOKEN_HEADER,
+} from '@lemoncode/quickmock-registry-protocol';
 import { nullClient, type RegistryClient } from './registry.models';
-import { workspaceHash } from './registry.utils';
 
-/** HTTP client for the VSCode extension's registry server. Falls back to nullClient when the extension is not running. */
-export function createRegistryClient(): RegistryClient {
-  const workspaceRoot = process.env.QM_WORKSPACE_ROOT ?? process.cwd();
+const REQUEST_TIMEOUT_MS = 2_000;
 
-  let port: number;
+function readPortFile(workspaceRoot: string) {
   try {
-    const hash = workspaceHash(workspaceRoot);
-    const portFile = join(tmpdir(), `quickmock-${hash}.port`);
-    port = parseInt(readFileSync(portFile, 'utf-8').trim(), 10);
-    if (Number.isNaN(port)) {
-      return nullClient;
-    }
+    const raw = readFileSync(buildPortFilePath(workspaceRoot), 'utf-8');
+    return parsePortFile(raw);
   } catch {
-    return nullClient;
+    return null;
   }
+}
+
+/** HTTP client for the VSCode extension's registry server. Falls back to nullClient when the extension is not running. */
+export function createRegistryClient(): RegistryClient {
+  const workspaceRoot = process.env.QM_WORKSPACE_ROOT ?? process.cwd();
+  const portFile = readPortFile(workspaceRoot);
+  if (!portFile) return nullClient;
+  const { port, token } = portFile;
 
   return {
     async getDocument(fsPath: string): Promise<string | null> {
       try {
-        const url = `http://127.0.0.1:${port}/document?path=${encodeURIComponent(fsPath)}`;
-        const res = await fetch(url, { signal: AbortSignal.timeout(2_000) });
-        if (!res.ok) {
-          return null;
-        }
+        const url = `http://${LOOPBACK_HOST}:${port}${DOCUMENT_ROUTE}?path=${encodeURIComponent(fsPath)}`;
+        const res = await fetch(url, {
+          headers: { [TOKEN_HEADER]: token },
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok) return null;
         return await res.text();
       } catch {
         return null;

packages/mcp/src/core/registry.client.ts

@@ -0,0 +1,16 @@
+{
+  "name": "@lemoncode/quickmock-registry-protocol",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@lemoncode/typescript-config": "*",
+    "@types/node": "^22.19.17"
+  }
+}

packages/mcp/src/core/registry.utils.ts

@@ -0,0 +1,4 @@
+export const TOKEN_HEADER = 'x-quickmock-token';
+export const LOOPBACK_HOST = '127.0.0.1';
+export const DOCUMENT_ROUTE = '/document';
+export const PORT_TOKEN_SEPARATOR = ' ';

packages/registry-protocol/package.json

@@ -0,0 +1,2 @@
+export * from './consts';
+export * from './utils';

packages/registry-protocol/src/consts.ts

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PORT_TOKEN_SEPARATOR } from './consts';
+
+const WORKSPACE_HASH_LENGTH = 8;
+
+export function buildPortFilePath(workspaceRoot: string): string {
+  const hash = createHash('md5')
+    .update(workspaceRoot)
+    .digest('hex')
+    .slice(0, WORKSPACE_HASH_LENGTH);
+  return join(tmpdir(), `quickmock-${hash}.port`);
+}
+
+export function encodePortFile(port: number, token: string): string {
+  return `${port}${PORT_TOKEN_SEPARATOR}${token}`;
+}
+
+export function parsePortFile(
+  raw: string
+): { port: number; token: string } | null {
+  const [portStr, token] = raw.trim().split(PORT_TOKEN_SEPARATOR);
+  const port = parseInt(portStr ?? '', 10);
+  if (Number.isNaN(port) || !token) return null;
+  return { port, token };
+}

packages/registry-protocol/src/index.ts

@@ -0,0 +1,11 @@
+{
+  "extends": "@lemoncode/typescript-config/base",
+  "include": ["src"],
+  "compilerOptions": {
+    "target": "ES2024",
+    "types": ["node"],
+    "lib": ["ES2024"],
+    "noEmit": true,
+    "rootDir": "src"
+  }
+}