@chen-rmag/core-infra 1.0.0

package/src/mcp/mcp-manager.ts

@@ -0,0 +1,118 @@
+import { MCPClient, MCPTool } from '@ai-test/core-infra/src/mcp/mcp-client';
+import { FileMCPManager } from '@ai-test/core-infra/src/mcp/file-mcp-manager';
+import { PlaywrightMCPManager } from '@ai-test/core-infra/src/mcp/playwright-mcp-manager';
+import { GroupedMCPManager } from '@ai-test/core-infra/src/mcp';
+
+export interface ToolGroupInfo {
+    groupId: string;
+    description: string;
+}
+
+export class MCPManager {
+    private managers: GroupedMCPManager[] = [];
+    private connected: boolean = false;
+    private language: string = 'zh-CN';
+
+    getManagers(): GroupedMCPManager[] {
+        return this.managers;
+    }
+
+    getClient(groupName: string): MCPClient {
+        for (const manager of this.managers) {
+            if (manager.getToolGroupInfo()[groupName]) {
+                return manager.getClient();
+            }
+        }
+
+        throw new Error(`MCP Client for group ${groupName} is not found`);
+    }
+
+    async start(language: string, forced: boolean = false): Promise<void> {
+        const playwrightClient = new PlaywrightMCPManager({ language: language });
+        const fileClient = new FileMCPManager();
+        this.managers = [playwrightClient, fileClient];
+        if (language !== this.language) {
+            forced = true;
+        }
+        this.language = language;
+
+        await Promise.all(this.managers.map(manager => manager.start(forced)));
+        this.connected = true;
+    }
+
+    async stop() {
+        for (const manager of this.managers) {
+            try {
+                await manager.getClient().disconnect();
+            } catch (error) {
+                console.error(`Error disconnecting MCP Client:`, error);
+            }
+        }
+        this.connected = false;
+    }
+
+    isConnected(): boolean {
+        return this.connected;
+    }
+
+    getToolGroupInfo(): ToolGroupInfo[] {
+        return this.managers.flatMap((manager) =>
+            manager.groups
+                .filter((group) => !group.loadByDefault)
+                .map((group) => ({
+                    groupId: group.name,
+                    description: group.description,
+                }))
+        );
+    }
+
+    getAllAvailableTools(): MCPTool[] {
+        let allTools: MCPTool[] = [];
+        for (const manager of this.managers) {
+            const tools = manager.getClient().getAvailableTools().filter(tool => {
+                return manager.groups.some(group => !group.tools || group.tools.includes(tool.name));
+            });
+            allTools = allTools.concat(tools);
+        }
+
+        return allTools;
+    }
+
+    getAvailableTools(groupName: string): MCPTool[] {
+        for (const manager of this.managers) {
+            const group = manager.groups.find(g => g.name === groupName);
+            if (group) {
+                const toolNames = group.tools;
+                const all = manager.getClient().getAvailableTools();
+                if (!toolNames) {
+                    return all;
+                }
+
+                return toolNames.filter(name => all.some(tool => tool.name === name)).map(name => all.find(tool => tool.name === name)!);
+            }
+        }
+
+        throw new Error(`Tool group ${groupName} not found`);
+    }
+
+
+    getDefaultTools(): MCPTool[] {
+        const allTools: MCPTool[] = [];
+        for (const manager of this.managers) {
+            for (const group of manager.groups) {
+                if (!group.loadByDefault || !group.tools) {
+                    continue;
+                }
+
+                const tools = manager.getClient().getAvailableTools();
+                for (const tool of tools) {
+                    if (group.tools.includes(tool.name)) {
+                        allTools.push(tool);
+                    }
+                }
+            }
+        }
+
+        return allTools;
+    }
+}

package/src/mcp/playwright-mcp-manager.ts

@@ -0,0 +1,127 @@
+/**
+ * MCP (Model Context Protocol) Client for Playwright integration
+ * Integrates with https://github.com/microsoft/playwright-mcp
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { MCPClient, MCPConfig } from './mcp-client';
+import { AbstractGroupedMCPManager } from '.';
+
+export interface PlaywrightMCPOpts {
+  language: string,
+  headless?: boolean,
+}
+
+export class PlaywrightMCPManager extends AbstractGroupedMCPManager {
+  private playwrightConfigPath?: string;
+  private playwrightConfigDir?: string;
+  private opts: PlaywrightMCPOpts;
+  private client?: MCPClient;
+
+  constructor(opts: PlaywrightMCPOpts) {
+    super([{
+      name: 'playwright_basic',
+      description: 'Basic Playwright tools for browser interactions',
+      tools: ['browser_navigate', 'browser_click', 'browser_fill_form', 'browser_press_key', 'browser_run_code', 'browser_select_option', 'browser_snapshot', 'browser_type', 'browser_wait_for'],
+      loadByDefault: true,
+    },
+    {
+      name: 'playwright_browser_manage',
+      description: `Playwright tools for browser and tab management, including: browser window resize, go back to previous page, close a page, list/create/close/select a tab`,
+      tools: ['browser_resize', 'browser_navigate_back', 'browser_close', 'browser_tabs'],
+      loadByDefault: false,
+    },
+    {
+      name: 'playwright_other',
+      description: 'Other Playwright tools for browser interactions, including: mouse hover on element, drag and drop an element, upload file, handle dialog, evaluate JavaScript on page or element',
+      tools: ['browser_hover', 'browser_drag', 'browser_file_upload', 'browser_handle_dialog', 'browser_evaluate'],
+      loadByDefault: false,
+    }
+    ]);
+    this.opts = opts;
+  }
+
+  async start(forced: boolean = false) {
+    this.prepareTempPlaywrightConfig(this.opts.language);
+    const client = this.createClient(this.opts);
+    this.client = client;
+    try {
+      await client.connect(forced);
+    } finally {
+      this.cleanupTempPlaywrightConfig();
+    }
+  }
+
+  getClient(): MCPClient {
+    if (!this.client) {
+      throw new Error("MCP Client is not started yet");
+    }
+    return this.client;
+  }
+
+  private createClient(opts: PlaywrightMCPOpts): MCPClient {
+    // Build args with headless mode
+    const args = [
+      '@cotestdev/mcp_playwright@latest',
+      '--image-responses', 'omit',
+      '--caps',
+      'core,core-tabs,extra'
+    ];
+
+    if (this.playwrightConfigPath) {
+      args.push('--config', this.playwrightConfigPath);
+    }
+
+    // Explicitly set headless or headed mode
+    // Playwright MCP requires explicit declaration of the mode
+    if (opts.headless) {
+      args.push('--headless');
+      console.log('Browser will run in HEADLESS mode (background)');
+    } else {
+      console.log('Browser will run in HEADED mode (visible window)');
+    }
+
+    const mcpConfig: MCPConfig = {
+      cmd: 'npx',
+      args: args,
+      env: { ...process.env } as Record<string, string>,
+    }
+
+    return new MCPClient(mcpConfig);
+  }
+
+  private prepareTempPlaywrightConfig(language: string) {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'playwright-mcp-'));
+    const configPath = path.join(tempDir, 'mcp.config.json');
+
+    const configContents = `
+{
+  "browser": {
+    "contextOptions": {
+      "locale": "${language}"
+    }
+  }
+}
+`;
+
+    fs.writeFileSync(configPath, configContents, 'utf8');
+
+    this.playwrightConfigDir = tempDir;
+    this.playwrightConfigPath = configPath;
+    console.log('Temporary Playwright config created at', configPath);
+  }
+
+  private cleanupTempPlaywrightConfig(): void {
+    if (!this.playwrightConfigDir) return;
+
+    try {
+      fs.rmSync(this.playwrightConfigDir, { recursive: true, force: true });
+    } catch (error) {
+      console.error('Failed to remove temporary Playwright config directory:', error);
+    } finally {
+      this.playwrightConfigDir = undefined;
+      this.playwrightConfigPath = undefined;
+    }
+  }
+}

package/src/model.ts

@@ -0,0 +1,234 @@
+import { ModelConfig } from "./types";
+import { BaseLanguageModel } from "@langchain/core/language_models/base";
+import { ChatOpenAI } from '@langchain/openai';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { ChatMistralAI } from '@langchain/mistralai';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import z from "zod";
+import { MCPManager } from "./mcp/mcp-manager";
+
+export function createModel(
+    config: ModelConfig,
+    bindTools: boolean = false,
+    mcpManager?: MCPManager,
+    useDefaultFuncs: boolean = false,
+): BaseLanguageModel {
+    let model: BaseLanguageModel;
+
+    if (config.provider === 'openai') {
+        const openaiConfig = {
+            apiKey: config.apiKey,
+            model: config.modelName || 'gpt-4-turbo',
+            ...config,
+        };
+
+        if (config.baseURL) {
+            (openaiConfig as Record<string, unknown>).configuration = {
+                baseURL: config.baseURL,
+            };
+        }
+
+        model = new ChatOpenAI(openaiConfig as Record<string, unknown>);
+    } else if (config.provider === 'anthropic') {
+        const anthropicConfig = {
+            apiKey: config.apiKey,
+            model: config.modelName || 'claude-3-sonnet-20240229',
+            anthropicApiUrl: config.baseURL,
+            clientOptions: {
+                baseURL: config.baseURL,
+                apiKey: config.apiKey,
+            },
+            ...config,
+        };
+
+        model = new ChatAnthropic(anthropicConfig as Record<string, unknown>);
+    } else if (config.provider === 'mistral') {
+        // Mistral uses ChatMistralAI package
+        const mistralConfig = {
+            apiKey: config.apiKey,
+            model: config.modelName || 'mistral-large-latest',
+            ...config,
+        };
+
+        model = new ChatMistralAI(mistralConfig as Record<string, unknown>);
+    } else if (config.provider === 'openrouter') {
+        // OpenRouter uses OpenAI-compatible API
+        const openrouterBaseURL = config.baseURL;
+        const openrouterConfig = {
+            apiKey: config.apiKey,
+            model: config.modelName,
+            configuration: { baseURL: openrouterBaseURL },
+            ...config,
+        };
+
+        model = new ChatOpenAI(openrouterConfig as Record<string, unknown>);
+    } else if (config.provider === 'ollama') {
+        const baseURL = config.baseURL || 'http://localhost:11434';
+        model = new ChatOpenAI({
+            apiKey: 'ollama',
+            model: config.modelName || 'llama2',
+            configuration: { baseURL },
+            ...config,
+        } as Record<string, unknown>);
+    } else {
+        throw new Error(`Unknown model provider: ${config.provider}`);
+    }
+
+    if (bindTools && mcpManager) {
+        model = bindPlaywrightTools(model, mcpManager, useDefaultFuncs);
+    }
+
+    return model;
+}
+
+/**
+ * Bind Playwright MCP tools to the model
+ * Creates LangChain tools from MCP tool definitions
+ */
+function bindPlaywrightTools(model: BaseLanguageModel, mcpManager: MCPManager, useDefaultFuncs: boolean): BaseLanguageModel {
+    const defaultTools = mcpManager.getDefaultTools();
+    // Convert MCP tools to LangChain tools (ensure each tool has its own JSON-schema-as-Zod schema)
+    const langchainTools: DynamicStructuredTool[] = defaultTools.map(mcpTool => {
+        const schema = convertToZodSchema(mcpTool.inputSchema || {});
+        return new DynamicStructuredTool({
+            name: mcpTool.name,
+            description: mcpTool.description,
+            schema,
+            func: async (input, runner, config) => {
+                const abortSignal = config?.signal ?? new AbortController().signal;
+                for (const manager of mcpManager.getManagers()) {
+                    const tool = manager.getClient().getToolByName(mcpTool.name);
+                    if (tool) {
+                        return manager.getClient().doCallTool(mcpTool.name, input as Record<string, unknown>, abortSignal);
+                    }
+                }
+            },
+        });
+    });
+
+    if (useDefaultFuncs) {
+        const finishTool = {
+            name: "finish_test",
+            description: "Call this tool ONLY when the test goal has been fully achieved or failed to achieve. After calling this, no more tools should be called.",
+            schema: z.object({
+                final_summary: z.optional(z.string()).describe("A brief summary confirming the test goal was achieved."),
+            }),
+            func: async () => { },
+        }
+        const getToolGroupsTool = {
+            name: "get_tools",
+            description: "Get available tools in a group.",
+            schema: z.object({
+                group_name: z.string().describe("The name of the tool group."),
+            }),
+            func: async () => {
+            },
+        }
+        const callToolTool = {
+            name: "call_tool",
+            description: "Call a tool in a group by name.",
+            schema: z.object({
+                group_name: z.string().describe("Tool group name."),
+                tool_name: z.string().describe("Tool name."),
+                args: z.object().describe("Tool parameters."),
+            }),
+            func: async () => {
+            },
+        }
+        const reuseTestTool = {
+            name: "reuse_test",
+            description: "Reuse a test from the provided reusable tests.",
+            schema: z.object({
+                id: z.string().describe("ID of the reusable test."),
+                args: z.object().describe("Reusable test"),
+            }),
+            func: async () => {
+            },
+        }
+        langchainTools.push(new DynamicStructuredTool(finishTool), new DynamicStructuredTool(callToolTool), new DynamicStructuredTool(getToolGroupsTool), new DynamicStructuredTool(reuseTestTool));
+    }
+
+    // For models that support tool binding (OpenAI, Anthropic), bind the tools
+    // Note: Not all models support bindTools(), so we skip it if not available
+    const modelAny = model as BaseChatModel;
+    if (modelAny && typeof modelAny.bindTools === 'function') {
+        // Force the model to use tools with tool_choice: 'required'
+        // This ensures the model will always invoke a tool rather than responding directly
+        // Only OpenAI and Anthropic fully support this parameter
+
+        return modelAny.bindTools(langchainTools, {
+            tool_choice: 'required',
+        }) as BaseLanguageModel;
+    }
+
+    return model;
+}
+
+
+/**
+ * Convert a plain object schema to a Zod schema
+ * Handles conversion of MCP tool input schemas to LangChain-compatible Zod types
+ */
+export function convertToZodSchema(
+    schema: Record<string, unknown>
+): z.ZodType {
+    // If schema is already a Zod type, return it
+    if (schema instanceof z.ZodType) {
+        return schema;
+    }
+
+    // Handle JSON Schema format (common from MCP tools)
+    if (schema.type === 'object' && schema.properties) {
+        const properties: Record<string, z.ZodTypeAny> = {};
+
+        const props = schema.properties as Record<string, unknown>;
+        const required = (schema.required as string[]) || [];
+
+        for (const [key, value] of Object.entries(props)) {
+            const propSchema = value as Record<string, unknown>;
+            const zodType = convertPropertyToZod(propSchema);
+
+            if (required.includes(key)) {
+                properties[key] = zodType;
+            } else {
+                properties[key] = zodType.optional();
+            }
+        }
+
+        return z.object(properties);
+    }
+
+    /**
+   * Convert a single property schema to Zod type
+   */
+    function convertPropertyToZod(schema: Record<string, unknown>): z.ZodTypeAny {
+        const type = schema.type as string;
+
+        switch (type) {
+            case 'string':
+                return z.string().describe((schema.description as string) || '');
+
+            case 'number':
+            case 'integer':
+                return z.number().describe((schema.description as string) || '');
+
+            case 'boolean':
+                return z.boolean().describe((schema.description as string) || '');
+
+            case 'array':
+                const items = schema.items as Record<string, unknown>;
+                const itemType = items ? convertPropertyToZod(items) : z.any();
+                return z.array(itemType).describe((schema.description as string) || '');
+
+            case 'object':
+                return z.object({}).catchall(z.any()).describe((schema.description as string) || '');
+
+            default:
+                return z.any();
+        }
+    }
+
+    // Fallback: accept any object with catchall
+    return z.object({}).catchall(z.any());
+}

package/src/repositories/BaseRepository.ts

@@ -0,0 +1,193 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { homedir } from 'os';
+import { writeFile, readFile, readdir, rm } from 'fs/promises';
+import path, { join } from 'path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from 'fs';
+
+/**
+ * Base repository class providing common file I/O operations
+ * Implements the base functionality for all data repositories
+ * 
+ * Supports project-isolated data storage:
+ * - When projectId is active: ~/.test_agent/projects/{projectId}/{subDir}/
+ * - When no project: ~/.test_agent/{subDir}/
+ */
+export abstract class BaseRepository {
+  protected storageDir: string;
+  protected subDir: string;
+  protected explicitProjectId?: string;
+
+  constructor(subDir: string) {
+    this.storageDir = join(homedir(), '.test_agent');
+    this.subDir = subDir;
+    this.ensureDir();
+  }
+
+  /**
+   * Ensure the subdirectory exists
+   */
+  protected ensureDir(): void {
+    const dirPath = this.getBaseDir();
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+  }
+
+  /**
+   * Get the base directory for this repository
+   * When a project is active:
+   *   - For 'projects': returns ~/.test_agent/projects (projects.json location)
+   *   - For other repos: returns ~/.test_agent/projects/{projectId}/{subDir}
+   * When no project:
+   *   - returns ~/.test_agent/{subDir}
+   */
+  protected getBaseDir(): string {
+    // Global directory: ~/.test_agent/{subDir}
+    return join(this.storageDir, this.subDir);
+  }
+
+  /**
+   * Get full file path for a specific ID
+   */
+  protected getFilePath(id: string, extension: string = 'json'): string {
+    return join(this.getBaseDir(), `${id}.${extension}`);
+  }
+
+  /**
+   * Save data to file (synchronous)
+   */
+  protected saveSync(id: string, data: unknown, extension: string = 'json'): void {
+    const filePath = this.getFilePath(id, extension);
+    try {
+      this.createDirectoriesRecursively(filePath);
+    } catch (error) {
+    }
+    writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  private createDirectoriesRecursively(targetPath: string): void {
+    // If target path is a file path, get its parent directory; otherwise, use target path as directory
+    const dir = path.extname(targetPath) ? path.dirname(targetPath) : targetPath;
+
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Save data to file (asynchronous)
+   */
+  protected async save(id: string, data: unknown, extension: string = 'json'): Promise<void> {
+    const filePath = this.getFilePath(id, extension);
+    await writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  /**
+   * Load data from file (synchronous)
+   */
+  protected loadSync<T>(id: string, extension: string = 'json'): T | null {
+    const filePath = this.getFilePath(id, extension);
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    return JSON.parse(content) as T;
+  }
+
+  /**
+   * Load data from file (asynchronous)
+   */
+  protected async load<T>(id: string, extension: string = 'json'): Promise<T | null> {
+    const filePath = this.getFilePath(id, extension);
+    try {
+      const content = await readFile(filePath, 'utf-8');
+      return JSON.parse(content) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * List all files in the directory
+   */
+  protected async listAll<T>(filter?: (filename: string) => boolean): Promise<T[]> {
+    const dirPath = this.getBaseDir();
+    try {
+      const files = await readdir(dirPath);
+      const results: T[] = [];
+
+      for (const file of files) {
+        if (filter && !filter(file)) {
+          continue;
+        }
+        if (!file.endsWith('.json')) {
+          continue;
+        }
+        const filePath = join(dirPath, file);
+        const content = await readFile(filePath, 'utf-8');
+        results.push(JSON.parse(content) as T);
+      }
+
+      return results;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * List all files synchronously
+   */
+  protected listAllSync<T>(filter?: (filename: string) => boolean): T[] {
+    const dirPath = this.getBaseDir();
+    try {
+      const files = readdirSync(dirPath);
+      const results: T[] = [];
+
+      for (const file of files) {
+        if (filter && !filter(file)) {
+          continue;
+        }
+        if (!file.endsWith('.json')) {
+          continue;
+        }
+        const filePath = join(dirPath, file);
+        const content = readFileSync(filePath, 'utf-8');
+        results.push(JSON.parse(content) as T);
+      }
+
+      return results;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Delete a file (synchronous)
+   */
+  protected deleteSync(id: string, extension: string = 'json'): void {
+    const filePath = this.getFilePath(id, extension);
+    if (existsSync(filePath)) {
+      rmSync(filePath);
+    }
+  }
+
+  /**
+   * Delete a file (asynchronous)
+   */
+  protected async delete(id: string, extension: string = 'json'): Promise<void> {
+    const filePath = this.getFilePath(id, extension);
+    try {
+      await rm(filePath);
+    } catch {
+      // File doesn't exist, ignore error
+    }
+  }
+
+  /**
+   * Check if file exists
+   */
+  protected existsSync(id: string, extension: string = 'json'): boolean {
+    const filePath = this.getFilePath(id, extension);
+    return existsSync(filePath);
+  }
+}