@oss-scout/mcp 0.8.0 → 0.10.0

package/dist/tools.js

@@ -1,6 +1,21 @@
 import { z } from "zod";
-import { SearchStrategySchema, ScoutPreferencesSchema } from "@oss-scout/core";
-const TOOL_TIMEOUT_MS = 60000;
+import { SearchStrategySchema, ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl, applyPreferenceField, SORTED_PREFERENCE_KEYS, } from "@oss-scout/core";
+// Generous ceiling: even with inter-phase delays zeroed, vetting many issues
+// under the budget tracker's sliding-window pacing can take minutes (#143).
+const TOOL_TIMEOUT_MS = 300000;
+// Surfaced on the JSON envelope when scout.checkpoint() returns false (#212).
+// The skip tool reports this inline because it returns a short status line;
+// the JSON tools (search, scout-features, config-set) carry it as a top-level
+// field so a persist failure isn't silently swallowed.
+const PERSIST_WARNING = "Checkpoint failed: changes were applied in memory but could not be persisted. They may be lost when the server restarts.";
+/**
+ * Serialize a tool result, attaching a top-level `persistWarning` field when
+ * the preceding checkpoint failed (#212). Spreads onto the existing object so
+ * the happy-path payload is byte-for-byte unchanged.
+ */
+function withPersistWarning(payload, persisted) {
+    return persisted ? payload : { ...payload, persistWarning: PERSIST_WARNING };
+}
 function withTimeout(promise, ms = TOOL_TIMEOUT_MS) {
     let timeoutId;
     const timer = new Promise((_, reject) => {
@@ -26,13 +41,21 @@ export function registerTools(server, scout) {
             .array(z.string())
             .optional()
             .describe("Soft-boost ranking for candidates in one of these `owner/repo` slugs. Stronger weight than language match (#1244). Not a filter; only reorders."),
+        avoidRepos: z
+            .array(z.string())
+            .optional()
+            .describe("Soft PENALTY (milder than excludeRepos) for candidates in one of these `owner/repo` slugs (#168). Pushes them down the ranking but does not remove them; a strong boost can still outweigh it."),
+        boostIssueTypes: z
+            .array(z.string())
+            .optional()
+            .describe('Soft-boost ranking for candidates whose issue labels match one of these types, case-insensitive (e.g. "bug", "good first issue") (#168). Not a filter; only reorders.'),
         diversityRatio: z
             .number()
             .min(0)
             .max(1)
             .optional()
             .describe("Diversity counterweight (#1244): fraction of result slots reserved for candidates that matched NEITHER preference list. Counters echo-chamber bias when boosts accumulate over time. 0 disables, 1 reserves every slot for diversity. Default 0."),
-    }, async ({ maxResults, strategies, preferLanguages, preferRepos, diversityRatio, }) => {
+    }, async ({ maxResults, strategies, preferLanguages, preferRepos, avoidRepos, boostIssueTypes, diversityRatio, }) => {
         try {
             const parsedStrategies = strategies
                 ? strategies
@@ -44,12 +67,23 @@ export function registerTools(server, scout) {
                 strategies: parsedStrategies,
                 preferLanguages,
                 preferRepos,
+                avoidRepos,
+                boostIssueTypes,
                 diversityRatio,
+                // No fixed inter-phase sleeps in the request/response MCP context;
+                // the budget tracker still paces the GitHub calls (#143)
+                interPhaseDelayMs: 0,
+                broadPhaseDelayMs: 0,
             }));
             scout.saveResults(result.candidates);
-            await scout.checkpoint();
+            const persisted = await scout.checkpoint();
             return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(withPersistWarning(result, persisted), null, 2),
+                    },
+                ],
             };
         }
         catch (err) {
@@ -86,9 +120,14 @@ export function registerTools(server, scout) {
                 splitRatio,
             }));
             scout.saveResults([...result.quickWins, ...result.biggerBets]);
-            await scout.checkpoint();
+            const persisted = await scout.checkpoint();
             return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(withPersistWarning(result, persisted), null, 2),
+                    },
+                ],
             };
         }
         catch (err) {
@@ -124,6 +163,21 @@ export function registerTools(server, scout) {
             content: [{ type: "text", text: JSON.stringify(preferences, null, 2) }],
         };
     });
+    server.tool("sync", "Reconcile tracked open PRs against GitHub — mark merged/closed and recompute repo scores. Cheap; good for a daily startup call.", async () => {
+        try {
+            const result = await withTimeout(scout.syncOpenPRs());
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
     server.tool("skip", "Skip, unskip, list, or clear skipped issues. Skipped issues are excluded from future searches and auto-expire after 90 days.", {
         action: z
             .enum(["add", "remove", "list", "clear"])
@@ -156,7 +210,9 @@ export function registerTools(server, scout) {
                 const count = scout.getSkippedIssues().length;
                 scout.clearSkippedIssues();
                 const synced = await scout.checkpoint();
-                const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+                const syncNote = synced
+                    ? ""
+                    : " (warning: failed to persist to disk)";
                 return {
                     content: [
                         {
@@ -174,7 +230,9 @@ export function registerTools(server, scout) {
                     .some((s) => s.url === issueUrl);
                 scout.unskipIssue(issueUrl);
                 const synced = await scout.checkpoint();
-                const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+                const syncNote = synced
+                    ? ""
+                    : " (warning: failed to persist to disk)";
                 return {
                     content: [
                         {
@@ -187,6 +245,11 @@ export function registerTools(server, scout) {
                 };
             }
             // action === "add"
+            // Same validation as the CLI's runSkip: skip matching is exact-URL,
+            // so junk or near-miss URLs would be stored but never match anything.
+            // The throw is caught below and surfaced as isError.
+            validateUrl(issueUrl);
+            validateGitHubUrl(issueUrl, ISSUE_URL_PATTERN, "issue");
             const alreadySkipped = scout
                 .getSkippedIssues()
                 .some((s) => s.url === issueUrl);
@@ -209,7 +272,7 @@ export function registerTools(server, scout) {
                 : undefined;
             scout.skipIssue(issueUrl, metadata);
             const synced = await scout.checkpoint();
-            const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+            const syncNote = synced ? "" : " (warning: failed to persist to disk)";
             return {
                 content: [{ type: "text", text: `Skipped: ${issueUrl}${syncNote}` }],
             };
@@ -222,118 +285,42 @@ export function registerTools(server, scout) {
             };
         }
     });
-    const VALID_KEYS = Object.keys(ScoutPreferencesSchema.shape);
-    const ARRAY_KEYS = new Set([
-        "languages",
-        "labels",
-        "projectCategories",
-        "excludeRepos",
-        "excludeOrgs",
-        "aiPolicyBlocklist",
-        "scope",
-        "defaultStrategy",
-    ]);
-    const NUMBER_KEYS = new Set([
-        "minStars",
-        "maxIssueAgeDays",
-        "minRepoScoreThreshold",
-        "interPhaseDelayMs",
-        "broadPhaseDelayMs",
-        "skipBroadWhenSufficientResults",
-        "featuresAnchorThreshold",
-        "featuresSplitRatio",
-    ]);
-    const BOOLEAN_KEYS = new Set(["includeDocIssues"]);
     server.tool("config-set", "Update an oss-scout configuration preference", {
         key: z
             .string()
-            .describe("Preference key to update (e.g. languages, minStars, excludeRepos)"),
+            .describe(`Preference key to update. One of: ${SORTED_PREFERENCE_KEYS.join(", ")}`),
         value: z
             .string()
-            .describe("New value — comma-separated for arrays, plain string for scalars"),
+            .describe('New value. Comma-separated for arrays; prefix with + to append or - to remove items (e.g. "+spam/repo"). Plain string/number/boolean for scalars.'),
     }, async ({ key, value }) => {
-        if (!VALID_KEYS.includes(key)) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Unknown config key: "${key}". Valid keys: ${VALID_KEYS.join(", ")}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-        let parsed;
-        if (ARRAY_KEYS.has(key)) {
-            // Accept comma-separated strings → arrays
-            try {
-                parsed = JSON.parse(value);
-                if (!Array.isArray(parsed)) {
-                    parsed = value
-                        .split(",")
-                        .map((s) => s.trim())
-                        .filter(Boolean);
-                }
-            }
-            catch {
-                parsed = value
-                    .split(",")
-                    .map((s) => s.trim())
-                    .filter(Boolean);
-            }
-        }
-        else if (NUMBER_KEYS.has(key)) {
-            const num = Number(value);
-            if (isNaN(num)) {
-                return {
-                    content: [
-                        { type: "text", text: `Invalid number for "${key}": "${value}"` },
-                    ],
-                    isError: true,
-                };
-            }
-            parsed = num;
-        }
-        else if (BOOLEAN_KEYS.has(key)) {
-            const lower = value.toLowerCase();
-            if (lower === "true" || lower === "yes")
-                parsed = true;
-            else if (lower === "false" || lower === "no")
-                parsed = false;
-            else {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Invalid boolean for "${key}": "${value}". Use true/false or yes/no.`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-        }
-        else {
-            // String or enum fields — pass through as-is
-            parsed = value;
+        // Parse + validate via the shared field map so the CLI and MCP stay in
+        // lockstep, including the +/- array syntax and the scope special case
+        // (#153). applyPreferenceField throws ValidationError on a bad key/value.
+        let validated;
+        try {
+            validated = applyPreferenceField(scout.getPreferences(), key, value);
         }
-        const currentPrefs = scout.getPreferences();
-        const candidate = { ...currentPrefs, [key]: parsed };
-        // Validate the full preferences object with Zod
-        const result = ScoutPreferencesSchema.safeParse(candidate);
-        if (!result.success) {
-            const issues = result.error.issues
-                .map((i) => `${i.path.join(".")}: ${i.message}`)
-                .join("; ");
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
             return {
-                content: [{ type: "text", text: `Validation error: ${issues}` }],
+                content: [{ type: "text", text: msg }],
                 isError: true,
             };
         }
-        scout.updatePreferences({ [key]: parsed });
-        await scout.checkpoint();
+        // Apply only the changed key; validation above ran against the full
+        // merged object so cross-field rules still hold.
+        scout.updatePreferences({
+            [key]: validated[key],
+        });
+        const persisted = await scout.checkpoint();
         const updated = scout.getPreferences();
         return {
-            content: [{ type: "text", text: JSON.stringify(updated, null, 2) }],
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(withPersistWarning(updated, persisted), null, 2),
+                },
+            ],
         };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/mcp",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "MCP server for oss-scout — exposes issue discovery and vetting as MCP tools",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^4.3.6",
-    "@oss-scout/core": "^0.11.0"
+    "@oss-scout/core": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
@@ -46,7 +46,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "bundle": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/mcp-server.bundle.cjs",
+    "bundle": "esbuild src/bin.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/mcp-server.bundle.cjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",