issuewatcher-mcp 0.2.1 → 0.2.2

package/README.md

@@ -29,6 +29,14 @@ A classic token (starts with `ghp_`) with the `public_repo` scope also works. Ne
 
 ### 2. Add IssueWatcher to your AI app
 
+**Recommended: install once so the server starts instantly.** The commands below use `npx`, which re-checks npm every time your app starts the server. On a slow connection or on Windows that can take 15 to 30 seconds, and some apps give up waiting (Claude Code stops at 30). Installing it once makes startup take under a second:
+
+```bash
+npm install -g issuewatcher-mcp
+```
+
+Then, in any config below, use the command `issuewatcher-mcp` (with no arguments) instead of `npx -y issuewatcher-mcp`. For example, in Claude Code: `claude mcp add issuewatcher -e GITHUB_TOKEN=github_pat_xxxxxxxx -- issuewatcher-mcp`. To update later, run the same install command again. If you would rather not install it, the `npx` form below works and only the first start is slow.
+
 Pick your app:
 
 <details>
@@ -139,7 +147,7 @@ Restart your AI app, then try:
 - *"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.
+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 thirty minutes. It looks at the 20 newest issues per repository in the time window.
 
 ## What the assistant can do (the tools)
 
@@ -198,6 +206,7 @@ LLM API keys (Gemini, OpenAI, Claude, Groq, ...) are only used by the *separate*
 | 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`). |
+| "Connection timed out" (for example after 30 s) when the app starts | Almost always `npx` being slow, not the server. Run `npm install -g issuewatcher-mcp` once and use the command `issuewatcher-mcp` instead of `npx -y issuewatcher-mcp`. Startup then takes under a second. |
 | "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. |

package/build/deps/discovery.js

@@ -2,6 +2,13 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { logger } from "../logger.js";
 import { MANIFEST_FILES, parseManifest } from "./manifests.js";
+/**
+ * Maps built while some registry lookups failed (a registry outage, not "no such package"). They are
+ * usable, but must not be cached for the full day: the missing packages would stay missing.
+ */
+export const incompleteMaps = new WeakSet();
+/** How long an incomplete map is kept before discovery is tried again. */
+const INCOMPLETE_RETRY_MS = 15 * 60_000;
 const DAY_MS = 86_400_000;
 async function inPool(items, size, fn) {
     const out = new Array(items.length);
@@ -34,7 +41,7 @@ export async function discoverDependencies(source, registry, opts, now = Date.no
             .slice(0, opts.maxRepos);
     }
     const aggregated = new Map();
-    await inPool(repos, 4, async ({ owner, name }) => {
+    await inPool(repos, 6, async ({ owner, name }) => {
         for (const file of MANIFEST_FILES) {
             let text;
             try {
@@ -66,11 +73,13 @@ export async function discoverDependencies(source, registry, opts, now = Date.no
         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) => {
+    let lookupFailures = 0;
+    const resolved = await inPool(ranked, 12, async (dep) => {
         try {
             return await registry.resolve(dep.ecosystem, dep.pkg);
         }
         catch (err) {
+            lookupFailures++;
             logger.warn(`Registry lookup failed for ${dep.ecosystem}:${dep.pkg}`, err);
             return null;
         }
@@ -83,6 +92,10 @@ export async function discoverDependencies(source, registry, opts, now = Date.no
         (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`);
+    if (lookupFailures > 0) {
+        logger.warn(`${lookupFailures} registry lookup(s) failed; the list will be rebuilt in 15 minutes`);
+        incompleteMaps.add(map);
+    }
     return map;
 }
 /**
@@ -107,7 +120,9 @@ export class CachedDiscovery {
             return cached.map;
         try {
             const map = await this.run();
-            await this.write({ fetchedAt: this.now(), map });
+            // An incomplete map is stored as if it were already almost expired, so the next start retries sooner.
+            const fetchedAt = incompleteMaps.has(map) ? this.now() - this.ttlMs + Math.min(INCOMPLETE_RETRY_MS, this.ttlMs) : this.now();
+            await this.write({ fetchedAt, map });
             return map;
         }
         catch (err) {

package/build/deps/registry.js

@@ -13,11 +13,13 @@ export function githubRepoFromUrl(url) {
         s.match(/^([\w.-]+)\/([\w.-]+)$/);
     return m ? `${m[1]}/${m[2]}` : null;
 }
+const MAX_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 400;
 export class HttpRegistry {
     client;
     urls;
     constructor(client = axios.create({
-        timeout: 15_000,
+        timeout: 10_000,
         headers: { "User-Agent": "IssueWatcher" },
     }), 
     /** Overridden in tests (a local stub) and for registry mirrors. */
@@ -26,14 +28,25 @@ export class HttpRegistry {
         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;
+        for (let attempt = 0;; attempt++) {
+            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;
+                // A dropped connection or a registry hiccup is worth a second try; losing the package
+                // would silently remove its repo from the watch list.
+                const status = axios.isAxiosError(err) ? err.response?.status : undefined;
+                // A timeout is not retried: a server that did not answer in 10 s will not answer the second time
+                // either, and three tries would turn one hung registry into half a minute of waiting.
+                const timedOut = axios.isAxiosError(err) && (err.code === "ECONNABORTED" || err.code === "ETIMEDOUT");
+                const transient = axios.isAxiosError(err) && !timedOut && (status === undefined || status < 400 || status >= 500);
+                if (!transient || attempt >= MAX_ATTEMPTS - 1)
+                    throw err;
+                await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * (attempt + 1)));
+            }
         }
     }
     async npm(pkg) {

package/build/github/api.js

@@ -15,8 +15,10 @@ function nextLink(res) {
 /** Milliseconds to wait before retrying, or null if the failure is not retryable. */
 function retryDelay(err, attempt) {
     const status = err.response?.status;
-    if (!err.response)
-        return 500 * 2 ** attempt; // network error / timeout
+    // A network error, a timeout, or a connection cut while the body was still arriving (axios then
+    // reports an error that carries the 200 it had already received).
+    if (!err.response || (status !== undefined && status < 400))
+        return 500 * 2 ** attempt;
     const headers = err.response.headers;
     const retryAfter = Number(headers["retry-after"]);
     if (Number.isFinite(retryAfter) && retryAfter > 0)
@@ -56,7 +58,9 @@ export class GitHubAPI {
             }
             catch (err) {
                 const delay = axios.isAxiosError(err) ? retryDelay(err, attempt) : null;
-                if (delay === null || attempt >= MAX_RETRIES || delay > MAX_RATE_LIMIT_WAIT_MS)
+                // One retry after a timeout, not three: each try waits the full timeout.
+                const timedOut = axios.isAxiosError(err) && (err.code === "ECONNABORTED" || err.code === "ETIMEDOUT");
+                if (delay === null || attempt >= (timedOut ? 1 : MAX_RETRIES) || delay > MAX_RATE_LIMIT_WAIT_MS)
                     throw err;
                 logger.warn(`GitHub request failed (${url}), retrying in ${Math.round(delay / 1000)}s`);
                 await sleep(delay);
@@ -125,8 +129,9 @@ export class GitHubAPI {
      */
     async getIssuesSince(owner, repo, since, max) {
         const sinceMs = since.getTime();
-        const perPage = Math.max(1, Math.min(PER_PAGE, max * 2));
-        const raw = await this.paginate(`/repos/${owner}/${repo}/issues`, { state: "open", sort: "created", direction: "desc", per_page: perPage }, {
+        // Full pages: the listing mixes in pull requests, which are dropped below, so a small page
+        // on a busy repo is mostly PRs and needs several round trips to reach the window's edge.
+        const raw = await this.paginate(`/repos/${owner}/${repo}/issues`, { state: "open", sort: "created", direction: "desc", per_page: PER_PAGE }, {
             maxPages: 5,
             stopAfter: (page) => page.some((i) => Date.parse(i.created_at ?? "") < sinceMs),
         });

package/build/logger.js

@@ -12,8 +12,12 @@ function log(level, msg, meta) {
     const sink = allToStderr ? console.error : level === "info" ? console.log : console[level];
     if (meta === undefined)
         sink(line);
+    // Stack traces are for real faults. A warning is an expected failure (a dropped connection, a
+    // missing file) and a one-line message says everything a user needs.
+    else if (meta instanceof Error)
+        sink(line, level === "error" ? meta.stack ?? meta.message : meta.message);
     else
-        sink(line, meta instanceof Error ? meta.stack ?? meta.message : meta);
+        sink(line, meta);
 }
 export const logger = {
     info: (msg, meta) => log("info", msg, meta),

package/build/mcp/radar.js

@@ -5,7 +5,7 @@ import { cleanLabel, cleanText, issueUrl, safeRepoName } from "./sanitize.js";
 import { TtlCache } from "./ttl-cache.js";
 const HOUR_MS = 3_600_000;
 /** Every fetch reaches back at least this far, so a later question about a shorter window reuses it. */
-const MIN_FETCH_HOURS = 72;
+const MIN_FETCH_HOURS = 168;
 /** A failure the user can act on, with a message safe to show (no tokens, no raw API text). */
 export class RadarError extends Error {
     kind;
@@ -19,7 +19,8 @@ export class RadarError extends Error {
 export function classifyError(err) {
     if (err instanceof RadarError)
         return err;
-    if (axios.isAxiosError(err) && err.response) {
+    // A response that arrived with a success status but failed anyway was cut off mid-body: a network problem.
+    if (axios.isAxiosError(err) && err.response && err.response.status >= 400) {
         const { status, headers } = err.response;
         if (status === 401) {
             return new RadarError("GitHub rejected the token (401). Create a new token and update GITHUB_TOKEN.", "auth");
@@ -67,7 +68,7 @@ export class Radar {
         this.budgetMs = opts.budgetMs ?? 20_000;
         this.perRepoMax = opts.perRepoMax ?? 20;
         this.defaultMode = opts.defaultMode ?? "both";
-        const ttl = opts.cacheTtlMs ?? 10 * 60_000;
+        const ttl = opts.cacheTtlMs ?? 30 * 60_000;
         this.repoIssues = new TtlCache(ttl, 500, this.now);
         this.singleIssues = new TtlCache(ttl, 500, this.now);
         this.targetsCache = new TtlCache(ttl, 1, this.now);
@@ -135,7 +136,7 @@ export class Radar {
      * finds them ready instead of waiting. Never throws: if something fails, the real question will
      * hit the same problem and report it properly.
      */
-    async warmUp(sinceHours = 72) {
+    async warmUp(sinceHours = MIN_FETCH_HOURS) {
         try {
             const targets = await this.targets();
             const since = new Date(this.now() - sinceHours * HOUR_MS);

package/build/mcp/server.js

@@ -90,7 +90,7 @@ export function createIssueWatcherServer(deps) {
             "their own projects depend on. Each issue has a 0-100 score and plain-language reasons. Use mode " +
             "'contributor' for 'what could I pick up and fix?' (good first issues, unassigned, fresh, not already " +
             "claimed) and 'consumer' for 'what could break my projects?'. Returns titles, labels, scores and links, " +
-            "not issue bodies. Results are cached for about 10 minutes.",
+            "not issue bodies. Results are cached for about 30 minutes.",
         inputSchema: rankedInput,
         outputSchema: rankedOut,
         annotations: { title: "Get ranked issues", ...READ_ONLY },

package/build/mcp/settings.js

@@ -46,7 +46,7 @@ export function loadMcpSettings(env = process.env) {
         cacheDir: path.resolve(text(env, "ISSUEWATCHER_CACHE_DIR") ?? path.join(os.homedir(), ".issuewatcher")),
         concurrency: int("ISSUEWATCHER_CONCURRENCY", 8, 1, 32),
         budgetMs: int("ISSUEWATCHER_BUDGET_MS", 20_000, 1_000, 120_000),
-        cacheTtlMs: int("ISSUEWATCHER_CACHE_TTL_MS", 600_000, 0, 86_400_000),
+        cacheTtlMs: int("ISSUEWATCHER_CACHE_TTL_MS", 1_800_000, 0, 86_400_000),
         prefetch: env.ISSUEWATCHER_PREFETCH?.trim().toLowerCase() !== "false",
     };
     return { settings, problems };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issuewatcher-mcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "MCP server that ranks new GitHub issues for your AI assistant: what to pick up, and what may break your projects.",
   "mcpName": "io.github.mac146/issuewatcher",
   "license": "MIT",