issuewatcher-mcp 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mayank Kumar Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,229 @@
-# Temporary Holding Version
+# IssueWatcher for your AI assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Ask your AI assistant "What should I work on today?" and get back the GitHub issues that are actually worth your time, with the reason for each.**
+
+IssueWatcher is an [MCP](https://modelcontextprotocol.io) server. It watches the repositories you starred and the open-source libraries your own projects depend on, ranks their newest issues, and explains every score. It works inside Claude, Cursor, VS Code and other apps that support MCP.
+
+- **Pick up something to fix:** good first issues that are unassigned, fresh, and not already being fixed by someone else.
+- **See what may break your projects:** problems reported in the libraries you use, matched to the versions you use.
+- **Know why:** every issue comes with plain-language reasons, and `explain_issue` shows each signal and its points.
+- **Safe:** every tool is read-only. It never comments on, assigns or changes anything on GitHub.
+- **Free, and no AI key needed:** your assistant does the reasoning with its own model. IssueWatcher only needs a GitHub token.
+
+> Status: early version (0.x). The ranking is rule-based and hand-tuned; it has been checked by reading real results, not yet against a large labelled data set. Feedback is very welcome: [open an issue](https://github.com/mac146/IssueWatcher/issues).
+
+## Quick start (about two minutes)
+
+### 1. Get a GitHub token
+
+IssueWatcher reads your list of starred repositories, so it needs a token. Read-only is enough.
+
+1. Open <https://github.com/settings/personal-access-tokens/new> (GitHub, then Settings, Developer settings, Personal access tokens, Fine-grained tokens).
+2. **Token name:** `IssueWatcher`. **Expiration:** 90 days is a good choice (you can regenerate it).
+3. **Repository access:**
+   - *Public repositories (read-only)* is enough to watch your stars and public dependencies.
+   - To also read the `package.json` / `requirements.txt` of **your private repositories**, choose *All repositories* (or select the ones you want) and under *Repository permissions* set **Contents: Read-only**.
+4. Click **Generate token** and copy it (it starts with `github_pat_`). You will not be able to see it again.
+
+A classic token (starts with `ghp_`) with the `public_repo` scope also works. Never paste a token into a chat or commit it to a repository.
+
+### 2. Add IssueWatcher to your AI app
+
+Pick your app:
+
+<details>
+<summary><b>Claude Desktop (one click)</b></summary>
+
+1. Download `issuewatcher-<version>.mcpb` from the [latest release](https://github.com/mac146/IssueWatcher/releases).
+2. Open it with Claude Desktop (double-click it, or drag it into Claude Desktop's settings under Extensions).
+3. When asked, paste your GitHub token. It is stored in your computer's secure keychain.
+4. Turn the extension on.
+
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add issuewatcher -e GITHUB_TOKEN=github_pat_xxxxxxxx -- npx -y issuewatcher-mcp
+```
+
+Then run `/mcp` inside Claude Code to see it connected. The server is added for the current project folder; add `--scope user` to have it in every folder.
+
+**Windows PowerShell** swallows the `--`, which makes Claude Code fail with `unknown option '-y'`. Put the `--` in quotes:
+
+```powershell
+claude mcp add issuewatcher -e "GITHUB_TOKEN=github_pat_xxxxxxxx" '--' npx -y issuewatcher-mcp
+```
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "issuewatcher": {
+      "command": "npx",
+      "args": ["-y", "issuewatcher-mcp"],
+      "env": { "GITHUB_TOKEN": "github_pat_xxxxxxxx" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>VS Code (GitHub Copilot agent mode)</b></summary>
+
+Add this to `.vscode/mcp.json`. VS Code will ask for the token when the server starts, so it is not stored in the file:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "github_token", "description": "GitHub token", "password": true }
+  ],
+  "servers": {
+    "issuewatcher": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "issuewatcher-mcp"],
+      "env": { "GITHUB_TOKEN": "${input:github_token}" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Any other MCP app (Windsurf, Zed, Cline, ...)</b></summary>
+
+Use the same command in the app's MCP settings: command `npx`, arguments `-y issuewatcher-mcp`, environment variable `GITHUB_TOKEN`.
+
+</details>
+
+> **Windows:** if an app says it cannot start `npx`, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "issuewatcher-mcp"]`.
+
+### 3. Check it works (optional but recommended)
+
+```bash
+GITHUB_TOKEN=github_pat_xxxxxxxx npx -y issuewatcher-mcp --check
+```
+
+(On Windows PowerShell: `$env:GITHUB_TOKEN="github_pat_xxxxxxxx"; npx -y issuewatcher-mcp --check`.)
+
+You should see:
+
+```
+  [ok]   GitHub token found.
+  [ok]   Token works: signed in as <you>.
+  [ok]   API budget: 4994 of 5000 requests left (resets ...).
+  [ok]   Watching 51 repos: 16 starred, 35 from libraries your projects use (7.2s).
+
+All good. Add this server to your AI app, then ask: "What should I work on today?"
+```
+
+### 4. Ask
+
+Restart your AI app, then try:
+
+- *"What should I work on today?"*
+- *"Show me good first issues from the last 24 hours."*
+- *"What broke in my dependencies this week?"*
+- *"Why did you rank the first one so high?"*
+- *"Only show issues in nodejs/node and pydantic/pydantic."*
+- *"What repos are you watching for me?"*
+
+IssueWatcher starts loading your repositories as soon as your AI app starts it, so by the time you type your first question the answer is usually instant. If you ask within the first few seconds it may take up to about ten (longer on a slow connection); follow-up questions are instant for the next ten minutes. It looks at the 20 newest issues per repository in the time window.
+
+## What the assistant can do (the tools)
+
+| Tool | What it does |
+| --- | --- |
+| `get_ranked_issues` | Ranks recent issues. Options: `mode` (`contributor`, `consumer`, `both`), `since` (`24h`, `3d`, `7d`, up to `30d`), `limit` (1-25), `min_score`, `source` (`starred`, `dependencies`, `both`), `repos`. |
+| `explain_issue` | Shows every signal behind one issue's score, how it relates to your repos and dependencies, and (only if asked) a short excerpt of the issue text. |
+| `list_watched_repos` | Shows which repos are watched and why, including which of your projects use which library. |
+
+There is also a prompt, `issue_radar`, that some apps show as a shortcut.
+
+## How the ranking works
+
+Every issue gets a score from 0 to 100 from transparent rules, each with a reason you can read:
+
+- **Why it is on your radar:** a repo you starred, or a library one of your projects depends on (runtime counts more than dev tools).
+- **Could you pick it up?** `good first issue` or `help wanted` labels, unassigned, opened recently, few comments, reproduction steps. Issues already assigned, claimed by a team, or where the reporter says they are opening a PR are scored down.
+- **Could it break you?** the issue mentions a version in your range, or words like crash, regression, CVE.
+- **Noise is scored down:** bots, questions, duplicates, vague or throwaway titles.
+
+The rules and the reasoning behind them are written down in [DECISIONS.md](https://github.com/mac146/IssueWatcher/blob/main/DECISIONS.md). They are tuned by hand and still being validated, so use the reasons to judge each result yourself.
+
+## Settings
+
+Set these as environment variables for the server (all optional except the token):
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `GITHUB_TOKEN` | none | Required. A GitHub token (`GH_TOKEN` also works). |
+| `SCORING_MODE` | `both` | `contributor`, `consumer` or `both`. The assistant can override it per question. |
+| `DEPENDENCY_SCAN` | `true` | Set `false` to watch only starred repos. |
+| `DEPENDENCY_REPOS` | your recently pushed repos | Comma-separated `owner/name` list of your projects to scan for dependencies. |
+| `IGNORE_REPOS` | none | Repos to never show, with `*` wildcards, e.g. `bootcamp-*/*`. |
+| `IGNORE_LABELS` | none | Labels to hide, e.g. `question,duplicate`. |
+| `ISSUEWATCHER_CACHE_DIR` | `~/.issuewatcher` | Where the dependency list is cached (for 24 hours). |
+| `ISSUEWATCHER_PREFETCH` | `true` | Load your repos and recent issues in the background when the server starts, so your first question is fast. Set `false` to load only when asked. |
+
+## Security and privacy
+
+- **Read-only.** No tool can write to GitHub. Your token can be read-only too, and should be.
+- **Your token stays on your computer** and is only sent to GitHub. It is never written to logs or included in any tool result.
+- **No telemetry.** IssueWatcher sends nothing to its author. It contacts only `api.github.com`, and the npm and PyPI registries to find where your dependencies live.
+- **What your AI app sees:** issue titles, labels, scores and links. Issue bodies are **not** included unless you ask for an excerpt.
+- **Issue text is written by strangers.** A malicious issue could try to trick an AI into following instructions hidden in it ("prompt injection"). IssueWatcher strips hidden characters, link targets and markup, caps lengths, labels excerpts as untrusted, and tells the model never to obey them. This lowers the risk, it cannot remove it. If you also give your assistant tools that can write to GitHub, use a **separate read-only token** for IssueWatcher and keep write actions behind confirmation. See [D-033](https://github.com/mac146/IssueWatcher/blob/main/DECISIONS.md) for the full reasoning.
+
+See also [PRIVACY.md](https://github.com/mac146/IssueWatcher/blob/main/docs/PRIVACY.md).
+
+## Do I need an LLM API key?
+
+**No.** IssueWatcher itself never calls an AI model. Your assistant (Claude, Cursor's models, Copilot, ...) reads the ranked list with its own model and its own login. Nothing to configure here.
+
+LLM API keys (Gemini, OpenAI, Claude, Groq, ...) are only used by the *separate* [email digest](https://github.com/mac146/IssueWatcher/blob/main/README.md) part of this project, which can send you a daily email of summaries.
+
+## Troubleshooting
+
+| Symptom | What to try |
+| --- | --- |
+| App shows "server disconnected" or no tools | Run the `--check` command from step 3 in a terminal; it prints the exact problem. Make sure Node.js 20 or newer is installed (`node --version`). |
+| "needs a GitHub token" | The token is missing or not passed to the server. Re-check the `env` / `-e` setting and restart the app. |
+| "GitHub rejected the token (401)" | The token expired or was copied wrongly. Create a new one. |
+| "No repositories to watch" | You have not starred any repositories yet. Star a few and try again. |
+| No dependencies found | Dependency matching reads `package.json` / `requirements.txt` in your recently pushed repos. For private repos the token needs **Contents: Read-only**. Or list projects with `DEPENDENCY_REPOS`. |
+| First answer is slow, or says "still loading" | The first load of ~50 repos takes up to ten seconds, longer on a slow connection. Ask again in a few seconds: the work continues in the background. If a scan runs out of its 20-second limit the answer says so and lists how many repos it did not reach. |
+| Results look wrong | Ask "explain the first one" and read the signals; then [tell us](https://github.com/mac146/IssueWatcher/issues). That feedback is how the ranking improves. |
+
+## Run it another way
+
+**From source:**
+
+```bash
+git clone https://github.com/mac146/IssueWatcher && cd IssueWatcher/mcp-server
+npm ci && npm run build
+GITHUB_TOKEN=github_pat_xxxxxxxx node build/mcp/main.js --check
+```
+
+Use `node /full/path/to/IssueWatcher/mcp-server/build/mcp/main.js` as the command in your app's config.
+
+**With Docker** (the server speaks MCP over stdio, so keep `-i`):
+
+```bash
+docker build --target mcp -t issuewatcher-mcp mcp-server
+docker run -i --rm -e GITHUB_TOKEN=github_pat_xxxxxxxx issuewatcher-mcp
+```
+
+## Uninstall
+
+Remove it from your AI app's settings, then delete the cache folder (`~/.issuewatcher`) and revoke the token at <https://github.com/settings/personal-access-tokens>.

package/build/deps/discovery.js

@@ -0,0 +1,133 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { logger } from "../logger.js";
+import { MANIFEST_FILES, parseManifest } from "./manifests.js";
+const DAY_MS = 86_400_000;
+async function inPool(items, size, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(size, items.length) }, async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    }));
+    return out;
+}
+/**
+ * Collects the dependencies declared across the user's repos, keeps the most
+ * widely used ones, and maps each to the GitHub repo that hosts its source.
+ * Packages whose repo can't be resolved are skipped (and logged at debug level).
+ */
+export async function discoverDependencies(source, registry, opts, now = Date.now) {
+    let repos;
+    if (opts.repos.length) {
+        repos = opts.repos.map((r) => {
+            const [owner, name] = r.split("/");
+            return { owner: owner, name: name };
+        });
+    }
+    else {
+        const cutoff = now() - opts.activeWithinDays * DAY_MS;
+        repos = (await source.listOwnRepos())
+            .filter((r) => !r.pushedAt || Date.parse(r.pushedAt) >= cutoff)
+            .slice(0, opts.maxRepos);
+    }
+    const aggregated = new Map();
+    await inPool(repos, 4, async ({ owner, name }) => {
+        for (const file of MANIFEST_FILES) {
+            let text;
+            try {
+                text = await source.getFile(owner, name, file);
+            }
+            catch (err) {
+                logger.warn(`Could not read ${owner}/${name}/${file}`, err);
+                continue;
+            }
+            if (!text)
+                continue;
+            for (const dep of parseManifest(file, text)) {
+                const key = `${dep.ecosystem}:${dep.pkg}`;
+                const existing = aggregated.get(key);
+                if (existing) {
+                    existing.usedBy.add(`${owner}/${name}`);
+                    if (dep.kind === "runtime")
+                        existing.kind = "runtime";
+                }
+                else {
+                    aggregated.set(key, { ...dep, usedBy: new Set([`${owner}/${name}`]) });
+                }
+            }
+        }
+    });
+    // Most widely used first, runtime before dev, then alphabetical for stable output.
+    const ranked = [...aggregated.values()]
+        .sort((a, b) => b.usedBy.size - a.usedBy.size ||
+        Number(b.kind === "runtime") - Number(a.kind === "runtime") ||
+        a.pkg.localeCompare(b.pkg))
+        .slice(0, opts.maxDependencies);
+    const resolved = await inPool(ranked, 5, async (dep) => {
+        try {
+            return await registry.resolve(dep.ecosystem, dep.pkg);
+        }
+        catch (err) {
+            logger.warn(`Registry lookup failed for ${dep.ecosystem}:${dep.pkg}`, err);
+            return null;
+        }
+    });
+    const map = {};
+    ranked.forEach((dep, i) => {
+        const repo = resolved[i];
+        if (!repo)
+            return;
+        (map[repo] ??= []).push({ ...dep, usedBy: [...dep.usedBy].sort() });
+    });
+    logger.info(`Dependency scan: ${repos.length} repo(s), ${aggregated.size} package(s), ${Object.keys(map).length} source repo(s) resolved`);
+    return map;
+}
+/**
+ * Wraps discovery with a disk cache so manifests and registries are not hit on
+ * every poll. If a refresh fails, the stale cache is used rather than losing
+ * the dependency watch list.
+ */
+export class CachedDiscovery {
+    run;
+    file;
+    ttlMs;
+    now;
+    constructor(run, file, ttlMs, now = Date.now) {
+        this.run = run;
+        this.file = file;
+        this.ttlMs = ttlMs;
+        this.now = now;
+    }
+    async get() {
+        const cached = await this.read();
+        if (cached && this.now() - cached.fetchedAt < this.ttlMs)
+            return cached.map;
+        try {
+            const map = await this.run();
+            await this.write({ fetchedAt: this.now(), map });
+            return map;
+        }
+        catch (err) {
+            logger.warn("Dependency discovery failed; using cached list if any", err);
+            return cached?.map ?? {};
+        }
+    }
+    async read() {
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.file, "utf-8"));
+            return typeof parsed.fetchedAt === "number" && parsed.map ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async write(data) {
+        await fs.mkdir(path.dirname(this.file), { recursive: true });
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(data), "utf-8");
+        await fs.rename(tmp, this.file);
+    }
+}

package/build/deps/manifests.js

@@ -0,0 +1,57 @@
+/** Files looked for at the root of each of the user's repos. */
+export const MANIFEST_FILES = ["package.json", "requirements.txt"];
+/** Specs that don't point at a registry package. */
+const NON_REGISTRY = /^(?:file:|link:|workspace:|git\+|git:|github:|https?:|npm:|\.{0,2}\/)/;
+export function parsePackageJson(text) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (typeof json !== "object" || json === null)
+        return [];
+    const manifest = json;
+    const out = [];
+    const add = (section, kind) => {
+        if (typeof section !== "object" || section === null)
+            return;
+        for (const [pkg, range] of Object.entries(section)) {
+            if (typeof range !== "string" || NON_REGISTRY.test(range))
+                continue;
+            out.push({ ecosystem: "npm", pkg, range, kind });
+        }
+    };
+    add(manifest.dependencies, "runtime");
+    add(manifest.devDependencies, "dev");
+    return out;
+}
+/** Handles `name==1.2`, `name>=1.2,<2`, extras (`name[extra]`) and markers (`; python_version...`). */
+export function parseRequirementsTxt(text) {
+    const out = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.split("#")[0].split(";")[0].trim();
+        if (!line || line.startsWith("-") || /^(?:git\+|https?:|\.{0,2}\/)/.test(line))
+            continue;
+        const m = line.match(/^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*(.*)$/);
+        if (!m)
+            continue;
+        out.push({ ecosystem: "pypi", pkg: m[1].toLowerCase().replace(/[_.]+/g, "-"), range: m[2].trim() || "*", kind: "runtime" });
+    }
+    return out;
+}
+export function parseManifest(file, text) {
+    if (file === "package.json")
+        return parsePackageJson(text);
+    if (file === "requirements.txt")
+        return parseRequirementsTxt(text);
+    return [];
+}
+/** Lowest version a range allows, e.g. "^1.6.0" -> 1.6, ">=2.1,<3" -> 2.1, "==4.0.1" -> 4.0. */
+export function minVersion(range) {
+    const m = range.match(/(\d+)(?:\.(\d+|x|\*))?/);
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: m[2] && /^\d+$/.test(m[2]) ? Number(m[2]) : 0 };
+}

package/build/deps/registry.js

@@ -0,0 +1,60 @@
+import axios from "axios";
+/**
+ * Extracts "owner/name" from the many spellings of a GitHub URL found in
+ * package metadata: git+https://…/o/r.git, github:o/r, git@github.com:o/r.git,
+ * https://github.com/o/r/tree/main/packages/x, and bare "o/r" shorthand.
+ */
+export function githubRepoFromUrl(url) {
+    if (!url)
+        return null;
+    const s = url.trim();
+    const m = s.match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i) ??
+        s.match(/^github:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i) ??
+        s.match(/^([\w.-]+)\/([\w.-]+)$/);
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+export class HttpRegistry {
+    client;
+    urls;
+    constructor(client = axios.create({
+        timeout: 15_000,
+        headers: { "User-Agent": "IssueWatcher" },
+    }), 
+    /** Overridden in tests (a local stub) and for registry mirrors. */
+    urls = { npm: "https://registry.npmjs.org", pypi: "https://pypi.org" }) {
+        this.client = client;
+        this.urls = urls;
+    }
+    async resolve(ecosystem, pkg) {
+        try {
+            return ecosystem === "npm" ? await this.npm(pkg) : await this.pypi(pkg);
+        }
+        catch (err) {
+            // An unknown package is a normal "no repo"; anything else should surface.
+            if (axios.isAxiosError(err) && err.response?.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    async npm(pkg) {
+        const res = await this.client.get(`${this.urls.npm}/${pkg.replace("/", "%2F")}/latest`);
+        const repo = res.data.repository;
+        return githubRepoFromUrl(typeof repo === "string" ? repo : repo?.url);
+    }
+    async pypi(pkg) {
+        const res = await this.client.get(`${this.urls.pypi}/pypi/${pkg}/json`);
+        const urls = res.data.info?.project_urls ?? {};
+        const preferred = ["Source", "Source Code", "Repository", "Code", "Homepage", "GitHub"];
+        const candidates = [
+            ...preferred.map((k) => urls[k]),
+            ...Object.values(urls),
+            res.data.info?.home_page,
+        ];
+        for (const url of candidates) {
+            const repo = githubRepoFromUrl(url);
+            if (repo)
+                return repo;
+        }
+        return null;
+    }
+}