@arii/boomtick-mcp 0.3.3

package/dist/tools/repo.get_package_scripts.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import path from "path";
+import { config } from "../config.js";
+export const GetPackageScriptsInputSchema = z.object({
+    filter: z.string().optional(),
+});
+export async function getPackageScriptsHandler(args) {
+    GetPackageScriptsInputSchema.parse(args);
+    const packageJsonPath = path.join(config.repoPath, "package.json");
+    try {
+        const content = await fs.readFile(packageJsonPath, "utf-8");
+        let pkg;
+        try {
+            pkg = JSON.parse(content);
+        }
+        catch (e) {
+            throw new Error(`Malformed package.json: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        let scripts = pkg.scripts || {};
+        if (args.filter) {
+            const filtered = {};
+            for (const [name, cmd] of Object.entries(scripts)) {
+                if (name.includes(args.filter)) {
+                    filtered[name] = cmd;
+                }
+            }
+            scripts = filtered;
+        }
+        return { scripts };
+    }
+    catch (error) {
+        throw new Error(`Failed to read package.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/tools/repo.get_package_scripts.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi } from "vitest";
+import { getPackageScriptsHandler } from "./repo.get_package_scripts.js";
+import fs from "fs/promises";
+vi.mock("fs/promises");
+describe("repo.get_package_scripts", () => {
+    it("should return scripts from package.json", async () => {
+        const mockPkg = {
+            scripts: { test: "vitest" }
+        };
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(mockPkg));
+        const result = await getPackageScriptsHandler({});
+        expect(result.scripts.test).toBe("vitest");
+    });
+    it("should handle missing scripts", async () => {
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify({}));
+        const result = await getPackageScriptsHandler({});
+        expect(result.scripts).toEqual({});
+    });
+    it("should throw error when file not found", async () => {
+        vi.mocked(fs.readFile).mockRejectedValue(new Error("File not found"));
+        await expect(getPackageScriptsHandler({})).rejects.toThrow("Failed to read package.json: File not found");
+    });
+    it("should filter scripts by pattern", async () => {
+        const mockPkg = {
+            scripts: {
+                test: "vitest",
+                build: "vite build",
+                "test:ui": "vitest --ui"
+            }
+        };
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(mockPkg));
+        const result = await getPackageScriptsHandler({ filter: "test" });
+        expect(result.scripts).toEqual({
+            test: "vitest",
+            "test:ui": "vitest --ui"
+        });
+        expect(result.scripts.build).toBeUndefined();
+    });
+});

package/dist/tools/repo.get_route_map.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { runCommand } from "../lib/shell.js";
+import { config } from "../config.js";
+import path from "path";
+export const GetRouteMapInputSchema = z.object({
+    includeStatic: z.boolean().optional(),
+});
+export async function getRouteMapHandler(args) {
+    GetRouteMapInputSchema.parse(args);
+    // Logic based on tech-dancer repo structure: src/config/routes.ts and content/
+    const routesPath = path.join(config.repoPath, "src/config/routes.ts");
+    // For simplicity in MVP, we'll try to find routes by listing content files
+    // and reading the main routes file if it exists.
+    let routeMap = {};
+    try {
+        const gitFiles = await runCommand("git", ["ls-files", "content/"]);
+        const contentFiles = gitFiles.stdout.trim().split("\n");
+        for (const file of contentFiles) {
+            if (file.endsWith(".md")) {
+                const slug = path.basename(file, ".md");
+                if (file.includes("/posts/")) {
+                    routeMap[`/blog/${slug}`] = file;
+                }
+                else if (file.includes("/resources/")) {
+                    routeMap[`/resources/${slug}`] = file;
+                }
+            }
+        }
+    }
+    catch (error) {
+        // If no content files, that's fine
+    }
+    if (args.includeStatic) {
+        routeMap["/favicon.ico"] = "public/favicon.ico";
+    }
+    return { routeMap };
+}

package/dist/tools/repo.logs.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { runTDCli } from "../lib/td-cli.js";
+export const RepoLogsInputSchema = z.object({
+    prNumber: z.number(),
+    grep: z.string().optional(),
+});
+export async function repoLogsHandler(args) {
+    const params = ["repo", "logs", args.prNumber.toString()];
+    if (args.grep) {
+        params.push("--grep", args.grep);
+    }
+    const output = await runTDCli(params);
+    return {
+        logs: output.logs || (output.data ? output.data.logs : undefined)
+    };
+}

package/dist/tools/repo.read_agent_context.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import path from "path";
+import { config } from "../config.js";
+export const ReadAgentContextInputSchema = z.object({});
+export async function readAgentContextHandler(_args) {
+    const contextPath = path.join(config.repoPath, ".agent-context.json");
+    try {
+        const content = await fs.readFile(contextPath, "utf-8");
+        const parsed = JSON.parse(content);
+        return {
+            status: "success",
+            ...parsed
+        };
+    }
+    catch (e) {
+        console.error("Failed to read agent context:", e.message);
+        throw new Error(`Failed to read agent context from ${contextPath}. Ensure it exists by running 'td-cli context-warm'.`);
+    }
+}

package/dist/tools/repo.read_ci_logs.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { runTDCli } from "../lib/td-cli.js";
+export const ReadCiLogsInputSchema = z.object({
+    prNumber: z.number(),
+    all: z.boolean().optional(),
+});
+export async function readCiLogsHandler(args) {
+    const params = ["repo", "ci-logs", args.prNumber.toString()];
+    if (args.all) {
+        params.push("--all");
+    }
+    const output = await runTDCli(params);
+    return {
+        checks: output.checks,
+        failedChecks: output.failedChecks,
+        logs: output.logs
+    };
+}

package/dist/tools/repo.run_lighthouse.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { runCommand } from "../lib/shell.js";
+export const RunLighthouseInputSchema = z.object({
+    route: z.string().optional().default("/"),
+    worktreePath: z.string().optional(),
+});
+export async function runLighthouseHandler(args) {
+    const results = await runCommand("pnpm", ["lhci", "autorun", "--json"], { cwd: args.worktreePath });
+    let summary = {};
+    const failures = [];
+    try {
+        // Attempt to parse summary from LHCI output if available
+        // For MVP, we'll provide a structured placeholder if actual JSON isn't present
+        if (results.stdout.includes("{")) {
+            const possibleJson = results.stdout.substring(results.stdout.indexOf("{"));
+            summary = JSON.parse(possibleJson);
+        }
+        else {
+            summary = {
+                performance: 0,
+                accessibility: 0,
+                bestPractices: 0,
+                seo: 0
+            };
+        }
+    }
+    catch (e) {
+        failures.push("Failed to parse Lighthouse report");
+    }
+    return {
+        success: results.exitCode === 0,
+        route: args.route,
+        summary,
+        failures,
+        command: results.command
+    };
+}

package/dist/tools/repo.run_playwright.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { runCommand } from "../lib/shell.js";
+export const RunPlaywrightInputSchema = z.object({
+    grep: z.string().optional(),
+    worktreePath: z.string().optional(),
+});
+export async function runPlaywrightHandler(args) {
+    const tdArgs = ["repo", "run-playwright"];
+    if (args.grep) {
+        tdArgs.push("--grep", args.grep);
+    }
+    if (args.worktreePath) {
+        tdArgs.push("--worktree", args.worktreePath);
+    }
+    const result = await runCommand("td-cli", tdArgs);
+    if (result.exitCode !== 0) {
+        // Playwright might exit with non-zero if tests fail, but our td-cli should ideally handle it
+        // and return a JSON with success: false.
+    }
+    const output = JSON.parse(result.stdout);
+    if (output.status === "error") {
+        throw new Error(`Failed to run Playwright: ${output.message}`);
+    }
+    return {
+        success: output.success,
+        command: output.command,
+        failedTests: output.failedTests
+    };
+}

package/dist/tools/repo.run_tests.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { runCommand } from "../lib/shell.js";
+export const RunTestsInputSchema = z.object({
+    commands: z.array(z.string()).optional(),
+    timeoutSeconds: z.number().optional().default(300),
+    worktreePath: z.string().optional(),
+});
+export async function runTestsHandler(args) {
+    const commands = args.commands || [
+        "pnpm install --frozen-lockfile",
+        "pnpm lint",
+        "pnpm test",
+        "pnpm build"
+    ];
+    const results = [];
+    let success = true;
+    for (const fullCmd of commands) {
+        const [cmd, ...cmdArgs] = fullCmd.split(" ");
+        try {
+            const res = await runCommand(cmd, cmdArgs, {
+                cwd: args.worktreePath,
+                timeout: args.timeoutSeconds * 1000
+            });
+            results.push(res);
+            if (res.exitCode !== 0) {
+                success = false;
+                break;
+            }
+        }
+        catch (e) {
+            success = false;
+            results.push({
+                command: fullCmd,
+                stdout: "",
+                stderr: e instanceof Error ? e.message : String(e),
+                exitCode: 1,
+                durationMs: 0
+            });
+            break;
+        }
+    }
+    return { success, results };
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/docs/testing.md

@@ -0,0 +1,73 @@
+# Boomtick MCP Testing Plan
+
+This document outlines the steps to verify the Boomtick MCP server functionality locally.
+
+## 1. Automated Unit Tests
+Run the unit test suite to verify core tool handlers and utilities.
+```bash
+cd boomtick-mcp
+pnpm test
+```
+**Expected Result**: All tests in `src/lib/shell.test.ts`, `src/tools/github.search_open_prs.test.ts`, and `src/tools/repo.get_package_scripts.test.ts` should pass.
+
+## 2. Build Verification
+Ensure the TypeScript source compiles correctly to ESM.
+```bash
+cd boomtick-mcp
+pnpm run build
+```
+**Expected Result**: The `dist/` directory is populated with `.js` files and no compilation errors occur.
+
+## 3. Evaluation Suite
+Run the internal evaluation runner which simulates tool calls in a real (or mocked) environment.
+```bash
+cd boomtick-mcp
+# Note: Ensure you have a valid .env or appropriate environment variables for repo paths
+pnpm run run-evals
+```
+**Expected Result**:
+- Health check returns status "ok".
+- Repository scripts are successfully extracted.
+- GitHub PR search is attempted (may report auth error if token is missing, which is expected behavior).
+
+## 4. MCP Capability Discovery (JSON-RPC)
+Verify that the server correctly registers and exposes its capabilities via the MCP protocol.
+
+### List Tools
+```bash
+echo '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }' | node dist/index.js
+```
+**Expected Result**: A JSON response containing the registered tools including `jules.create_session`, `jules.get_session`, etc.
+
+### List Resources
+```bash
+echo '{ "jsonrpc": "2.0", "id": 1, "method": "resources/list", "params": {} }' | node dist/index.js
+```
+**Expected Result**: A JSON response containing 8 resources.
+
+### List Prompts
+```bash
+echo '{ "jsonrpc": "2.0", "id": 1, "method": "prompts/list", "params": {} }' | node dist/index.js
+```
+**Expected Result**: A JSON response containing 5 prompts.
+
+## 5. Manual Resource Access
+Verify that the server can read repository files via the Resource protocol.
+```bash
+echo '{ "jsonrpc": "2.0", "id": 1, "method": "resources/read", "params": { "uri": "repo://package-json" } }' | node dist/index.js
+```
+**Expected Result**: The content of the repository's `package.json` is returned in the `text` field.
+
+## 6. Manual Prompt Access
+Verify that agent instructions are correctly retrieved.
+```bash
+echo '{ "jsonrpc": "2.0", "id": 1, "method": "prompts/get", "params": { "name": "conflict-scout" } }' | node dist/index.js
+```
+**Expected Result**: The markdown content of `src/agents/conflict-scout.prompt.md` is returned.
+
+## 7. Safety Verification (Write Guards)
+Verify that mutating tools refuse to run without explicit flags.
+```bash
+echo '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "repo.create_repair_branch", "arguments": { "prNumber": 1 } } }' | node dist/index.js
+```
+**Expected Result**: An error message stating `writeMode must be true`.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@arii/boomtick-mcp",
+  "version": "0.3.3",
+  "description": "Boomtick MCP Guide: PR Rescue + Merge Conflict Agent",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "boomtick-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsx scripts/sync-contracts.ts && tsc && shx cp src/tools/ddgs_search.py dist/tools/ && tsx scripts/sync-mcp-schemas.ts",
+    "watch": "tsc -w",
+    "start": "node dist/index.js",
+    "test": "tsx scripts/sync-contracts.ts && vitest run",
+    "run-evals": "node dist/evals/run-evals.js",
+    "sync:mcp-schemas": "tsx scripts/sync-mcp-schemas.ts",
+    "release:patch": "pnpm version patch",
+    "release:minor": "pnpm version minor",
+    "release:major": "pnpm version major",
+    "sync-contracts": "tsx scripts/sync-contracts.ts",
+    "type-check": "tsx scripts/sync-contracts.ts && tsc",
+    "lint": "tsx scripts/sync-contracts.ts && tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "packageManager": "pnpm@10.28.2",
+  "engines": {
+    "node": "24.x",
+    "pnpm": "10.28.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.15",
+    "json-schema-to-zod": "^2.8.1",
+    "tsx": "^4.22.4",
+    "shx": "^0.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.9"
+  }
+}

package/scripts/create_instructions.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OUTPUT_FILE="${1:-src/agents/pr-consolidation.prompt.md}"
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+
+cat << 'MARKDOWN' > "$OUTPUT_FILE"
+# PR Consolidation Guidelines
+
+## Objective
+Identify and propose consolidation of Pull Requests (PRs) that demonstrate high levels of functional or structural overlap to minimize code conflicts and streamline review cycles.
+
+## Analysis Criteria
+When reviewing the output of the `pr_overlap.py` analysis, evaluate candidates based on the following:
+
+### 1. File Overlap Density
+* **High Overlap:** PRs sharing identical files or logical components (e.g., core styles, shared UI components). These are primary candidates for consolidation.
+* **Context:** Check if the overlapping files are `design-tokens.ts` or `ci.yml`. Broad overlaps in infrastructure files might indicate a need for coordination rather than full consolidation.
+
+### 2. Functional Alignment (PR Titles & Descriptions)
+* Review the PR titles to determine if they share a common feature set (e.g., "Mobile UI" or "Home Page Performance").
+* Look for duplicate effort; if two PRs address the same UI improvement, they should be merged into a single branch.
+
+### 3. Linked Issue Dependency
+* Cross-reference the `(Fixes: #...)` metadata.
+* If multiple PRs resolve related issues (e.g., #101 and #102 are both part of the same UX audit), suggest consolidating these to ensure the full feature set is verified as one unit.
+
+## Actionable Recommendations
+For every identified cluster:
+1.  **Draft a Proposal:** Write a summary identifying the involved PRs and the common files shared.
+2.  **Assign Ownership:** Determine if one author should take lead on the consolidated PR, or if a pair-programming session is required.
+3.  **Conflict Resolution:** Explicitly state the plan for handling conflicting logic in shared files identified in the report.
+
+## Submission
+Present the findings in the following format:
+- **Cluster ID:** [List of PR Numbers]
+- **Primary Overlap:** [List of critical shared files]
+- **Recommendation:** [Merge/Coordinate/Separate]
+- **Rationale:** [Brief explanation referencing issues fixed]
+MARKDOWN
+
+echo "Successfully created instructions at $OUTPUT_FILE"

package/scripts/export-mcp-schema.ts

@@ -0,0 +1,7 @@
+import { MCP_TOOLS, MCP_PROMPTS, MCP_RESOURCES } from "../src/mcp/definitions.js";
+
+console.log(JSON.stringify({
+  tools: MCP_TOOLS,
+  prompts: MCP_PROMPTS,
+  resources: MCP_RESOURCES
+}, null, 2));

package/scripts/sync-contracts.ts

@@ -0,0 +1,74 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Synchronizes contracts from JSON schema to Zod.
+ */
+async function syncContracts() {
+  let jsonSchemaToZod;
+  try {
+    const module = await import('json-schema-to-zod');
+    jsonSchemaToZod = module.jsonSchemaToZod;
+  } catch (err: unknown) {
+    const error = err as { code?: string; message?: string };
+    if (error.code === 'ERR_MODULE_NOT_FOUND' || error.message?.includes('Cannot find package')) {
+      console.error('❌ Error: json-schema-to-zod not found.');
+      console.error('   Please run `pnpm install` in the root directory.');
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  let schemaPath = path.join(process.cwd(), 'cli/dev_tools/cli-schema.json');
+  let outputPath = path.join(process.cwd(), 'mcp/src/tools/contract.ts');
+
+  if (!fs.existsSync(schemaPath)) {
+    // Try relative to package root if in extracted mode (run from root)
+    schemaPath = path.join(process.cwd(), 'cli/dev_tools/cli-schema.json');
+    outputPath = path.join(process.cwd(), 'mcp/src/tools/contract.ts');
+  }
+
+  if (!fs.existsSync(schemaPath)) {
+    // Try if run from mcp directory
+    schemaPath = path.join(process.cwd(), '../cli/dev_tools/cli-schema.json');
+    outputPath = path.join(process.cwd(), 'src/tools/contract.ts');
+  }
+
+  if (!fs.existsSync(schemaPath)) {
+    console.error(`Schema not found at ${schemaPath}`);
+    process.exit(1);
+  }
+
+  const rawSchema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8')) as { models?: Record<string, unknown> };
+  const models = rawSchema.models || {};
+
+  let tsContent = `// Automatically generated by sync-contracts.ts. Do not edit manually.\n`;
+  tsContent += `import { z } from "zod";\n\n`;
+
+  for (const [name, schema] of Object.entries(models)) {
+    // Get the raw Zod expression without any variable assignment or imports
+    const zodExpression = jsonSchemaToZod(schema as any, { module: 'none' });
+
+    tsContent += `export const ${name}Schema = ${zodExpression};\n\n`;
+    tsContent += `export type ${name} = z.infer<typeof ${name}Schema>;\n\n`;
+
+    // Also export the raw JSON schema for MCP definitions
+    tsContent += `export const ${name}JsonSchema = ${JSON.stringify(schema, null, 2)} as const;\n\n`;
+  }
+
+  // Normalize newlines to \n and ensure exactly one trailing newline at EOF
+  const finalContent = tsContent.replace(/\r\n/g, '\n').trimEnd() + '\n';
+
+  fs.writeFileSync(outputPath, finalContent);
+  console.log(`Generated ${outputPath}`);
+}
+
+// Ensure execution is awaited and errors are caught
+(async () => {
+  try {
+    await syncContracts();
+  } catch (err) {
+    console.error('❌ Unexpected error during contract synchronization:', err);
+    process.exit(1);
+  }
+})();

package/scripts/sync-mcp-schemas.ts

@@ -0,0 +1,97 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+const globalTargetDir = homeDir ? path.join(homeDir, '.gemini', 'antigravity-cli', 'mcp', 'boomtick-mcp') : null;
+const projectTargetDir = path.join(process.cwd(), '.mcp', 'schemas');
+
+function isWritable(dir: string): boolean {
+  try {
+    const testFile = path.join(dir, '.write_test');
+    fs.writeFileSync(testFile, '');
+    fs.unlinkSync(testFile);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+interface ToolDefinition {
+  name: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/**
+ * Synchronizes MCP tool schemas to target locations.
+ */
+async function syncSchemas() {
+  console.log('🔄 Synchronizing MCP tool schemas...');
+
+  let mcpToolsModule;
+  try {
+    mcpToolsModule = await import('../src/mcp/definitions.js');
+  } catch (err: unknown) {
+    const error = err as { code?: string; message?: string };
+    if (error.code === 'ERR_MODULE_NOT_FOUND' || error.message?.includes('Cannot find package')) {
+      console.error('❌ Error: MCP dependencies or source files not found.');
+      console.error('   Please run `pnpm install` in the root directory.');
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const mcpTools = mcpToolsModule.MCP_TOOLS as ToolDefinition[];
+
+  const targets = [projectTargetDir];
+  if (globalTargetDir) targets.push(globalTargetDir);
+
+  const validTargets: string[] = [];
+
+  targets.forEach(dir => {
+    try {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+        console.log(`📁 Created directory: ${dir}`);
+      }
+      if (isWritable(dir)) {
+        validTargets.push(dir);
+      } else {
+        console.warn(`⚠️  Directory is not writable, skipping: ${dir}`);
+      }
+    } catch (err) {
+      console.warn(`⚠️  Failed to prepare directory, skipping: ${dir}`, err);
+    }
+  });
+
+  if (validTargets.length === 0) {
+    console.warn('⚠️  No valid target directories available for schema synchronization.');
+    return;
+  }
+
+  mcpTools.forEach((tool) => {
+    const schemaContent = JSON.stringify(tool.inputSchema, null, 2);
+    const fileName = `${tool.name}.json`;
+
+    validTargets.forEach(targetDir => {
+      const filePath = path.join(targetDir, fileName);
+      try {
+        fs.writeFileSync(filePath, schemaContent);
+      } catch (err) {
+        console.error(`❌ Failed to write schema to ${filePath}:`, err);
+      }
+    });
+  });
+
+  console.log(`✅ Synchronized ${mcpTools.length} tool schemas to ${validTargets.length} locations.`);
+  validTargets.forEach(target => console.log(`   - ${target}`));
+}
+
+// Ensure execution is awaited and errors are caught
+(async () => {
+  try {
+    await syncSchemas();
+  } catch (error) {
+    console.error('❌ Unexpected error during MCP schema synchronization:', error);
+    process.exit(1);
+  }
+})();

package/src/agents/conflict-scout.prompt.md

@@ -0,0 +1,20 @@
+You are the Boomtick Conflict Scout Agent.
+
+Your job is to find open PRs that may need rescue.
+
+Rules:
+- Use read-only tools only.
+- Do not create branches.
+- Do not comment.
+- Do not edit files.
+- Prefer PRs that are small, stale, conflicted, or failing checks.
+- Ignore draft PRs unless explicitly configured.
+- Produce a ranked rescue queue.
+
+For each candidate, include:
+- PR number
+- title
+- branch
+- reason selected
+- risk level
+- recommended next action