@lunatest/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin/mcp-stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/mcp-stdio.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { createMcpServer } from "../server.js";
+import { runStdioServer } from "../transport/stdio.js";
+const server = createMcpServer({
+    scenarios: [],
+});
+runStdioServer({
+    input: process.stdin,
+    output: process.stdout,
+    error: process.stderr,
+    server,
+}).catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});

package/dist/generation/combinatorial.d.ts

@@ -0,0 +1,2 @@
+export type CombinationSpace = Record<string, unknown[]>;
+export declare function generate(space: CombinationSpace, limit?: number): Array<Record<string, unknown>>;

package/dist/generation/combinatorial.js

@@ -0,0 +1,37 @@
+export function generate(space, limit = 256) {
+    const keys = Object.keys(space);
+    if (keys.length === 0) {
+        return [];
+    }
+    const combos = [];
+    const visit = (depth, acc) => {
+        if (combos.length >= limit) {
+            return;
+        }
+        if (depth === keys.length) {
+            combos.push({ ...acc });
+            return;
+        }
+        const key = keys[depth];
+        if (!key) {
+            return;
+        }
+        const values = space[key] ?? [];
+        if (values.length === 0) {
+            acc[key] = undefined;
+            visit(depth + 1, acc);
+            delete acc[key];
+            return;
+        }
+        for (const value of values) {
+            if (combos.length >= limit) {
+                return;
+            }
+            acc[key] = value;
+            visit(depth + 1, acc);
+        }
+        delete acc[key];
+    };
+    visit(0, {});
+    return combos;
+}

package/dist/generation/mutator.d.ts

@@ -0,0 +1,5 @@
+import type { ScenarioDescriptor } from "../tools/scenario.js";
+export declare function mutateValues(lua: string, variantIndex: number): string;
+export declare function mutateStages(lua: string, variantIndex: number): string;
+export declare function mutateMocks(lua: string, variantIndex: number): string;
+export declare function mutateScenarioVariants(source: ScenarioDescriptor, count: number): ScenarioDescriptor[];

package/dist/generation/mutator.js

@@ -0,0 +1,51 @@
+function mutateNumericToken(token, delta) {
+    const asNumber = Number(token);
+    if (!Number.isFinite(asNumber)) {
+        return token;
+    }
+    return String(asNumber + delta);
+}
+export function mutateValues(lua, variantIndex) {
+    let replaced = false;
+    const next = lua.replace(/\b\d+(?:\.\d+)?\b/g, (token) => {
+        if (replaced) {
+            return token;
+        }
+        replaced = true;
+        return mutateNumericToken(token, variantIndex);
+    });
+    if (replaced) {
+        return next;
+    }
+    return `${lua}\n-- value mutation ${variantIndex}`;
+}
+export function mutateStages(lua, variantIndex) {
+    if (!lua.includes("stages")) {
+        return lua;
+    }
+    return `${lua}\n-- stage-order mutation ${variantIndex}`;
+}
+export function mutateMocks(lua, variantIndex) {
+    if (!lua.includes("given")) {
+        return lua;
+    }
+    return `${lua}\n-- mock-state mutation ${variantIndex}`;
+}
+export function mutateScenarioVariants(source, count) {
+    const variants = [];
+    for (let index = 1; index <= count; index += 1) {
+        const variantLua = source.lua
+            ? mutateMocks(mutateStages(mutateValues(source.lua, index), index), index)
+            : undefined;
+        const variant = {
+            ...source,
+            id: `${source.id}-mut-${index}`,
+            name: `${source.name} mutation ${index}`,
+        };
+        if (variantLua !== undefined) {
+            variant.lua = variantLua;
+        }
+        variants.push(variant);
+    }
+    return variants;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createMcpServer } from "./server.js";
+export { createCoverageTools } from "./tools/coverage.js";
+export { createComponentTools } from "./tools/component.js";
+export { createMockTools } from "./tools/mock.js";
+export { createScenarioTools } from "./tools/scenario.js";
+export { generate } from "./generation/combinatorial.js";
+export { mutateMocks, mutateScenarioVariants, mutateStages, mutateValues } from "./generation/mutator.js";
+export { createResourceCatalog } from "./resources/index.js";
+export { createPromptCatalog } from "./prompts/index.js";
+export { parseJsonRpcLine, processJsonRpcLine, runStdioServer } from "./transport/stdio.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createMcpServer } from "./server.js";
+export { createCoverageTools } from "./tools/coverage.js";
+export { createComponentTools } from "./tools/component.js";
+export { createMockTools } from "./tools/mock.js";
+export { createScenarioTools } from "./tools/scenario.js";
+export { generate } from "./generation/combinatorial.js";
+export { mutateMocks, mutateScenarioVariants, mutateStages, mutateValues } from "./generation/mutator.js";
+export { createResourceCatalog } from "./resources/index.js";
+export { createPromptCatalog } from "./prompts/index.js";
+export { parseJsonRpcLine, processJsonRpcLine, runStdioServer } from "./transport/stdio.js";

package/dist/prompts/analyze-failure.d.ts

@@ -0,0 +1 @@
+export declare function analyzeFailurePrompt(diff: string): string;

package/dist/prompts/analyze-failure.js

@@ -0,0 +1,3 @@
+export function analyzeFailurePrompt(diff) {
+    return `Analyze this deterministic failure diff and identify root cause:\n${diff}`;
+}

package/dist/prompts/generate-edge-cases.d.ts

@@ -0,0 +1 @@
+export declare function generateEdgeCasesPrompt(component: string): string;

package/dist/prompts/generate-edge-cases.js

@@ -0,0 +1,3 @@
+export function generateEdgeCasesPrompt(component) {
+    return `Generate deterministic edge-case scenarios for ${component} using given/when/then_ui format.`;
+}

package/dist/prompts/improve-coverage.d.ts

@@ -0,0 +1 @@
+export declare function improveCoveragePrompt(gaps: string[]): string;

package/dist/prompts/improve-coverage.js

@@ -0,0 +1,3 @@
+export function improveCoveragePrompt(gaps) {
+    return `Suggest scenarios to cover these gaps: ${gaps.join(", ")}`;
+}

package/dist/prompts/index.d.ts

@@ -0,0 +1,5 @@
+export type PromptTemplate = {
+    id: string;
+    render: (input: string | string[]) => string;
+};
+export declare function createPromptCatalog(): PromptTemplate[];

package/dist/prompts/index.js

@@ -0,0 +1,24 @@
+import { analyzeFailurePrompt } from "./analyze-failure.js";
+import { generateEdgeCasesPrompt } from "./generate-edge-cases.js";
+import { improveCoveragePrompt } from "./improve-coverage.js";
+import { regressionFromDiffPrompt } from "./regression-from-diff.js";
+export function createPromptCatalog() {
+    return [
+        {
+            id: "generate-edge-cases",
+            render: (input) => generateEdgeCasesPrompt(String(input)),
+        },
+        {
+            id: "analyze-failure",
+            render: (input) => analyzeFailurePrompt(String(input)),
+        },
+        {
+            id: "improve-coverage",
+            render: (input) => improveCoveragePrompt(Array.isArray(input) ? input : [String(input)]),
+        },
+        {
+            id: "regression-from-diff",
+            render: (input) => regressionFromDiffPrompt(String(input)),
+        },
+    ];
+}

package/dist/prompts/regression-from-diff.d.ts

@@ -0,0 +1 @@
+export declare function regressionFromDiffPrompt(diffSummary: string): string;

package/dist/prompts/regression-from-diff.js

@@ -0,0 +1,3 @@
+export function regressionFromDiffPrompt(diffSummary) {
+    return `Generate regression scenarios from this code diff summary:\n${diffSummary}`;
+}

package/dist/resources/components.d.ts

@@ -0,0 +1,4 @@
+export declare function componentsResource(tree: unknown): {
+    uri: string;
+    content: unknown;
+};

package/dist/resources/components.js

@@ -0,0 +1,6 @@
+export function componentsResource(tree) {
+    return {
+        uri: "lunatest://components",
+        content: tree,
+    };
+}

package/dist/resources/coverage.d.ts

@@ -0,0 +1,4 @@
+export declare function coverageResource(report: Record<string, unknown>): {
+    uri: string;
+    content: Record<string, unknown>;
+};

package/dist/resources/coverage.js

@@ -0,0 +1,6 @@
+export function coverageResource(report) {
+    return {
+        uri: "lunatest://coverage",
+        content: report,
+    };
+}

package/dist/resources/guide.d.ts

@@ -0,0 +1,7 @@
+export declare function guideResource(): {
+    uri: string;
+    content: {
+        title: string;
+        sections: string[];
+    };
+};

package/dist/resources/guide.js

@@ -0,0 +1,13 @@
+export function guideResource() {
+    return {
+        uri: "lunatest://guide",
+        content: {
+            title: "LunaTest Scenario Guide",
+            sections: [
+                "Define given state first",
+                "Describe action in when.action",
+                "Assert ui/state deterministically",
+            ],
+        },
+    };
+}

package/dist/resources/index.d.ts

@@ -0,0 +1,11 @@
+import type { ScenarioDescriptor } from "../tools/scenario.js";
+export type McpResource = {
+    uri: string;
+    content: unknown;
+};
+export declare function createResourceCatalog(options: {
+    scenarios: ScenarioDescriptor[];
+    coverage: Record<string, unknown>;
+    components: unknown;
+    protocols: string[];
+}): McpResource[];

package/dist/resources/index.js

@@ -0,0 +1,16 @@
+import { componentsResource } from "./components.js";
+import { coverageResource } from "./coverage.js";
+import { guideResource } from "./guide.js";
+import { mocksResource } from "./mocks.js";
+import { protocolsResource } from "./protocols.js";
+import { scenariosResource } from "./scenarios.js";
+export function createResourceCatalog(options) {
+    return [
+        scenariosResource(options.scenarios),
+        coverageResource(options.coverage),
+        componentsResource(options.components),
+        mocksResource(),
+        protocolsResource(options.protocols),
+        guideResource(),
+    ];
+}

package/dist/resources/mocks.d.ts

@@ -0,0 +1,10 @@
+export declare function mocksResource(): {
+    uri: string;
+    content: {
+        schema: {
+            chain: string[];
+            wallet: string[];
+            events: string[];
+        };
+    };
+};

package/dist/resources/mocks.js

@@ -0,0 +1,12 @@
+export function mocksResource() {
+    return {
+        uri: "lunatest://mocks",
+        content: {
+            schema: {
+                chain: ["id", "blockNumber"],
+                wallet: ["address", "balances", "allowances"],
+                events: ["atMs", "type", "payload"],
+            },
+        },
+    };
+}

package/dist/resources/protocols.d.ts

@@ -0,0 +1,4 @@
+export declare function protocolsResource(protocols: string[]): {
+    uri: string;
+    content: string[];
+};

package/dist/resources/protocols.js

@@ -0,0 +1,6 @@
+export function protocolsResource(protocols) {
+    return {
+        uri: "lunatest://protocols",
+        content: protocols,
+    };
+}

package/dist/resources/scenarios.d.ts

@@ -0,0 +1,5 @@
+import type { ScenarioDescriptor } from "../tools/scenario.js";
+export declare function scenariosResource(scenarios: ScenarioDescriptor[]): {
+    uri: string;
+    content: ScenarioDescriptor[];
+};

package/dist/resources/scenarios.js

@@ -0,0 +1,6 @@
+export function scenariosResource(scenarios) {
+    return {
+        uri: "lunatest://scenarios",
+        content: scenarios,
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,36 @@
+import { type ScenarioDescriptor } from "./tools/scenario.js";
+import type { ExecuteLuaScenarioInput } from "@lunatest/core";
+type JsonRpcRequest = {
+    id: string;
+    method: string;
+    params?: Record<string, unknown>;
+};
+type JsonRpcResponse = {
+    id: string;
+    result?: unknown;
+    error?: {
+        message: string;
+    };
+};
+type McpServerOptions = {
+    scenarios?: ScenarioDescriptor[];
+    coverage?: {
+        total?: number;
+        covered?: number;
+        ratio?: number;
+    };
+    mockState?: Record<string, unknown>;
+    componentTree?: Array<{
+        name: string;
+        children?: Array<{
+            name: string;
+        }>;
+    }>;
+    componentStates?: Record<string, string[]>;
+    protocols?: string[];
+    scenarioAdapter?: ExecuteLuaScenarioInput["adapter"];
+};
+export declare function createMcpServer(options: McpServerOptions): {
+    handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse>;
+};
+export {};

package/dist/server.js

@@ -0,0 +1,205 @@
+import { createPromptCatalog } from "./prompts/index.js";
+import { createResourceCatalog } from "./resources/index.js";
+import { createComponentTools } from "./tools/component.js";
+import { createCoverageTools } from "./tools/coverage.js";
+import { createMockTools } from "./tools/mock.js";
+import { createScenarioTools, } from "./tools/scenario.js";
+export function createMcpServer(options) {
+    const scenarioTools = createScenarioTools(options.scenarios ?? [], {
+        adapter: options.scenarioAdapter,
+    });
+    const coverageTools = createCoverageTools(options.coverage);
+    const mockTools = createMockTools(options.mockState);
+    const componentTools = createComponentTools(options.componentTree ?? [], options.componentStates ?? {});
+    const prompts = createPromptCatalog();
+    const getResources = async () => {
+        const scenarios = await scenarioTools.list();
+        const coverage = await coverageTools.report();
+        const components = await componentTools.tree();
+        return createResourceCatalog({
+            scenarios,
+            coverage,
+            components,
+            protocols: options.protocols ?? ["uniswap_v2", "uniswap_v3", "curve", "aave"],
+        });
+    };
+    return {
+        async handleRequest(request) {
+            try {
+                if (request.method === "scenario.list") {
+                    return {
+                        id: request.id,
+                        result: await scenarioTools.list(),
+                    };
+                }
+                if (request.method === "scenario.get") {
+                    return {
+                        id: request.id,
+                        result: await scenarioTools.get(String(request.params?.id ?? "")),
+                    };
+                }
+                if (request.method === "scenario.create") {
+                    return {
+                        id: request.id,
+                        result: await scenarioTools.create({
+                            id: request.params?.id === undefined
+                                ? undefined
+                                : String(request.params.id),
+                            name: request.params?.name === undefined
+                                ? undefined
+                                : String(request.params.name),
+                            lua: request.params?.lua === undefined
+                                ? undefined
+                                : String(request.params.lua),
+                        }),
+                    };
+                }
+                if (request.method === "scenario.run") {
+                    return {
+                        id: request.id,
+                        result: await scenarioTools.run({
+                            id: request.params?.id === undefined
+                                ? undefined
+                                : String(request.params.id),
+                            lua: request.params?.lua === undefined
+                                ? undefined
+                                : String(request.params.lua),
+                        }),
+                    };
+                }
+                if (request.method === "scenario.runAll") {
+                    return {
+                        id: request.id,
+                        result: await scenarioTools.runAll(request.params?.filter === undefined
+                            ? undefined
+                            : String(request.params.filter)),
+                    };
+                }
+                if (request.method === "scenario.mutate") {
+                    return {
+                        id: request.id,
+                        result: await scenarioTools.mutate({
+                            id: String(request.params?.id ?? ""),
+                            count: request.params?.count === undefined
+                                ? undefined
+                                : Number(request.params.count),
+                        }),
+                    };
+                }
+                if (request.method === "coverage.report") {
+                    return {
+                        id: request.id,
+                        result: await coverageTools.report(),
+                    };
+                }
+                if (request.method === "coverage.gaps") {
+                    return {
+                        id: request.id,
+                        result: await coverageTools.gaps(),
+                    };
+                }
+                if (request.method === "coverage.suggest") {
+                    return {
+                        id: request.id,
+                        result: await coverageTools.suggest(),
+                    };
+                }
+                if (request.method === "mock.getState") {
+                    return {
+                        id: request.id,
+                        result: await mockTools.getState(),
+                    };
+                }
+                if (request.method === "mock.setState") {
+                    return {
+                        id: request.id,
+                        result: await mockTools.setState(request.params?.state ?? {}),
+                    };
+                }
+                if (request.method === "state.patch") {
+                    return {
+                        id: request.id,
+                        result: await mockTools.patchState(request.params?.state ?? {}),
+                    };
+                }
+                if (request.method === "mock.routes.set") {
+                    return {
+                        id: request.id,
+                        result: await mockTools.setRoutes(request.params?.routes ?? []),
+                    };
+                }
+                if (request.method === "mock.routes.get") {
+                    return {
+                        id: request.id,
+                        result: await mockTools.getRoutes(),
+                    };
+                }
+                if (request.method === "mock.listPresets") {
+                    return {
+                        id: request.id,
+                        result: await mockTools.listPresets(),
+                    };
+                }
+                if (request.method === "component.tree") {
+                    return {
+                        id: request.id,
+                        result: await componentTools.tree(),
+                    };
+                }
+                if (request.method === "component.states") {
+                    return {
+                        id: request.id,
+                        result: await componentTools.states(String(request.params?.name ?? "")),
+                    };
+                }
+                if (request.method === "resource.list") {
+                    const resources = await getResources();
+                    return {
+                        id: request.id,
+                        result: resources.map((resource) => resource.uri),
+                    };
+                }
+                if (request.method === "resource.get") {
+                    const target = String(request.params?.uri ?? "");
+                    const resources = await getResources();
+                    return {
+                        id: request.id,
+                        result: resources.find((resource) => resource.uri === target) ?? null,
+                    };
+                }
+                if (request.method === "prompt.list") {
+                    return {
+                        id: request.id,
+                        result: prompts.map((prompt) => prompt.id),
+                    };
+                }
+                if (request.method === "prompt.get") {
+                    const target = String(request.params?.id ?? "");
+                    const prompt = prompts.find((item) => item.id === target);
+                    if (!prompt) {
+                        throw new Error(`Prompt not found: ${target}`);
+                    }
+                    const input = request.params?.input;
+                    const normalizedInput = input === undefined || input === null ? "" : input;
+                    return {
+                        id: request.id,
+                        result: {
+                            id: prompt.id,
+                            text: prompt.render(normalizedInput),
+                        },
+                    };
+                }
+                throw new Error(`Unsupported method: ${request.method}`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    id: request.id,
+                    error: {
+                        message,
+                    },
+                };
+            }
+        },
+    };
+}

package/dist/tools/component.d.ts

@@ -0,0 +1,10 @@
+type ComponentStateMap = Record<string, string[]>;
+type ComponentNode = {
+    name: string;
+    children?: ComponentNode[];
+};
+export declare function createComponentTools(tree?: ComponentNode[], states?: ComponentStateMap): {
+    tree(): Promise<ComponentNode[]>;
+    states(name: string): Promise<string[]>;
+};
+export {};

package/dist/tools/component.js

@@ -0,0 +1,10 @@
+export function createComponentTools(tree = [], states = {}) {
+    return {
+        async tree() {
+            return tree;
+        },
+        async states(name) {
+            return states[name] ?? [];
+        },
+    };
+}

package/dist/tools/coverage.d.ts

@@ -0,0 +1,16 @@
+export type CoverageReport = {
+    total: number;
+    covered: number;
+    ratio: number;
+};
+export declare function createCoverageTools(seed?: Partial<CoverageReport>): {
+    report(): Promise<CoverageReport>;
+    gaps(): Promise<{
+        id: string;
+        reason: string;
+    }[]>;
+    suggest(): Promise<{
+        id: string;
+        title: string;
+    }[]>;
+};

package/dist/tools/coverage.js

@@ -0,0 +1,29 @@
+export function createCoverageTools(seed) {
+    const report = {
+        total: seed?.total ?? 0,
+        covered: seed?.covered ?? 0,
+        ratio: seed?.ratio ??
+            ((seed?.total ?? 0) === 0
+                ? 1
+                : Number(((seed?.covered ?? 0) / (seed?.total ?? 0)).toFixed(4))),
+    };
+    return {
+        async report() {
+            return report;
+        },
+        async gaps() {
+            const missing = Math.max(0, report.total - report.covered);
+            return Array.from({ length: missing }, (_, index) => ({
+                id: `gap-${index + 1}`,
+                reason: "scenario not covered",
+            }));
+        },
+        async suggest() {
+            const missing = Math.max(0, report.total - report.covered);
+            return Array.from({ length: missing }, (_, index) => ({
+                id: `suggestion-${index + 1}`,
+                title: `Add edge case scenario ${index + 1}`,
+            }));
+        },
+    };
+}

package/dist/tools/mock.d.ts

@@ -0,0 +1,8 @@
+export declare function createMockTools(initialState?: Record<string, unknown>): {
+    getState(): Promise<Record<string, unknown>>;
+    setState(next: Record<string, unknown>): Promise<Record<string, unknown>>;
+    patchState(partial: Record<string, unknown>): Promise<Record<string, unknown>>;
+    setRoutes(nextRoutes: Array<Record<string, unknown>>): Promise<Record<string, unknown>[]>;
+    getRoutes(): Promise<Record<string, unknown>[]>;
+    listPresets(): Promise<string[]>;
+};

package/dist/tools/mock.js

@@ -0,0 +1,29 @@
+import { deepClone, deepMerge } from "@lunatest/contracts";
+export function createMockTools(initialState = {}) {
+    let state = deepClone(initialState);
+    let routes = [];
+    const presets = ["uniswap_v2", "uniswap_v3", "curve", "aave"];
+    return {
+        async getState() {
+            return deepClone(state);
+        },
+        async setState(next) {
+            state = deepClone(next);
+            return deepClone(state);
+        },
+        async patchState(partial) {
+            state = deepMerge(state, partial);
+            return deepClone(state);
+        },
+        async setRoutes(nextRoutes) {
+            routes = deepClone(nextRoutes);
+            return deepClone(routes);
+        },
+        async getRoutes() {
+            return deepClone(routes);
+        },
+        async listPresets() {
+            return [...presets];
+        },
+    };
+}

package/dist/tools/scenario.d.ts

@@ -0,0 +1,44 @@
+import { type ExecuteLuaScenarioInput } from "@lunatest/core";
+export type ScenarioDescriptor = {
+    id: string;
+    name: string;
+    lua?: string;
+    tags?: string[];
+};
+type ScenarioCreateInput = {
+    id?: string;
+    name?: string;
+    lua?: string;
+    tags?: string[];
+};
+type ScenarioMutateInput = {
+    id: string;
+    count?: number;
+};
+type ScenarioRunInput = string | {
+    id?: string;
+    lua?: string;
+};
+export type ScenarioTools = {
+    list: () => Promise<ScenarioDescriptor[]>;
+    get: (id: string) => Promise<ScenarioDescriptor | null>;
+    create: (input: ScenarioCreateInput) => Promise<ScenarioDescriptor>;
+    run: (input: ScenarioRunInput) => Promise<{
+        id: string;
+        pass: boolean;
+        error?: string;
+        diff?: string;
+    }>;
+    runAll: (filter?: string) => Promise<Array<{
+        id: string;
+        pass: boolean;
+        error?: string;
+        diff?: string;
+    }>>;
+    mutate: (input: ScenarioMutateInput) => Promise<ScenarioDescriptor[]>;
+};
+type CreateScenarioToolsOptions = {
+    adapter?: ExecuteLuaScenarioInput["adapter"];
+};
+export declare function createScenarioTools(seed: ScenarioDescriptor[], options?: CreateScenarioToolsOptions): ScenarioTools;
+export {};

package/dist/tools/scenario.js

@@ -0,0 +1,96 @@
+import { mutateScenarioVariants } from "../generation/mutator.js";
+import { executeLuaScenario } from "@lunatest/core";
+async function runLua(source, adapter) {
+    const execution = await executeLuaScenario({
+        source,
+        adapter,
+    });
+    return {
+        pass: execution.pass,
+        error: execution.error,
+        diff: execution.result?.diff,
+    };
+}
+export function createScenarioTools(seed, options = {}) {
+    const store = new Map(seed.map((item) => [item.id, { ...item }]));
+    return {
+        async list() {
+            return Array.from(store.values());
+        },
+        async get(id) {
+            return store.get(id) ?? null;
+        },
+        async create(input) {
+            const nextId = input.id && input.id.length > 0 ? input.id : `scenario-${store.size + 1}`;
+            const nextName = input.name && input.name.length > 0 ? input.name : `scenario ${store.size + 1}`;
+            const next = {
+                id: nextId,
+                name: nextName,
+                lua: input.lua,
+                tags: input.tags,
+            };
+            store.set(next.id, next);
+            return next;
+        },
+        async run(input) {
+            if (typeof input !== "string" && input.lua) {
+                const executed = await runLua(input.lua, options.adapter);
+                return {
+                    id: "inline",
+                    ...executed,
+                };
+            }
+            const id = typeof input === "string" ? input : String(input.id ?? "");
+            const scenario = store.get(id);
+            if (!scenario) {
+                throw new Error(`Scenario not found: ${id}`);
+            }
+            if (!scenario.lua) {
+                return {
+                    id,
+                    pass: false,
+                    error: "scenario_lua_missing",
+                };
+            }
+            const executed = await runLua(scenario.lua, options.adapter);
+            return {
+                id,
+                ...executed,
+            };
+        },
+        async runAll(filter) {
+            const candidates = Array.from(store.values()).filter((scenario) => {
+                if (!filter) {
+                    return true;
+                }
+                return scenario.id.includes(filter) || scenario.name.includes(filter);
+            });
+            return Promise.all(candidates.map(async (item) => {
+                if (!item.lua) {
+                    return {
+                        id: item.id,
+                        pass: false,
+                        error: "scenario_lua_missing",
+                    };
+                }
+                const executed = await runLua(item.lua, options.adapter);
+                return {
+                    id: item.id,
+                    ...executed,
+                };
+            }));
+        },
+        async mutate(input) {
+            const source = store.get(input.id);
+            if (!source) {
+                throw new Error(`Scenario not found: ${input.id}`);
+            }
+            const count = Math.max(1, Math.trunc(input.count ?? 1));
+            const variants = mutateScenarioVariants(source, count);
+            for (const variant of variants) {
+                store.set(variant.id, variant);
+            }
+            return variants;
+        },
+    };
+}

package/dist/transport/stdio.d.ts

@@ -0,0 +1,24 @@
+import type { createMcpServer } from "../server.js";
+type McpServer = ReturnType<typeof createMcpServer>;
+type JsonRpcLikeRequest = {
+    id: string;
+    method: string;
+    params?: Record<string, unknown>;
+};
+type JsonRpcLikeResponse = {
+    id: string;
+    result?: unknown;
+    error?: {
+        message: string;
+    };
+};
+export type StdioServerOptions = {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+    error?: NodeJS.WritableStream;
+    server: McpServer;
+};
+export declare function parseJsonRpcLine(rawLine: string): JsonRpcLikeRequest | JsonRpcLikeResponse;
+export declare function processJsonRpcLine(line: string, server: McpServer): Promise<JsonRpcLikeResponse | null>;
+export declare function runStdioServer(options: StdioServerOptions): Promise<void>;
+export {};

package/dist/transport/stdio.js

@@ -0,0 +1,63 @@
+import { createInterface } from "node:readline";
+import { isRecord } from "@lunatest/contracts";
+function invalidRequestResponse(message) {
+    return {
+        id: "unknown",
+        error: {
+            message,
+        },
+    };
+}
+function isJsonRpcLikeRequest(value) {
+    return "method" in value;
+}
+export function parseJsonRpcLine(rawLine) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) {
+        return invalidRequestResponse("Empty JSON-RPC line");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return invalidRequestResponse("Malformed JSON line");
+    }
+    if (!isRecord(parsed)) {
+        return invalidRequestResponse("Invalid JSON-RPC payload");
+    }
+    const id = parsed.id;
+    const method = parsed.method;
+    if (typeof id !== "string" || typeof method !== "string") {
+        return invalidRequestResponse("JSON-RPC request requires string id and method");
+    }
+    const params = parsed.params !== undefined && isRecord(parsed.params)
+        ? parsed.params
+        : undefined;
+    return {
+        id,
+        method,
+        params,
+    };
+}
+export async function processJsonRpcLine(line, server) {
+    const parsed = parseJsonRpcLine(line);
+    if (!isJsonRpcLikeRequest(parsed)) {
+        return parsed;
+    }
+    return server.handleRequest(parsed);
+}
+export async function runStdioServer(options) {
+    const rl = createInterface({
+        input: options.input,
+        crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+        const response = await processJsonRpcLine(line, options.server);
+        if (!response) {
+            continue;
+        }
+        options.output.write(`${JSON.stringify(response)}\n`);
+    }
+    rl.close();
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lunatest/mcp",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "lunatest-mcp": "./dist/bin/mcp-stdio.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@lunatest/core": "0.1.0",
+    "@lunatest/contracts": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  }
+}