@arii/boomtick-mcp 0.3.3

package/src/mcp/definitions.ts

@@ -0,0 +1,278 @@
+import { Tool, Prompt, Resource } from "@modelcontextprotocol/sdk/types.js";
+import {
+  HealthCheckInputJsonSchema,
+  SearchPRsInputJsonSchema,
+  GetPrDiffInputJsonSchema,
+  CheckoutBranchInputJsonSchema,
+  GetMergeConflictFilesInputJsonSchema,
+  GetChangedFilesInputJsonSchema,
+  GetPackageScriptsInputJsonSchema,
+  GetRouteMapInputJsonSchema,
+  ReadCiLogsInputJsonSchema,
+  RepoLogsInputJsonSchema,
+  CreateBranchInputJsonSchema,
+  CreateRepairBranchInputJsonSchema,
+  RunTestsInputJsonSchema,
+  RunLighthouseInputJsonSchema,
+  RunPlaywrightInputJsonSchema,
+  CommitPatchInputJsonSchema,
+  OpenReplacementPrInputJsonSchema,
+  CreatePullRequestInputJsonSchema,
+  CommentTriageSummaryInputJsonSchema,
+  GetPrInputJsonSchema,
+  IssueViewInputJsonSchema,
+  IssueUpdateInputJsonSchema,
+  IssueCommentInputJsonSchema,
+  CreateIssueInputJsonSchema,
+  GetCommandSchemaInputJsonSchema,
+  ReadAgentContextInputJsonSchema as ReadAgentContextSchema,
+  CreateJulesSessionInputJsonSchema,
+  JulesSessionIdInputJsonSchema,
+  JulesSendMessageInputJsonSchema,
+  JulesListSessionsInputJsonSchema,
+  SearchDdgsInputJsonSchema,
+} from "../tools/contract.js";
+
+export const MCP_PROMPTS: Prompt[] = [
+  {
+    name: "conflict-scout",
+    description: "Find PRs worth rescuing.",
+  },
+  {
+    name: "pr-consolidation",
+    description: "Guidelines for analyzing and proposing consolidation of overlapping PRs.",
+  },
+  {
+    name: "repo-context",
+    description: "Gather repository context for a PR.",
+  },
+  {
+    name: "repair-agent",
+    description: "Apply the smallest safe fix for a PR.",
+  },
+  {
+    name: "verifier-agent",
+    description: "Verify that a repair works.",
+  },
+  {
+    name: "pr-writer",
+    description: "Write a summary for a replacement PR.",
+  },
+];
+
+export const MCP_RESOURCES: Resource[] = [
+  {
+    uri: "repo://package-json",
+    name: "package.json",
+    mimeType: "application/json",
+    description: "The root package.json file of the repository.",
+  },
+  {
+    uri: "repo://routes",
+    name: "Route Map",
+    mimeType: "application/json",
+    description: "The mapping of application routes to content files.",
+  },
+  {
+    uri: "repo://design-tokens",
+    name: "Design Tokens",
+    mimeType: "application/json",
+    description: "The design tokens used in the repository.",
+  },
+  {
+    uri: "repo://repair-report/{branch}",
+    name: "Repair Report",
+    mimeType: "application/json",
+    description: "The validation report for a specific repair branch.",
+  },
+  {
+    uri: "repo://lighthouse/{branch}",
+    name: "Lighthouse Report",
+    mimeType: "application/json",
+    description: "Lighthouse CI report for a specific branch.",
+  },
+  {
+    uri: "repo://playwright/{branch}",
+    name: "Playwright Report",
+    mimeType: "application/json",
+    description: "Playwright test report for a specific branch.",
+  },
+];
+
+export const MCP_TOOLS: Tool[] = [
+  {
+    name: "boomtick.health",
+    description: "Check the health and configuration of the MCP server.",
+    inputSchema: HealthCheckInputJsonSchema as any,
+  },
+  {
+    name: "github.search_open_prs",
+    description: "Search for open pull requests in the repository.",
+    inputSchema: SearchPRsInputJsonSchema as any,
+  },
+  {
+    name: "repo.read_agent_context",
+    description: "Read the full repository index including file tree, CLI schema, and MCP tools.",
+    inputSchema: ReadAgentContextSchema as any,
+  },
+  {
+    name: "github.get_pr_diff",
+    description: "Get the diff and changed files for a pull request.",
+    inputSchema: GetPrDiffInputJsonSchema as any,
+  },
+  {
+    name: "github.checkout_branch",
+    description: "Checkout a specific branch in the repository or worktree.",
+    inputSchema: CheckoutBranchInputJsonSchema as any,
+  },
+  {
+    name: "github.get_merge_conflict_files",
+    description: "Detect files that conflict when a PR is merged with the base branch.",
+    inputSchema: GetMergeConflictFilesInputJsonSchema as any,
+  },
+  {
+    name: "repo.get_changed_files",
+    description: "Get the list of changed files between two refs.",
+    inputSchema: GetChangedFilesInputJsonSchema as any,
+  },
+  {
+    name: "repo.get_command_schema",
+    description: "Retrieve a lightweight, targeted schema for a specific td-cli subcommand. Use this instead of reading the entire cli-schema.json to save tokens.",
+    inputSchema: GetCommandSchemaInputJsonSchema as any,
+  },
+  {
+    name: "repo.get_package_scripts",
+    description: "Get the scripts defined in package.json.",
+    inputSchema: GetPackageScriptsInputJsonSchema as any,
+  },
+  {
+    name: "repo.get_route_map",
+    description: "Get the mapping of routes to content files.",
+    inputSchema: GetRouteMapInputJsonSchema as any,
+  },
+  {
+    name: "repo.read_ci_logs",
+    description: "Read CI logs for a given pull request.",
+    inputSchema: ReadCiLogsInputJsonSchema as any,
+  },
+  {
+    name: "repo.logs",
+    description: "Stream or grep combined CI logs for all jobs in a pull request.",
+    inputSchema: RepoLogsInputJsonSchema as any,
+  },
+  {
+    name: "repo.create_branch",
+    description: "Creates a new clean git branch from a target base branch.",
+    inputSchema: CreateBranchInputJsonSchema as any,
+  },
+  {
+    name: "repo.create_repair_branch",
+    description: "Creates a fresh worktree and a new repair branch for an existing PR. This isolates the repair work from the main codebase.",
+    inputSchema: CreateRepairBranchInputJsonSchema as any,
+  },
+  {
+    name: "repo.run_tests",
+    description: "Run repository tests and checks.",
+    inputSchema: RunTestsInputJsonSchema as any,
+  },
+  {
+    name: "repo.run_lighthouse",
+    description: "Run Lighthouse CI audits.",
+    inputSchema: RunLighthouseInputJsonSchema as any,
+  },
+  {
+    name: "repo.run_playwright",
+    description: "Run Playwright E2E tests.",
+    inputSchema: RunPlaywrightInputJsonSchema as any,
+  },
+  {
+    name: "repo.commit_patch",
+    description: "Commit verified repair changes in a worktree.",
+    inputSchema: CommitPatchInputJsonSchema as any,
+  },
+  {
+    name: "github.open_replacement_pr",
+    description: "Open a new PR that replaces or repairs the original PR.",
+    inputSchema: OpenReplacementPrInputJsonSchema as any,
+  },
+  {
+    name: "github.create_pull_request",
+    description: "Creates a pull request on GitHub using the MCP server's integrated credentials. Bypasses terminal CLI constraints.",
+    inputSchema: CreatePullRequestInputJsonSchema as any,
+  },
+  {
+    name: "github.comment_triage_summary",
+    description: "Comment on the original PR with a diagnosis and replacement link.",
+    inputSchema: CommentTriageSummaryInputJsonSchema as any,
+  },
+  {
+    name: "github.get_pr",
+    description: "Get details of a GitHub PR including title, state, and URLs.",
+    inputSchema: GetPrInputJsonSchema as any,
+  },
+  {
+    name: "github.issue_view",
+    description: "View details of a GitHub issue including title, body, and state.",
+    inputSchema: IssueViewInputJsonSchema as any,
+  },
+  {
+    name: "github.issue_update",
+    description: "Update a GitHub issue's body, labels, and/or state.",
+    inputSchema: IssueUpdateInputJsonSchema as any,
+  },
+  {
+    name: "github.issue_comment",
+    description: "Add a new comment to a GitHub issue.",
+    inputSchema: IssueCommentInputJsonSchema as any,
+  },
+  {
+    name: "github.create_issue",
+    description: "Create a new GitHub issue.",
+    inputSchema: CreateIssueInputJsonSchema as any,
+  },
+  {
+    name: "jules.create_session",
+    description: "Create a Jules session that performs work externally and may generate a GitHub pull request.",
+    inputSchema: CreateJulesSessionInputJsonSchema as any,
+  },
+  {
+    name: "jules.get_session",
+    description: "Get the status and details of a Jules session.",
+    inputSchema: JulesSessionIdInputJsonSchema as any,
+  },
+  {
+    name: "jules.send_message",
+    description: "Send a message to an active Jules session.",
+    inputSchema: JulesSendMessageInputJsonSchema as any,
+  },
+  {
+    name: "jules.get_messages",
+    description: "Get the message history of a Jules session.",
+    inputSchema: JulesSessionIdInputJsonSchema as any,
+  },
+  {
+    name: "jules.list_sessions",
+    description: "List all Jules sessions.",
+    inputSchema: JulesListSessionsInputJsonSchema as any,
+  },
+  {
+    name: "jules.cancel_session",
+    description: "Cancel an ongoing Jules session.",
+    inputSchema: JulesSessionIdInputJsonSchema as any,
+  },
+  {
+    name: "jules.get_pr",
+    description: "Get the generated pull request url associated with an active Jules agent session.",
+    inputSchema: JulesSessionIdInputJsonSchema as any,
+  },
+  {
+    name: "jules.trigger_feedback",
+    description: "Automatically collect CI status/logs for the PR associated with a Jules session and send them back as feedback.",
+    inputSchema: JulesSessionIdInputJsonSchema as any,
+  },
+  {
+    name: "agent.search_ddgs",
+    description: "Search the web using DuckDuckGo (via ddgs python library).",
+    inputSchema: SearchDdgsInputJsonSchema as any,
+  },
+];

package/src/mcp/server.ts

@@ -0,0 +1,359 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { config } from "../config.js";
+import { createSuccessResult, createErrorResult } from "../lib/result.js";
+import { MCP_TOOLS, MCP_PROMPTS, MCP_RESOURCES } from "./definitions.js";
+import { healthHandler, HealthCheckInputSchema } from "./tools.js";
+import { searchOpenPrsHandler, SearchOpenPrsInputSchema } from "../tools/github.search_open_prs.js";
+import { getPrDiffHandler, GetPrDiffInputSchema } from "../tools/github.get_pr_diff.js";
+import { getMergeConflictFilesHandler, GetMergeConflictFilesInputSchema } from "../tools/github.get_merge_conflict_files.js";
+import { checkoutBranchHandler, CheckoutBranchInputSchema } from "../tools/github.checkout_branch.js";
+import { getChangedFilesHandler, GetChangedFilesInputSchema } from "../tools/repo.get_changed_files.js";
+import { readAgentContextHandler, ReadAgentContextInputSchema } from "../tools/repo.read_agent_context.js";
+import { getCommandSchemaHandler, GetCommandSchemaInputSchema } from "../tools/repo.get_command_schema.js";
+import { getPackageScriptsHandler, GetPackageScriptsInputSchema } from "../tools/repo.get_package_scripts.js";
+import { getRouteMapHandler, GetRouteMapInputSchema } from "../tools/repo.get_route_map.js";
+import { readCiLogsHandler, ReadCiLogsInputSchema } from "../tools/repo.read_ci_logs.js";
+import { repoLogsHandler, RepoLogsInputSchema } from "../tools/repo.logs.js";
+import { createRepairBranchHandler, CreateRepairBranchInputSchema } from "../tools/repo.create_repair_branch.js";
+import { createBranchHandler, CreateBranchInputSchema } from "../tools/repo.create_branch.js";
+import { runTestsHandler, RunTestsInputSchema } from "../tools/repo.run_tests.js";
+import { runLighthouseHandler, RunLighthouseInputSchema } from "../tools/repo.run_lighthouse.js";
+import { runPlaywrightHandler, RunPlaywrightInputSchema } from "../tools/repo.run_playwright.js";
+import { commitPatchHandler, CommitPatchInputSchema } from "../tools/repo.commit_patch.js";
+import { openReplacementPrHandler, OpenReplacementPrInputSchema } from "../tools/github.open_replacement_pr.js";
+import { commentTriageSummaryHandler, CommentTriageSummaryInputSchema } from "../tools/github.comment_triage_summary.js";
+import { createPullRequestHandler, CreatePullRequestInputSchema } from "../tools/github.create_pull_request.js";
+import { getPrHandler, GetPrInputSchema } from "../tools/github.get_pr.js";
+import { issueViewHandler, IssueViewInputSchema } from "../tools/github.issue_view.js";
+import { issueUpdateHandler, IssueUpdateInputSchema } from "../tools/github.issue_update.js";
+import { issueCommentHandler, IssueCommentInputSchema } from "../tools/github.issue_comment.js";
+import { createIssueHandler, CreateIssueInputSchema } from "../tools/github.create_issue.js";
+
+
+import { createJulesSessionHandler, CreateJulesSessionInputSchema } from "../tools/jules/create-session.js";
+import { getJulesSessionHandler, GetJulesSessionInputSchema } from "../tools/jules/get-session.js";
+import { sendJulesMessageHandler, SendJulesMessageInputSchema } from "../tools/jules/send-message.js";
+import { getJulesMessagesHandler, GetJulesMessagesInputSchema } from "../tools/jules/get-messages.js";
+import { listJulesSessionsHandler, ListJulesSessionsInputSchema } from "../tools/jules/list-sessions.js";
+import { cancelJulesSessionHandler, CancelJulesSessionInputSchema } from "../tools/jules/cancel-session.js";
+import { getJulesPullRequestHandler, GetJulesPullRequestInputSchema } from "../tools/jules/get-pr.js";
+import { triggerJulesFeedbackHandler, TriggerJulesFeedbackInputSchema } from "../tools/jules/trigger-feedback.js";
+import { ddgsSearchHandler, DdgsSearchInputSchema } from "../tools/ddgs.search.js";
+
+import fs from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+
+export class BoomtickMCPServer {
+  private server: Server;
+
+  constructor() {
+    this.server = new Server(
+      {
+        name: "boomtick-mcp",
+        version: "0.2.0",
+      },
+      {
+        capabilities: {
+          tools: {},
+          resources: {},
+          prompts: {},
+        },
+      }
+    );
+
+    this.setupToolHandlers();
+    this.setupResourceHandlers();
+    this.setupPromptHandlers();
+  }
+
+  private setupPromptHandlers() {
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      return {
+        prompts: MCP_PROMPTS,
+      };
+    });
+
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const name = request.params.name;
+
+      const agentsDir = path.resolve(config.repoPath, "mcp/src/agents");
+      // nosemgrep
+      const promptPath = path.resolve(agentsDir, `${name}.prompt.md`);
+
+      if (!promptPath.startsWith(agentsDir + path.sep)) {
+        throw new Error("Path traversal detected");
+      }
+
+      try {
+        const content = await fs.readFile(promptPath, "utf-8");
+        return {
+          messages: [
+            {
+              role: "user",
+              content: { type: "text", text: content },
+            },
+          ],
+        };
+      } catch (e) {
+        throw new Error(`Prompt not found: ${name}`);
+      }
+    });
+  }
+
+  private setupResourceHandlers() {
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      return {
+        resources: MCP_RESOURCES,
+      };
+    });
+
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const uri = request.params.uri;
+      if (uri === "repo://package-json") {
+        const content = await fs.readFile(path.join(config.repoPath, "package.json"), "utf-8");
+        return {
+          contents: [{ uri, mimeType: "application/json", text: content }],
+        };
+      }
+      if (uri === "repo://routes") {
+        const routeMap = await getRouteMapHandler({});
+        return {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(routeMap, null, 2) }],
+        };
+      }
+      if (uri === "repo://design-tokens") {
+        const tokensPath = path.join(config.repoPath, "src/styles/design-tokens.ts");
+        const content = await fs.readFile(tokensPath, "utf-8");
+        return {
+          contents: [{ uri, mimeType: "text/typescript", text: content }],
+        };
+      }
+      if (uri.startsWith("repo://diff/")) {
+        const prNumber = parseInt(uri.split("/").pop() || "");
+        const diff = await getPrDiffHandler({ prNumber });
+        return {
+          contents: [{ uri, mimeType: "text/plain", text: diff.diffText }],
+        };
+      }
+      if (uri.startsWith("repo://ci/")) {
+        const prNumber = parseInt(uri.split("/").pop() || "");
+        const logs = await readCiLogsHandler({ prNumber });
+        return {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(logs, null, 2) }],
+        };
+      }
+      if (uri.startsWith("repo://lighthouse/")) {
+        const branch = uri.split("/").pop() || "";
+        const report = await runLighthouseHandler({ route: "/", worktreePath: `../boomtick-mcp-rescue-${branch}` });
+        return {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(report, null, 2) }],
+        };
+      }
+      if (uri.startsWith("repo://playwright/")) {
+        const branch = uri.split("/").pop() || "";
+        const report = await runPlaywrightHandler({ worktreePath: `../boomtick-mcp-rescue-${branch}` });
+        return {
+          contents: [{ uri, mimeType: "application/json", text: JSON.stringify(report, null, 2) }],
+        };
+      }
+      throw new Error(`Resource not found: ${uri}`);
+    });
+  }
+
+  private setupToolHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: MCP_TOOLS,
+      };
+    });
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        switch (request.params.name) {
+          case "boomtick.health":
+            return createSuccessResult(await healthHandler(HealthCheckInputSchema.parse(request.params.arguments || {})));
+          case "github.search_open_prs":
+            return createSuccessResult(await searchOpenPrsHandler(SearchOpenPrsInputSchema.parse(request.params.arguments || {})));
+          case "repo.read_agent_context":
+            return createSuccessResult(await readAgentContextHandler(ReadAgentContextInputSchema.parse(request.params.arguments || {})));
+          case "github.get_pr_diff":
+            return createSuccessResult(await getPrDiffHandler(GetPrDiffInputSchema.parse(request.params.arguments)));
+          case "github.get_merge_conflict_files":
+            return createSuccessResult(await getMergeConflictFilesHandler(GetMergeConflictFilesInputSchema.parse(request.params.arguments)));
+          case "github.checkout_branch":
+            return createSuccessResult(await checkoutBranchHandler(CheckoutBranchInputSchema.parse(request.params.arguments)));
+          case "repo.get_changed_files":
+            return createSuccessResult(await getChangedFilesHandler(GetChangedFilesInputSchema.parse(request.params.arguments || {})));
+          case "repo.get_command_schema":
+            return createSuccessResult(await getCommandSchemaHandler(GetCommandSchemaInputSchema.parse(request.params.arguments)));
+          case "repo.get_package_scripts":
+            return createSuccessResult(await getPackageScriptsHandler(GetPackageScriptsInputSchema.parse(request.params.arguments || {})));
+          case "repo.get_route_map":
+            return createSuccessResult(await getRouteMapHandler(GetRouteMapInputSchema.parse(request.params.arguments || {})));
+          case "repo.read_ci_logs":
+            return createSuccessResult(await readCiLogsHandler(ReadCiLogsInputSchema.parse(request.params.arguments)));
+          case "repo.logs":
+            return createSuccessResult(await repoLogsHandler(RepoLogsInputSchema.parse(request.params.arguments)));
+          case "repo.create_branch":
+            return createSuccessResult(await createBranchHandler(CreateBranchInputSchema.parse(request.params.arguments)));
+          case "repo.create_repair_branch":
+            return createSuccessResult(await createRepairBranchHandler(CreateRepairBranchInputSchema.parse(request.params.arguments)));
+          case "repo.run_tests":
+            return createSuccessResult(await runTestsHandler(RunTestsInputSchema.parse(request.params.arguments || {})));
+          case "repo.run_lighthouse":
+            return createSuccessResult(await runLighthouseHandler(RunLighthouseInputSchema.parse(request.params.arguments || {})));
+          case "repo.run_playwright":
+            return createSuccessResult(await runPlaywrightHandler(RunPlaywrightInputSchema.parse(request.params.arguments || {})));
+          case "repo.commit_patch":
+            return createSuccessResult(await commitPatchHandler(CommitPatchInputSchema.parse(request.params.arguments)));
+          case "github.open_replacement_pr":
+            return createSuccessResult(await openReplacementPrHandler(OpenReplacementPrInputSchema.parse(request.params.arguments)));
+          case "github.comment_triage_summary":
+            return createSuccessResult(await commentTriageSummaryHandler(CommentTriageSummaryInputSchema.parse(request.params.arguments)));
+          case "github.create_pull_request":
+            return createSuccessResult(await createPullRequestHandler(CreatePullRequestInputSchema.parse(request.params.arguments)));
+          case "github.get_pr":
+            return createSuccessResult(await getPrHandler(GetPrInputSchema.parse(request.params.arguments)));
+          case "github.issue_view":
+            return createSuccessResult(await issueViewHandler(IssueViewInputSchema.parse(request.params.arguments)));
+          case "github.issue_update":
+            return createSuccessResult(await issueUpdateHandler(IssueUpdateInputSchema.parse(request.params.arguments)));
+          case "github.issue_comment":
+            return createSuccessResult(await issueCommentHandler(IssueCommentInputSchema.parse(request.params.arguments)));
+          case "github.create_issue":
+            return createSuccessResult(await createIssueHandler(CreateIssueInputSchema.parse(request.params.arguments)));
+
+
+
+          case "jules.create_session":
+            return createSuccessResult(await createJulesSessionHandler(CreateJulesSessionInputSchema.parse(request.params.arguments)));
+          case "jules.get_session":
+            return createSuccessResult(await getJulesSessionHandler(GetJulesSessionInputSchema.parse(request.params.arguments)));
+          case "jules.send_message":
+            return createSuccessResult(await sendJulesMessageHandler(SendJulesMessageInputSchema.parse(request.params.arguments)));
+          case "jules.get_messages":
+            return createSuccessResult(await getJulesMessagesHandler(GetJulesMessagesInputSchema.parse(request.params.arguments)));
+          case "jules.list_sessions":
+            return createSuccessResult(await listJulesSessionsHandler(ListJulesSessionsInputSchema.parse(request.params.arguments || {})));
+          case "jules.cancel_session":
+            return createSuccessResult(await cancelJulesSessionHandler(CancelJulesSessionInputSchema.parse(request.params.arguments)));
+          case "jules.get_pr":
+            return createSuccessResult(await getJulesPullRequestHandler(GetJulesPullRequestInputSchema.parse(request.params.arguments)));
+          case "jules.trigger_feedback":
+            return createSuccessResult(await triggerJulesFeedbackHandler(TriggerJulesFeedbackInputSchema.parse(request.params.arguments)));
+          case "agent.search_ddgs":
+            return createSuccessResult(await ddgsSearchHandler(DdgsSearchInputSchema.parse(request.params.arguments)));
+          default:
+            return createErrorResult(`Tool not found: ${request.params.name}`);
+        }
+      } catch (error) {
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+      }
+    });
+  }
+  async run() {
+    const projectRoot = config.repoPath || process.cwd();
+    const homeDir = process.env.HOME || "";
+    const extraPaths = [];
+
+    // 1. DYNAMIC PYTHON PATH (pip / virtualenv discovery)
+    const venvDirs = [".venv", "venv", "env"];
+    for (const venvDir of venvDirs) {
+      const venvBin = path.join(projectRoot, venvDir, "bin");
+      if (existsSync(venvBin)) {
+        extraPaths.push(venvBin);
+        break;
+      }
+    }
+
+    // 2. DYNAMIC NODE PATH (.nvmrc parsing)
+    const nvmrcPath = path.join(projectRoot, ".nvmrc");
+    let targetNodeVersion = "";
+
+    if (existsSync(nvmrcPath)) {
+      const rawVersion = readFileSync(nvmrcPath, "utf-8").trim();
+      targetNodeVersion = rawVersion.startsWith("v") ? rawVersion : `v${rawVersion}`;
+    }
+
+    if (homeDir) {
+      extraPaths.push(
+        path.join(homeDir, ".local", "bin"),
+        path.join(homeDir, "miniforge3", "bin"),
+        path.join(homeDir, "anaconda3", "bin"),
+        path.join(homeDir, "miniconda3", "bin")
+      );
+
+      if (process.env.NVM_BIN) {
+        extraPaths.push(process.env.NVM_BIN);
+      } else if (targetNodeVersion) {
+        extraPaths.push(path.join(homeDir, ".nvm", "versions", "node", targetNodeVersion, "bin"));
+      } else {
+        extraPaths.push(path.join(homeDir, ".nvm", "versions", "node", process.version, "bin"));
+      }
+    }
+
+    extraPaths.push(path.dirname(process.execPath));
+
+    const currentPath = process.env.PATH || "";
+    const updatedPaths = [...extraPaths, ...currentPath.split(path.delimiter)];
+    process.env.PATH = Array.from(new Set(updatedPaths))
+      .filter(Boolean)
+      .join(path.delimiter);
+
+    // 3. SAFE REPOSITORY RESOLUTION
+    const repoPath = config.repoPath || projectRoot;
+
+    // 4. SECURE, UNIX-ONLY PRE-FLIGHT CHECK FOR TD-CLI
+    try {
+      const result = spawnSync("td-cli", ["doctor"], { 
+        encoding: "utf-8", 
+        cwd: repoPath,
+        shell: false // Explicitly disabled to clear Semgrep rules
+      });
+
+      if (result.error) {
+        throw result.error;
+      }
+
+      if (result.status !== 0) {
+        console.error("status:", result.status);
+        console.error("stdout:", result.stdout);
+        console.error("stderr:", result.stderr);
+        throw new Error(`td-cli doctor returned exit code: ${result.status}`);
+      }
+
+      console.error("✅ td-cli verified on PATH securely");
+    } catch (error) {
+      console.error("❌ Fatal: td-cli is not resolvable on PATH. MCP tools will fail.");
+      console.error("Please ensure the project is installed: pip install -e .");
+      console.error("❌ Fatal: td-cli pre-flight check failed:", error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const ddgsScriptPath = path.join(__dirname, "..", "tools", "ddgs_search.py");
+    try {
+      await fs.access(ddgsScriptPath);
+    } catch (err) {
+      console.error(`❌ Fatal: ddgs_search.py not found at ${ddgsScriptPath}`);
+      process.exit(1);
+    }
+
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error("Boomtick MCP Server running on stdio");
+  }
+}

package/src/mcp/tools.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { config } from "../config.js";
+
+export const HealthCheckInputSchema = z.object({
+  checkDeep: z.boolean().optional().default(false),
+});
+
+export async function healthHandler(args: z.infer<typeof HealthCheckInputSchema>) {
+  HealthCheckInputSchema.parse(args);
+  return {
+    status: "ok",
+    config: {
+      githubOwner: config.githubOwner,
+      githubRepo: config.githubRepo,
+      repoPath: config.repoPath,
+      readOnly: !config.githubToken,
+      ghPath: config.ghPath
+    },
+  };
+}