@kirrosh/apitool 0.4.3

package/src/db/schema.ts

@@ -0,0 +1,215 @@
+import { Database } from "bun:sqlite";
+import { resolve } from "path";
+import { existsSync } from "fs";
+
+let _db: Database | null = null;
+let _dbPath: string | null = null;
+
+export function getDb(dbPath?: string): Database {
+  const path = dbPath ? resolve(dbPath) : (_dbPath ?? resolve(process.cwd(), "apitool.db"));
+
+  // If cached connection exists, verify the file still exists
+  if (_db && _dbPath === path && existsSync(path)) return _db;
+
+  // Close stale connection if any
+  if (_db) {
+    try { _db.close(); } catch {}
+    _db = null;
+    _dbPath = null;
+  }
+  const db = new Database(path, { create: true });
+
+  // Performance and integrity settings
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+
+  runMigrations(db);
+
+  _db = db;
+  _dbPath = path;
+  return db;
+}
+
+export function closeDb(): void {
+  if (_db) {
+    try { _db.close(); } catch {}
+    _db = null;
+    _dbPath = null;
+  }
+}
+
+// ──────────────────────────────────────────────
+// Schema
+// ──────────────────────────────────────────────
+
+const SCHEMA_VERSION = 6;
+
+const SCHEMA_V1 = `
+  CREATE TABLE IF NOT EXISTS runs (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    started_at    TEXT NOT NULL,
+    finished_at   TEXT,
+    total         INTEGER NOT NULL DEFAULT 0,
+    passed        INTEGER NOT NULL DEFAULT 0,
+    failed        INTEGER NOT NULL DEFAULT 0,
+    skipped       INTEGER NOT NULL DEFAULT 0,
+    trigger       TEXT DEFAULT 'manual',
+    commit_sha    TEXT,
+    branch        TEXT,
+    environment   TEXT,
+    duration_ms   INTEGER,
+    collection_id INTEGER REFERENCES collections(id)
+  );
+
+  CREATE TABLE IF NOT EXISTS results (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id          INTEGER NOT NULL REFERENCES runs(id),
+    suite_name      TEXT NOT NULL,
+    test_name       TEXT NOT NULL,
+    status          TEXT NOT NULL,
+    duration_ms     INTEGER NOT NULL,
+    request_method  TEXT,
+    request_url     TEXT,
+    request_body    TEXT,
+    response_status INTEGER,
+    response_body   TEXT,
+    error_message   TEXT,
+    assertions      TEXT,
+    captures        TEXT
+  );
+
+  CREATE TABLE IF NOT EXISTS environments (
+    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+    name      TEXT NOT NULL UNIQUE,
+    variables TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS collections (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    name         TEXT NOT NULL,
+    test_path    TEXT NOT NULL,
+    openapi_spec TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_runs_started      ON runs(started_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_runs_collection    ON runs(collection_id);
+  CREATE INDEX IF NOT EXISTS idx_results_run        ON results(run_id);
+  CREATE INDEX IF NOT EXISTS idx_results_status     ON results(status);
+  CREATE INDEX IF NOT EXISTS idx_results_name       ON results(suite_name, test_name);
+  CREATE INDEX IF NOT EXISTS idx_collections_name   ON collections(name);
+`;
+
+const SCHEMA_V2 = `
+  CREATE TABLE IF NOT EXISTS ai_generations (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    collection_id     INTEGER REFERENCES collections(id),
+    prompt            TEXT NOT NULL,
+    model             TEXT NOT NULL,
+    provider          TEXT NOT NULL,
+    generated_yaml    TEXT,
+    output_path       TEXT,
+    status            TEXT NOT NULL DEFAULT 'pending',
+    error_message     TEXT,
+    prompt_tokens     INTEGER,
+    completion_tokens INTEGER,
+    duration_ms       INTEGER,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_ai_gen_collection ON ai_generations(collection_id);
+`;
+
+const SCHEMA_V3 = `
+  CREATE TABLE IF NOT EXISTS chat_sessions (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    title       TEXT,
+    provider    TEXT NOT NULL,
+    model       TEXT NOT NULL,
+    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    last_active TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS chat_messages (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id    INTEGER NOT NULL REFERENCES chat_sessions(id),
+    role          TEXT NOT NULL,
+    content       TEXT NOT NULL,
+    tool_name     TEXT,
+    tool_args     TEXT,
+    tool_result   TEXT,
+    input_tokens  INTEGER,
+    output_tokens INTEGER,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_chat_messages_session ON chat_messages(session_id);
+  CREATE INDEX IF NOT EXISTS idx_chat_sessions_active  ON chat_sessions(last_active DESC);
+`;
+
+const SCHEMA_V4 = `
+  CREATE TABLE IF NOT EXISTS settings (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+`;
+
+const SCHEMA_V5 = `
+  ALTER TABLE collections ADD COLUMN base_dir TEXT;
+
+  CREATE TABLE environments_new (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    name          TEXT NOT NULL,
+    collection_id INTEGER REFERENCES collections(id) ON DELETE CASCADE,
+    variables     TEXT NOT NULL
+  );
+
+  INSERT INTO environments_new (id, name, collection_id, variables)
+    SELECT id, name, NULL, variables FROM environments;
+
+  DROP TABLE environments;
+  ALTER TABLE environments_new RENAME TO environments;
+
+  CREATE UNIQUE INDEX idx_env_name_collection ON environments(name, collection_id);
+  CREATE UNIQUE INDEX idx_env_name_global ON environments(name) WHERE collection_id IS NULL;
+`;
+
+const SCHEMA_V6 = `
+  ALTER TABLE results ADD COLUMN response_headers TEXT;
+`;
+
+function runMigrations(db: Database): void {
+  const currentVersion = (db.query("PRAGMA user_version").get() as { user_version: number }).user_version;
+
+  if (currentVersion >= SCHEMA_VERSION) return;
+
+  db.transaction(() => {
+    if (currentVersion < 1) {
+      db.exec(SCHEMA_V1);
+    }
+    if (currentVersion < 2) {
+      db.exec(SCHEMA_V2);
+    }
+    if (currentVersion < 3) {
+      db.exec(SCHEMA_V3);
+    }
+    if (currentVersion < 4) {
+      db.exec(SCHEMA_V4);
+    }
+    if (currentVersion < 5) {
+      db.exec(SCHEMA_V5);
+      // Backfill base_dir from dirname(test_path) for existing collections
+      const rows = db.query("SELECT id, test_path FROM collections WHERE base_dir IS NULL").all() as { id: number; test_path: string }[];
+      const updateStmt = db.prepare("UPDATE collections SET base_dir = ? WHERE id = ?");
+      for (const row of rows) {
+        // test_path uses forward slashes (normalizePath); get parent dir
+        const lastSlash = row.test_path.lastIndexOf("/");
+        const baseDir = lastSlash > 0 ? row.test_path.slice(0, lastSlash) : row.test_path;
+        updateStmt.run(baseDir, row.id);
+      }
+    }
+    if (currentVersion < 6) {
+      db.exec(SCHEMA_V6);
+    }
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+  })();
+}

package/src/mcp/server.ts

@@ -0,0 +1,47 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerRunTestsTool } from "./tools/run-tests.ts";
+import { registerValidateTestsTool } from "./tools/validate-tests.ts";
+import { registerQueryDbTool } from "./tools/query-db.ts";
+import { registerSendRequestTool } from "./tools/send-request.ts";
+import { registerExploreApiTool } from "./tools/explore-api.ts";
+import { registerManageEnvironmentTool } from "./tools/manage-environment.ts";
+import { registerCoverageAnalysisTool } from "./tools/coverage-analysis.ts";
+import { registerSaveTestSuiteTool } from "./tools/save-test-suite.ts";
+import { registerGenerateTestsGuideTool } from "./tools/generate-tests-guide.ts";
+import { registerSetupApiTool } from "./tools/setup-api.ts";
+import { registerGenerateMissingTestsTool } from "./tools/generate-missing-tests.ts";
+import { registerManageServerTool } from "./tools/manage-server.ts";
+import { registerCiInitTool } from "./tools/ci-init.ts";
+
+export interface McpServerOptions {
+  dbPath?: string;
+}
+
+export async function startMcpServer(options: McpServerOptions = {}): Promise<void> {
+  const { dbPath } = options;
+
+  const server = new McpServer({
+    name: "apitool",
+    version: "0.4.0",
+  });
+
+  // Register all tools
+  registerRunTestsTool(server, dbPath);
+  registerValidateTestsTool(server);
+  registerQueryDbTool(server, dbPath);
+  registerSendRequestTool(server);
+  registerExploreApiTool(server);
+  registerManageEnvironmentTool(server, dbPath);
+  registerCoverageAnalysisTool(server);
+  registerSaveTestSuiteTool(server, dbPath);
+  registerGenerateTestsGuideTool(server);
+  registerSetupApiTool(server, dbPath);
+  registerGenerateMissingTestsTool(server);
+  registerManageServerTool(server, dbPath);
+  registerCiInitTool(server);
+
+  // Connect via stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/mcp/tools/ci-init.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ciInitCommand } from "../../cli/commands/ci-init.ts";
+
+export function registerCiInitTool(server: McpServer) {
+  server.registerTool("ci_init", {
+    description:
+      "Generate a CI/CD workflow file for running API tests automatically on push, PR, and schedule. " +
+      "Supports GitHub Actions and GitLab CI. Auto-detects platform from project structure " +
+      "(.github/ → GitHub, .gitlab-ci.yml → GitLab). " +
+      "Use after tests are generated and passing. After generating the workflow, help the user commit and push to activate CI.",
+    inputSchema: {
+      platform: z.optional(z.enum(["github", "gitlab"]))
+        .describe("CI platform. If omitted, auto-detects from project structure (defaults to GitHub)"),
+      force: z.optional(z.boolean())
+        .describe("Overwrite existing CI config (default: false)"),
+      dir: z.optional(z.string())
+        .describe("Project root directory where CI config will be created (default: current working directory)"),
+    },
+  }, async ({ platform, force, dir }) => {
+    // Capture stdout to return as result
+    const logs: string[] = [];
+    const origWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      logs.push(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      const code = await ciInitCommand({
+        platform,
+        force: force ?? false,
+        dir,
+      });
+
+      process.stdout.write = origWrite;
+
+      const output = logs.join("").trim();
+      if (code !== 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: output || "ci init failed", exitCode: code }, null, 2) }],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ message: output, exitCode: 0 }, null, 2) }],
+      };
+    } catch (err) {
+      process.stdout.write = origWrite;
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

package/src/mcp/tools/coverage-analysis.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readOpenApiSpec, extractEndpoints, scanCoveredEndpoints, filterUncoveredEndpoints } from "../../core/generator/index.ts";
+
+export function registerCoverageAnalysisTool(server: McpServer) {
+  server.registerTool("coverage_analysis", {
+    description: "Compare an OpenAPI spec against existing test files to find untested endpoints. " +
+      "Use to identify gaps and prioritize which endpoints to generate tests for next.",
+    inputSchema: {
+      specPath: z.string().describe("Path to OpenAPI spec file (JSON or YAML)"),
+      testsDir: z.string().describe("Path to directory with test YAML files"),
+    },
+  }, async ({ specPath, testsDir }) => {
+    try {
+      const doc = await readOpenApiSpec(specPath);
+      const allEndpoints = extractEndpoints(doc);
+
+      if (allEndpoints.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "No endpoints found in the spec" }, null, 2) }],
+          isError: true,
+        };
+      }
+
+      const covered = await scanCoveredEndpoints(testsDir);
+      const uncovered = filterUncoveredEndpoints(allEndpoints, covered);
+      const coveredCount = allEndpoints.length - uncovered.length;
+      const percentage = Math.round((coveredCount / allEndpoints.length) * 100);
+
+      const result = {
+        totalEndpoints: allEndpoints.length,
+        covered: coveredCount,
+        uncovered: uncovered.length,
+        percentage,
+        uncoveredEndpoints: uncovered.map(ep => ({
+          method: ep.method,
+          path: ep.path,
+          summary: ep.summary,
+          tags: ep.tags,
+        })),
+        coveredEndpoints: covered.map(ep => ({
+          method: ep.method,
+          path: ep.path,
+          file: ep.file,
+        })),
+      };
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

package/src/mcp/tools/explore-api.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readOpenApiSpec, extractEndpoints, extractSecuritySchemes } from "../../core/generator/index.ts";
+import { compressSchema, formatParam } from "../../core/generator/schema-utils.ts";
+
+export function registerExploreApiTool(server: McpServer) {
+  server.registerTool("explore_api", {
+    description: "Explore an OpenAPI spec — list endpoints, servers, and security schemes. " +
+      "Use with includeSchemas=true when generating tests to get full request/response body schemas.",
+    inputSchema: {
+      specPath: z.string().describe("Path to OpenAPI spec file (JSON or YAML)"),
+      tag: z.optional(z.string()).describe("Filter endpoints by tag"),
+      includeSchemas: z.optional(z.boolean()).describe("Include request/response body schemas and parameter types (default: false)"),
+    },
+  }, async ({ specPath, tag, includeSchemas }) => {
+    try {
+      const doc = await readOpenApiSpec(specPath);
+      const allEndpoints = extractEndpoints(doc);
+      const securitySchemes = extractSecuritySchemes(doc);
+      const servers = ((doc as any).servers ?? []) as Array<{ url: string; description?: string }>;
+
+      const endpoints = tag
+        ? allEndpoints.filter(ep => ep.tags.includes(tag))
+        : allEndpoints;
+
+      const result = {
+        title: (doc as any).info?.title,
+        version: (doc as any).info?.version,
+        servers: servers.map(s => ({ url: s.url, description: s.description })),
+        securitySchemes: securitySchemes.map(s => ({
+          name: s.name,
+          type: s.type,
+          ...(s.scheme ? { scheme: s.scheme } : {}),
+          ...(s.in ? { in: s.in, keyName: s.apiKeyName } : {}),
+        })),
+        totalEndpoints: allEndpoints.length,
+        ...(tag ? { filteredByTag: tag, matchingEndpoints: endpoints.length } : {}),
+        endpoints: endpoints.map(ep => {
+          const base: Record<string, unknown> = {
+            method: ep.method,
+            path: ep.path,
+            summary: ep.summary,
+            tags: ep.tags,
+            parameters: ep.parameters.map(p => ({
+              name: p.name,
+              in: p.in,
+              required: p.required ?? false,
+              ...(includeSchemas ? { type: formatParam(p).split(": ")[1] } : {}),
+            })),
+            hasRequestBody: !!ep.requestBodySchema,
+            responses: ep.responses.map(r => ({
+              statusCode: r.statusCode,
+              description: r.description,
+              ...(includeSchemas && r.schema ? { schema: compressSchema(r.schema) } : {}),
+            })),
+          };
+
+          if (includeSchemas) {
+            if (ep.requestBodySchema) {
+              base.requestBodySchema = compressSchema(ep.requestBodySchema);
+            }
+            if (ep.requestBodyContentType) {
+              base.requestBodyContentType = ep.requestBodyContentType;
+            }
+            if (ep.security.length > 0) {
+              base.security = ep.security;
+            }
+          }
+
+          return base;
+        }),
+      };
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

package/src/mcp/tools/generate-missing-tests.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  scanCoveredEndpoints,
+  filterUncoveredEndpoints,
+} from "../../core/generator/index.ts";
+import { compressEndpointsWithSchemas, buildGenerationGuide } from "./generate-tests-guide.ts";
+
+export function registerGenerateMissingTestsTool(server: McpServer) {
+  server.registerTool("generate_missing_tests", {
+    description: "Analyze test coverage and generate a test guide for only the uncovered endpoints. " +
+      "Combines coverage_analysis + generate_tests_guide — returns a focused guide for missing tests. " +
+      "Use this for incremental test generation to avoid duplicating existing tests.",
+    inputSchema: {
+      specPath: z.string().describe("Path or URL to OpenAPI spec file"),
+      testsDir: z.string().describe("Path to directory with existing test YAML files"),
+      outputDir: z.optional(z.string()).describe("Directory for saving new test files (default: same as testsDir)"),
+    },
+  }, async ({ specPath, testsDir, outputDir }) => {
+    try {
+      const doc = await readOpenApiSpec(specPath);
+      const allEndpoints = extractEndpoints(doc);
+      const securitySchemes = extractSecuritySchemes(doc);
+      const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
+      const title = (doc as any).info?.title as string | undefined;
+
+      if (allEndpoints.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "No endpoints found in the spec" }, null, 2) }],
+          isError: true,
+        };
+      }
+
+      const covered = await scanCoveredEndpoints(testsDir);
+      const uncovered = filterUncoveredEndpoints(allEndpoints, covered);
+      const coveredCount = allEndpoints.length - uncovered.length;
+      const percentage = Math.round((coveredCount / allEndpoints.length) * 100);
+
+      if (uncovered.length === 0) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              fullyCovered: true,
+              percentage: 100,
+              totalEndpoints: allEndpoints.length,
+              covered: coveredCount,
+            }, null, 2),
+          }],
+        };
+      }
+
+      // Build guide for uncovered endpoints only
+      const apiContext = compressEndpointsWithSchemas(uncovered, securitySchemes);
+      const coverageHeader = `## Coverage: ${coveredCount}/${allEndpoints.length} endpoints covered (${percentage}%). Generating tests for ${uncovered.length} uncovered endpoints:`;
+
+      const guide = buildGenerationGuide({
+        title: title ?? "API",
+        baseUrl,
+        apiContext,
+        outputDir: outputDir ?? testsDir,
+        securitySchemes,
+        endpointCount: uncovered.length,
+        coverageHeader,
+      });
+
+      return {
+        content: [{ type: "text" as const, text: guide }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}