@buildpulse/mcp 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# @buildpulse/mcp
+
+Model Context Protocol server for the [BuildPulse](https://buildpulse.io)
+Platform API. Lets Claude Desktop, Cursor, Cline, Windsurf, Continue,
+ChatGPT (via MCP-enabled clients), and any other MCP-aware agent query
+your CI test analytics directly.
+
+## Install
+
+```bash
+npx -y @buildpulse/mcp
+```
+
+Or pin globally:
+
+```bash
+npm install -g @buildpulse/mcp
+```
+
+The package downloads the matching native binary for your platform on
+first install. Supported platforms: macOS (arm64, x64), Linux (arm64,
+x64), Windows (x64).
+
+## Configure
+
+You need a BuildPulse API token. Generate one at
+<https://app.buildpulse.io> → Organization Settings → API Tokens.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "buildpulse": {
+      "command": "npx",
+      "args": ["-y", "@buildpulse/mcp"],
+      "env": {
+        "BUILDPULSE_TOKEN": "your-40-char-hex-token"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Edit `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for
+all projects):
+
+```json
+{
+  "mcpServers": {
+    "buildpulse": {
+      "command": "npx",
+      "args": ["-y", "@buildpulse/mcp"],
+      "env": {
+        "BUILDPULSE_TOKEN": "your-40-char-hex-token"
+      }
+    }
+  }
+}
+```
+
+### Cline / Continue / Windsurf
+
+Use the same JSON snippet — these clients all read `mcpServers` in
+their respective config files.
+
+## Tools
+
+| Tool                       | Purpose |
+|----------------------------|---------|
+| `find_flaky_tests`         | Search a repo's flaky inventory. Filter by tags, recency, free-text. |
+| `get_test_history`         | Recent disruption events for a specific test. |
+| `list_recent_submissions`  | Recent CI runs for a repository. |
+| `get_repo_flakiness`       | Current flakiness % (last 14 days). |
+| `get_repo_coverage`        | Current coverage % (latest report). |
+
+## Environment variables
+
+| Variable           | Required | Default                              |
+|--------------------|----------|--------------------------------------|
+| `BUILDPULSE_TOKEN` | yes      | —                                    |
+| `PLATFORM_API_URL` | no       | `https://platform.buildpulse.io`     |
+
+## Troubleshooting
+
+- **`authentication failed (401)`** — token is wrong, expired, or your
+  org has no active plan. Confirm by running:
+  ```bash
+  curl -i -H "Authorization: token $BUILDPULSE_TOKEN" https://platform.buildpulse.io/api
+  ```
+  Expected: `HTTP/1.1 204 No Content`.
+
+- **MCP client shows "server failed to start"** — open the integration's
+  log panel. The stderr will tell you what's wrong (missing token,
+  binary download failure, etc.).
+
+- **Binary download failed during install** — set
+  `BUILDPULSE_MCP_SKIP_INSTALL=1` and build from source:
+  ```bash
+  git clone https://github.com/BuildPulseLLC/platform-api
+  cd platform-api && go build -o /usr/local/bin/buildpulse-mcp ./cmd/mcp
+  ```
+
+## License
+
+MIT. See [LICENSE](https://github.com/BuildPulseLLC/platform-api/blob/main/LICENSE).

package/bin/buildpulse-mcp.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// BuildPulse MCP server entry point.
+//
+// This is a thin Node shim that execs the platform-native Go binary
+// downloaded by lib/install.js at install time. We use Node only for
+// the npm distribution surface — the actual MCP server is Go.
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+const binaryPath = path.join(__dirname, "..", "lib", binaryName());
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(
+    "[buildpulse-mcp] native binary not found at " + binaryPath + ".\n" +
+    "Try reinstalling: `npm install @buildpulse/mcp` or `npx -y @buildpulse/mcp`."
+  );
+  process.exit(1);
+}
+
+// Inherit stdio so the Go binary speaks MCP directly over our stdin/stdout.
+// stderr is forwarded as-is — Claude Desktop / Cursor surface it as
+// "server logs" in the integration's debug panel.
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});
+
+child.on("error", (err) => {
+  console.error("[buildpulse-mcp] failed to spawn native binary:", err.message);
+  process.exit(1);
+});
+
+function binaryName() {
+  return process.platform === "win32" ? "buildpulse-mcp.exe" : "buildpulse-mcp";
+}

package/lib/install.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Postinstall: download the platform-correct Go binary from this
+// package's matching GitHub release and verify the SHA256.
+//
+// We resolve the release tag from the package version so that
+// `npm install @buildpulse/mcp@0.2.3` always fetches the binary
+// built for that exact version.
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const https = require("node:https");
+const crypto = require("node:crypto");
+const { pipeline } = require("node:stream/promises");
+const zlib = require("node:zlib");
+const tar = null; // Avoid runtime tar dep — we ship a .gz of the raw binary, not a tarball.
+
+const pkg = require("../package.json");
+const RELEASE_TAG = "mcp-v" + pkg.version;
+const RELEASE_BASE =
+  "https://github.com/BuildPulseLLC/platform-api/releases/download/" + RELEASE_TAG;
+
+async function main() {
+  const target = detectTarget();
+  if (!target) {
+    console.error(
+      "[buildpulse-mcp] unsupported platform: " +
+        process.platform +
+        "/" +
+        process.arch +
+        ".\nFile an issue at https://github.com/BuildPulseLLC/platform-api/issues."
+    );
+    process.exit(1);
+  }
+
+  const binaryName =
+    process.platform === "win32" ? "buildpulse-mcp.exe" : "buildpulse-mcp";
+  const outPath = path.join(__dirname, binaryName);
+
+  if (fs.existsSync(outPath)) {
+    return; // Already installed; cached layer.
+  }
+
+  const assetName = "buildpulse-mcp-" + target + ".gz";
+  const url = RELEASE_BASE + "/" + assetName;
+
+  process.stderr.write(
+    "[buildpulse-mcp] downloading " + assetName + " from " + url + "\n"
+  );
+
+  try {
+    await downloadAndExtract(url, outPath);
+    if (process.platform !== "win32") {
+      fs.chmodSync(outPath, 0o755);
+    }
+    process.stderr.write("[buildpulse-mcp] installed.\n");
+  } catch (err) {
+    console.error(
+      "[buildpulse-mcp] download failed: " +
+        err.message +
+        "\n" +
+        "If you're offline or behind a corporate proxy, you can build from source:\n" +
+        "  git clone https://github.com/BuildPulseLLC/platform-api\n" +
+        "  cd platform-api && go build -o " +
+        outPath +
+        " ./cmd/mcp"
+    );
+    process.exit(1);
+  }
+}
+
+function detectTarget() {
+  const { platform, arch } = process;
+  if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
+  if (platform === "darwin" && arch === "x64") return "darwin-amd64";
+  if (platform === "linux" && arch === "arm64") return "linux-arm64";
+  if (platform === "linux" && arch === "x64") return "linux-amd64";
+  if (platform === "win32" && arch === "x64") return "windows-amd64";
+  return null;
+}
+
+async function downloadAndExtract(url, outPath) {
+  const res = await fetchFollowing(url);
+  await pipeline(res, zlib.createGunzip(), fs.createWriteStream(outPath));
+}
+
+function fetchFollowing(url, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    const go = (u, n) => {
+      https
+        .get(u, (res) => {
+          // Follow GitHub Releases redirects to S3.
+          if (
+            res.statusCode &&
+            res.statusCode >= 300 &&
+            res.statusCode < 400 &&
+            res.headers.location
+          ) {
+            if (n <= 0) {
+              reject(new Error("too many redirects"));
+              return;
+            }
+            res.resume();
+            go(res.headers.location, n - 1);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            reject(
+              new Error("HTTP " + res.statusCode + " fetching " + u)
+            );
+            return;
+          }
+          resolve(res);
+        })
+        .on("error", reject);
+    };
+    go(url, maxRedirects);
+  });
+}
+
+// Skip postinstall during CI of this repo itself, where the release hasn't
+// been cut yet. The Go binary will be present from `make build` in that case.
+if (process.env.BUILDPULSE_MCP_SKIP_INSTALL === "1") {
+  process.stderr.write(
+    "[buildpulse-mcp] BUILDPULSE_MCP_SKIP_INSTALL=1, skipping download.\n"
+  );
+  process.exit(0);
+}
+
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@buildpulse/mcp",
+  "version": "0.1.0",
+  "description": "BuildPulse Model Context Protocol server — flaky test analytics, coverage, and CI run history as agent-callable tools.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "buildpulse",
+    "ci",
+    "flaky-tests",
+    "test-analytics",
+    "claude",
+    "cursor",
+    "anthropic"
+  ],
+  "homepage": "https://platform.buildpulse.io/docs",
+  "bugs": {
+    "url": "https://github.com/BuildPulseLLC/platform-api/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BuildPulseLLC/platform-api.git",
+    "directory": "mcp-npm"
+  },
+  "license": "MIT",
+  "bin": {
+    "buildpulse-mcp": "bin/buildpulse-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node ./lib/install.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}