@reneturcios/greenlight 0.3.7 → 0.3.8

package/README.md

@@ -2,6 +2,12 @@
 
 Greenlight checks a GitHub issue before you spend hours on it, and tells you in plain words whether your pull request is likely to land.
 
+**New:** [The Contribution Friction Index](https://cloudcorprecords.github.io/greenlight/) ranks 43 well known projects by how hard it really is to get a pull request merged, from live GitHub data.
+
+## Use Greenlight inside your AI coding tool
+
+Greenlight ships an agent drop-in pack in [`integrations/`](integrations/README.md): ready-to-copy MCP configs for Claude Code, Cursor, VS Code / Copilot, Windsurf, and Cline, plus instruction snippets that teach your agent the one behavior rule: **check Greenlight before it opens a PR.** Verify with a "list your MCP tools" prompt; the greenlight server carries 8 tools (check_issue, scan_repo, repo_friction, claim_issue, prep_issue, open_pr, ci_triage, review_triage).
+
 ## The problem
 
 You find an issue that looks perfect. You code all evening. Then one of these happens:

package/dist/index.js

@@ -14,7 +14,7 @@ import { fetchMergeVelocity } from "./merge-velocity.js";
 import { createRestClient, claimIssue, prepIssue, openPr, AutomationRefusal, } from "./automate.js";
 import { triagePr } from "./ci-triage.js";
 import { triageReview } from "./review-triage.js";
-const server = new McpServer({ name: "greenlight", version: "0.3.7" });
+const server = new McpServer({ name: "greenlight", version: "0.3.8" });
 const text = (obj) => ({
     content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
 });

package/integrations/README.md

@@ -0,0 +1,59 @@
+# Greenlight agent drop-in pack
+
+One behavior rule, everywhere: **your agent checks Greenlight before it
+opens a pull request.** The configs below register Greenlight's MCP server
+and teach the agent the workflow: check the issue first, stop on TAKEN or
+GATED, triage red CI before touching code, triage reviews before fixing,
+and never post anything to GitHub without the human's go-ahead.
+
+## Install per tool
+
+| Tool | Copy this file | To this destination |
+|---|---|---|
+| Claude Code | `claude-code/.mcp.json` | your project root as `.mcp.json` |
+| Claude Code | `claude-code/CLAUDE.snippet.md` | paste into your project's `CLAUDE.md` |
+| Cursor | `cursor/.cursor/mcp.json` | your project as `.cursor/mcp.json` |
+| Cursor | `cursor/greenlight.mdc` | your project as `.cursor/rules/greenlight.mdc` |
+| VS Code / Copilot | `copilot/.vscode/mcp.json` | your project as `.vscode/mcp.json` |
+| VS Code / Copilot | `copilot/copilot-instructions.snippet.md` | paste into `.github/copilot-instructions.md` |
+| Windsurf | `windsurf/mcp_config.json` | `~/.codeium/windsurf/mcp_config.json` (merge with existing) |
+| Cline | `cline/cline_mcp_settings.json` | your project as `.cline/mcp_settings.json` |
+| Anything else | `mcp.json` | wherever your client reads MCP configs |
+
+Restart the tool after installing. Every config launches the server as
+`npx -y @reneturcios/greenlight mcp`, so nothing is installed globally;
+the package downloads on first use. Set the `GITHUB_TOKEN` environment
+variable for the higher GitHub API rate limit (60 to 5000 requests/hour);
+without it the tools still work but share the small anonymous budget.
+
+## Verify it worked
+
+Ask the agent: "list your MCP tools." You should see the `greenlight`
+server with all 8 tools:
+
+- `check_issue` — verdict on whether an issue is landable (GO / RISKY / TAKEN / GATED / STALE)
+- `scan_repo` — find starter issues worth working in a repo
+- `repo_friction` — how hard it is to land an outside PR (0 to 100)
+- `claim_issue` — draft a claim comment shaped by the repo's gates (dry run by default)
+- `prep_issue` — fork/branch checklist, CLA path, house rules (dry run by default)
+- `open_pr` — compose the PR with the verdict and gates recorded (dry run by default)
+- `ci_triage` — is each red check pre-existing, yours, or an external blocker
+- `review_triage` — classify review findings and draft replies (never posts)
+
+## Format notes
+
+- Claude Code, Cursor, Windsurf, and Cline all use the `mcpServers` top
+  level key in their MCP config files.
+- VS Code's `.vscode/mcp.json` uses `servers` instead of `mcpServers`,
+  and stdio entries carry `"type": "stdio"`.
+- Windsurf's remote transports use `serverUrl` and `transport` instead of
+  `url` and `type`; this pack only needs stdio, so it uses the plain
+  command/args shape.
+
+Doc sources checked while building this pack: Claude Code `.mcp.json`
+shape (project root, `mcpServers`, stdio command/args) per Anthropic-adjacent
+project references; VS Code `.vscode/mcp.json` `servers` key per the VS Code
+MCP servers docs and multiple community configs; Cursor `.cursor/mcp.json`
+`mcpServers` and `.mdc` rules with `description`/`alwaysApply` frontmatter;
+Windsurf `~/.codeium/windsurf/mcp_config.json` per its command-palette
+"MCP Servers" docs; Cline `.cline/mcp_settings.json` with `mcpServers`.

package/integrations/claude-code/.mcp.json

@@ -0,0 +1 @@
+{"mcpServers":{"greenlight":{"args":["-y","@reneturcios/greenlight","mcp"],"command":"npx"}}}

package/integrations/claude-code/CLAUDE.snippet.md

@@ -0,0 +1,39 @@
+# Greenlight rules for Claude Code
+
+Paste this file's contents into your project's CLAUDE.md (or keep the file
+and reference it from CLAUDE.md). It teaches the agent the Greenlight
+workflow through the greenlight MCP tools.
+
+## Greenlight: check before you open a PR
+
+You have the Greenlight MCP server connected (server name: greenlight,
+8 tools: check_issue, scan_repo, repo_friction, claim_issue, prep_issue,
+open_pr, ci_triage, review_triage). It answers one question at every step:
+is this contribution worth doing, and is the problem mine?
+
+Rules:
+
+1. BEFORE writing any code for a GitHub issue, call `check_issue` with the
+   issue URL.
+   - If the verdict is TAKEN (someone already has an open PR) or GATED
+     (the repo will not accept this PR, e.g. external PRs are paused or
+     auto-closed): STOP. Tell the human why, quoting the reasons. Do not
+     start coding.
+   - If the verdict is RISKY: explain the risk and ask before continuing.
+   - If the verdict is GO: continue.
+2. Before claiming an issue or setting up to work it, call `prep_issue`
+   (dry run) to learn the repo's exact CLA path, house rules, changeset
+   convention, and whether the fix even lives in this repo. Report the
+   plan; do not create forks or branches without being asked.
+3. If the PR's CI goes red: call `ci_triage` BEFORE changing any code, and
+   tell the human whether each failure is pre-existing, likely yours,
+   indeterminate, or an external blocker.
+4. After review comments arrive: call `review_triage`. Fix likely-real
+   findings first, present needs-decision items to the human, and push
+   back on likely-noise only with the evidence the tool gives you. The
+   drafts are yours to adapt; the tool never posts them.
+5. NEVER post claim comments, open PRs, or write anything to GitHub without
+   the human's explicit go-ahead. Drafts are output only.
+
+Tip: set GITHUB_TOKEN in your environment for the higher GitHub API rate
+limit (60 to 5000 requests per hour).

package/integrations/cline/README.md

@@ -0,0 +1,14 @@
+# Cline install
+
+Cline reads MCP servers from `mcpSettings` in its settings. The portable
+file form is:
+
+    .cline/mcp_settings.json
+
+Copy the `cline_mcp_settings.json` file in this folder there (merging with
+any servers you already have), then check the Cline "MCP Servers" panel:
+the `greenlight` server should list 8 tools. The `disabled: false` field is
+Cline's way of keeping the server enabled without deleting it.
+
+Workflow: see the integrations README — your agent checks Greenlight
+before it opens a PR.

package/integrations/cline/cline_mcp_settings.json

@@ -0,0 +1 @@
+{"mcpServers":{"greenlight":{"args":["-y","@reneturcios/greenlight","mcp"],"command":"npx","disabled":false}}}

package/integrations/copilot/.vscode/mcp.json

@@ -0,0 +1 @@
+{"servers":{"greenlight":{"args":["-y","@reneturcios/greenlight","mcp"],"command":"npx","type":"stdio"}}}

package/integrations/copilot/copilot-instructions.snippet.md

@@ -0,0 +1,27 @@
+# Greenlight instructions for GitHub Copilot / VS Code
+
+Paste this file's contents into your project's
+`.github/copilot-instructions.md` (create the folder if it does not exist).
+
+## Greenlight: check before you open a PR
+
+You have the Greenlight MCP server connected (server `greenlight`, tools:
+check_issue, scan_repo, repo_friction, claim_issue, prep_issue, open_pr,
+ci_triage, review_triage). Apply these instructions whenever working on a
+pull request to an open source project:
+
+1. Before writing any code for a GitHub issue, call `check_issue` with the
+   issue URL. If the verdict is TAKEN or GATED, stop and tell the user why,
+   quoting the reasons. Never start work on a TAKEN or GATED issue without
+   being told to.
+2. Before claiming or setting up work, call `prep_issue` (dry run) to learn
+   the repo's exact CLA path, house rules, and changeset convention. Report
+   the plan; do not create forks or branches unasked.
+3. If the PR's CI goes red, call `ci_triage` before changing code, and tell
+   the user whether each failure is pre-existing, likely theirs,
+   indeterminate, or an external blocker.
+4. After review comments arrive, call `review_triage`. Fix likely-real
+   findings first; bring needs-decision items to the user; push back on
+   likely-noise only with the tool's evidence. Drafts are output only.
+5. Never post claim comments, open PRs, or write anything to GitHub without
+   the user's explicit go-ahead.

package/integrations/cursor/.cursor/mcp.json

@@ -0,0 +1 @@
+{"mcpServers":{"greenlight":{"args":["-y","@reneturcios/greenlight","mcp"],"command":"npx"}}}

package/integrations/cursor/greenlight.mdc

@@ -0,0 +1,27 @@
+---
+description: Greenlight contribution workflow — check issues before coding, triage CI and reviews
+alwaysApply: false
+---
+
+# Greenlight rules (drop-in for Cursor)
+
+You have the Greenlight MCP server connected (server `greenlight`, tools:
+check_issue, scan_repo, repo_friction, claim_issue, prep_issue, open_pr,
+ci_triage, review_triage). Apply these rules whenever the user is working on
+a pull request to an open source project:
+
+1. Before writing any code for a GitHub issue, call `check_issue` with the
+   issue URL. If the verdict is TAKEN or GATED, stop and tell the user why,
+   quoting the reasons. Never start work on a TAKEN or GATED issue without
+   being told to.
+2. Before claiming or setting up work, call `prep_issue` (dry run) to learn
+   the repo's exact CLA path, house rules, and changeset convention. Report
+   the plan; do not create forks or branches unasked.
+3. If the PR's CI goes red, call `ci_triage` before changing code, and tell
+   the user whether each failure is pre-existing, likely theirs,
+   indeterminate, or an external blocker.
+4. After review comments arrive, call `review_triage`. Fix likely-real
+   findings first; bring needs-decision items to the user; push back on
+   likely-noise only with the tool's evidence. Drafts are output only.
+5. Never post claim comments, open PRs, or write anything to GitHub without
+   the user's explicit go-ahead.

package/integrations/mcp.json

@@ -0,0 +1 @@
+{"mcpServers":{"greenlight":{"args":["-y","@reneturcios/greenlight","mcp"],"command":"npx"}}}

package/integrations/windsurf/README.md

@@ -0,0 +1,14 @@
+# Windsurf install
+
+Windsurf's global MCP config lives at:
+
+    ~/.codeium/windsurf/mcp_config.json
+
+Copy the `mcp_config.json` file in this folder there (merging with any
+servers you already have), then restart Windsurf and check its MCP panel:
+the `greenlight` server should list 8 tools. Newer Windsurf versions also
+accept a project-level `.windsurf/mcp.json` file using the same
+`mcpServers` format.
+
+Workflow: see the integrations README — your agent checks Greenlight
+before it opens a PR.

package/integrations/windsurf/mcp_config.json

@@ -0,0 +1 @@
+{"mcpServers":{"greenlight":{"args":["-y","@reneturcios/greenlight","mcp"],"command":"npx"}}}

package/package.json

@@ -25,7 +25,7 @@
     "test": "tsx --test test/*.test.ts"
   },
   "type": "module",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "mcpName": "io.github.CloudCorpRecords/greenlight",
   "publishConfig": {
     "access": "public"
@@ -37,6 +37,7 @@
   "homepage": "https://github.com/CloudCorpRecords/greenlight#readme",
   "files": [
     "dist",
-    "server.json"
+    "server.json",
+    "integrations"
   ]
 }

package/server.json

@@ -6,13 +6,13 @@
     "url": "https://github.com/CloudCorpRecords/greenlight",
     "source": "github"
   },
-  "version": "0.3.7",
+  "version": "0.3.8",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@reneturcios/greenlight",
-      "version": "0.3.7",
+      "version": "0.3.8",
       "runtimeHint": "npx",
       "packageArguments": [
         {