@oss-scout/mcp 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Costa
+
+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/dist/index.js

@@ -11,7 +11,7 @@ async function main() {
         process.exit(1);
     }
     const scout = await createScout({ githubToken: token });
-    const server = new McpServer({ name: "@oss-scout/core", version: "0.1.0" }, { capabilities: { resources: {}, tools: {} } });
+    const server = new McpServer({ name: "oss-scout-mcp", version: "0.2.1" }, { capabilities: { resources: {}, tools: {} } });
     registerTools(server, scout);
     registerResources(server, scout);
     const transport = new StdioServerTransport();

package/dist/mcp-server.bundle.cjs

@@ -35704,7 +35704,6 @@ var IssueScopeSchema = external_exports3.enum([
 ]);
 var SearchStrategySchema = external_exports3.enum([
   "merged",
-  "orgs",
   "starred",
   "broad",
   "maintained",
@@ -35712,7 +35711,6 @@ var SearchStrategySchema = external_exports3.enum([
 ]);
 var CONCRETE_STRATEGIES = [
   "merged",
-  "orgs",
   "starred",
   "broad",
   "maintained"
@@ -35785,6 +35783,13 @@ var TrackedIssueSchema = external_exports3.object({
   vetted: external_exports3.boolean(),
   vettingResult: IssueVettingResultSchema.optional()
 });
+var SkippedIssueSchema = external_exports3.object({
+  url: external_exports3.string(),
+  repo: external_exports3.string(),
+  number: external_exports3.number(),
+  title: external_exports3.string(),
+  skippedAt: external_exports3.string()
+});
 var SavedCandidateSchema = external_exports3.object({
   issueUrl: external_exports3.string(),
   repo: external_exports3.string(),
@@ -35801,13 +35806,12 @@ var SavedCandidateSchema = external_exports3.object({
 var PersistenceModeSchema = external_exports3.enum(["local", "gist"]);
 var ScoutPreferencesSchema = external_exports3.object({
   githubUsername: external_exports3.string().default(""),
-  languages: external_exports3.array(external_exports3.string()).default(["typescript", "javascript"]),
+  languages: external_exports3.array(external_exports3.string()).default(["any"]),
   labels: external_exports3.array(external_exports3.string()).default(["good first issue", "help wanted"]),
   scope: external_exports3.array(IssueScopeSchema).optional(),
   excludeRepos: external_exports3.array(external_exports3.string()).default([]),
   excludeOrgs: external_exports3.array(external_exports3.string()).default([]),
   aiPolicyBlocklist: external_exports3.array(external_exports3.string()).default(["matplotlib/matplotlib"]),
-  preferredOrgs: external_exports3.array(external_exports3.string()).default([]),
   projectCategories: external_exports3.array(ProjectCategorySchema).default([]),
   minStars: external_exports3.number().default(50),
   maxIssueAgeDays: external_exports3.number().default(90),
@@ -35825,6 +35829,7 @@ var ScoutStateSchema = external_exports3.object({
   mergedPRs: external_exports3.array(StoredMergedPRSchema).default([]),
   closedPRs: external_exports3.array(StoredClosedPRSchema).default([]),
   savedResults: external_exports3.array(SavedCandidateSchema).default([]),
+  skippedIssues: external_exports3.array(SkippedIssueSchema).default([]),
   lastSearchAt: external_exports3.string().optional(),
   lastRunAt: external_exports3.string().default(() => (/* @__PURE__ */ new Date()).toISOString()),
   gistId: external_exports3.string().optional()
@@ -36760,12 +36765,9 @@ var IssueVetter = class {
       matchesPreferredCategory: matchesCategory
     });
     const starredRepos = this.stateReader.getStarredRepos();
-    const preferredOrgs = this.stateReader.getPreferredOrgs();
     let searchPriority = "normal";
     if (effectiveMergedCount > 0) {
       searchPriority = "merged_pr";
-    } else if (preferredOrgs.some((o) => o.toLowerCase() === orgName?.toLowerCase())) {
-      searchPriority = "preferred_org";
     } else if (starredRepos.includes(repoFullName)) {
       searchPriority = "starred";
     }
@@ -37015,6 +37017,8 @@ function buildIssueFilter(config2) {
         return false;
       if (config2.lowScoringRepos.has(repoFullName))
         return false;
+      if (config2.skippedUrls.has(item.html_url))
+        return false;
       const updatedAt = new Date(item.updated_at);
       const ageDays = daysBetween(updatedAt, config2.now);
       if (ageDays > config2.maxAgeDays)
@@ -37035,38 +37039,6 @@ async function runPhase0(octokit, vetter, repos, baseQualifiers, maxResults, fil
     rateLimitHit
   };
 }
-async function runPhase05(octokit, vetter, orgsToSearch, baseQualifiers, labels, maxResults, phase0RepoSet, filterIssues) {
-  info(MODULE9, `Phase 0.5: Searching issues in ${orgsToSearch.length} preferred org(s)...`);
-  const orgRepoFilter = orgsToSearch.map((org) => `org:${org}`).join(" OR ");
-  const orgOps = orgsToSearch.length - 1;
-  try {
-    const allItems = await searchWithChunkedLabels(octokit, labels, orgOps, (labelQ) => `${baseQualifiers} ${labelQ} (${orgRepoFilter})`.replace(/  +/g, " ").trim(), maxResults * 3);
-    if (allItems.length === 0) {
-      return { candidates: [], error: null, rateLimitHit: false };
-    }
-    const filtered = filterIssues(allItems).filter((item) => {
-      const repoFullName = extractRepoFromUrl(item.repository_url);
-      if (!repoFullName)
-        return false;
-      return !phase0RepoSet.has(repoFullName);
-    });
-    const { candidates, allFailed: allVetFailed, rateLimitHit } = await vetter.vetIssuesParallel(filtered.slice(0, maxResults * 2).map((i) => i.html_url), maxResults, "preferred_org");
-    info(MODULE9, `Found ${candidates.length} candidates from preferred orgs`);
-    return {
-      candidates,
-      error: allVetFailed ? "All preferred org issue vetting failed" : null,
-      rateLimitHit
-    };
-  } catch (error48) {
-    const errMsg = errorMessage(error48);
-    warn(MODULE9, `Error searching preferred orgs: ${errMsg}`);
-    return {
-      candidates: [],
-      error: errMsg,
-      rateLimitHit: isRateLimitError(error48)
-    };
-  }
-}
 async function runPhase1(octokit, vetter, repos, baseQualifiers, labels, maxResults, filterIssues) {
   info(MODULE9, `Phase 1: Searching issues in ${repos.length} starred repos...`);
   const phase1Labels = labels.slice(0, 3);
@@ -37203,8 +37175,8 @@ var IssueDiscovery = class {
   }
   /**
    * Search for issues matching our criteria.
-   * Searches in priority order: merged-PR repos first (no label filter), then preferred
-   * organizations, then starred repos, then general search, then actively maintained repos.
+   * Searches in priority order: merged-PR repos first (no label filter), then starred
+   * repos, then general search, then actively maintained repos.
    * Filters out issues from low-scoring and excluded repos.
    *
    * @param options - Search configuration
@@ -37262,6 +37234,10 @@ var IssueDiscovery = class {
       tracker.init(CRITICAL_BUDGET_THRESHOLD, new Date(Date.now() + 6e4).toISOString());
       warn(MODULE9, "Could not check rate limit \u2014 using conservative budget, skipping heavy phases:", errorMessage(error48));
     }
+    if (searchBudget <= 0) {
+      this.rateLimitWarning = "GitHub search API quota exhausted. Try again after the rate limit resets.";
+      return { candidates: [], strategiesUsed: [] };
+    }
     const mergedPRRepos = this.stateReader.getReposWithMergedPRs();
     const starredRepos = this.getStarredRepos();
     const starredRepoSet = new Set(starredRepos);
@@ -37278,6 +37254,7 @@ var IssueDiscovery = class {
       excludeOrgs: new Set((config2.excludeOrgs ?? []).map((o) => o.toLowerCase())),
       aiBlocklisted,
       lowScoringRepos,
+      skippedUrls: options.skippedUrls ?? /* @__PURE__ */ new Set(),
       maxAgeDays: config2.maxIssueAgeDays || 90,
       now: /* @__PURE__ */ new Date(),
       includeDocIssues: config2.includeDocIssues ?? true
@@ -37295,22 +37272,6 @@ var IssueDiscovery = class {
       }
       strategiesUsed.push("merged");
     }
-    const preferredOrgs = config2.preferredOrgs ?? [];
-    if (allCandidates.length < maxResults && preferredOrgs.length > 0 && searchBudget >= CRITICAL_BUDGET_THRESHOLD && enabledStrategies.has("orgs")) {
-      if (phase0Repos.length > 0)
-        await sleep(INTER_PHASE_DELAY_MS);
-      const phase0Orgs = new Set(phase0Repos.map((r) => r.split("/")[0]?.toLowerCase()));
-      const orgsToSearch = preferredOrgs.filter((org) => !phase0Orgs.has(org.toLowerCase())).slice(0, 5);
-      if (orgsToSearch.length > 0) {
-        const remaining = maxResults - allCandidates.length;
-        const result = await runPhase05(this.octokit, this.vetter, orgsToSearch, baseQualifiers, labels, remaining, phase0RepoSet, filterIssues);
-        allCandidates.push(...result.candidates);
-        phaseErrors["0.5"] = result.error;
-        if (result.rateLimitHit)
-          rateLimitHitDuringSearch = true;
-      }
-      strategiesUsed.push("orgs");
-    }
     if (allCandidates.length < maxResults && starredRepos.length > 0 && searchBudget >= CRITICAL_BUDGET_THRESHOLD && enabledStrategies.has("starred")) {
       await sleep(INTER_PHASE_DELAY_MS);
       const reposToSearch = starredRepos.filter((r) => !phase0RepoSet.has(r));
@@ -37356,7 +37317,6 @@ var IssueDiscovery = class {
     if (allCandidates.length === 0) {
       const errorDetails = [
         phaseErrors["0"] ? `Phase 0 (merged-PR repos): ${phaseErrors["0"]}` : null,
-        phaseErrors["0.5"] ? `Phase 0.5 (preferred orgs): ${phaseErrors["0.5"]}` : null,
         phaseErrors["1"] ? `Phase 1 (starred repos): ${phaseErrors["1"]}` : null,
         phaseErrors["2"] ? `Phase 2 (general): ${phaseErrors["2"]}` : null,
         phaseErrors["3"] ? `Phase 3 (maintained repos): ${phaseErrors["3"]}` : null
@@ -37374,9 +37334,8 @@ var IssueDiscovery = class {
     allCandidates.sort((a, b) => {
       const priorityOrder = {
         merged_pr: 0,
-        preferred_org: 1,
-        starred: 2,
-        normal: 3
+        starred: 1,
+        normal: 2
       };
       const priorityDiff = priorityOrder[a.searchPriority] - priorityOrder[b.searchPriority];
       if (priorityDiff !== 0)
@@ -37462,11 +37421,16 @@ var GistStateStore = class {
       warn(MODULE10, "No gist ID \u2014 cannot push");
       return false;
     }
+    const json2 = JSON.stringify(state, null, 2);
+    if (json2.length > 9e5) {
+      warn(MODULE10, `State too large for gist (${Math.round(json2.length / 1024)}KB). Consider clearing old results with 'oss-scout results clear'.`);
+      return false;
+    }
     try {
       await this.octokit.gists.update({
         gist_id: this.gistId,
         files: {
-          [GIST_FILENAME]: { content: JSON.stringify(state, null, 2) }
+          [GIST_FILENAME]: { content: json2 }
         }
       });
       debug(MODULE10, "State pushed to gist");
@@ -37639,6 +37603,7 @@ function mergeStates(local, remote) {
     mergedPRs: unionByUrl(local.mergedPRs, remote.mergedPRs),
     closedPRs: unionByUrl(local.closedPRs, remote.closedPRs),
     savedResults: mergeSavedResults(local.savedResults ?? [], remote.savedResults ?? []),
+    skippedIssues: mergeSkippedIssues(local.skippedIssues ?? [], remote.skippedIssues ?? []),
     lastSearchAt: pickFresherTimestamp(local.lastSearchAt, remote.lastSearchAt),
     lastRunAt: pickFresherTimestamp(local.lastRunAt, remote.lastRunAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
     gistId: remote.gistId ?? local.gistId
@@ -37689,6 +37654,18 @@ function mergeSavedResults(local, remote) {
   }
   return [...merged.values()];
 }
+function mergeSkippedIssues(local, remote) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const item of local)
+    merged.set(item.url, item);
+  for (const item of remote) {
+    const existing = merged.get(item.url);
+    if (!existing || item.skippedAt > existing.skippedAt) {
+      merged.set(item.url, item);
+    }
+  }
+  return [...merged.values()];
+}
 function pickFresherTimestamp(a, b) {
   if (!a)
     return b;
@@ -37719,7 +37696,8 @@ function loadLocalState() {
       const backupPath = `${statePath}.corrupt.${Date.now()}`;
       fs4.copyFileSync(statePath, backupPath);
       warn(MODULE11, `Corrupt state backed up to ${backupPath}`);
-    } catch {
+    } catch (backupErr) {
+      warn(MODULE11, `Failed to back up corrupt state: ${errorMessage(backupErr)}`);
     }
     return ScoutStateSchema.parse({ version: 1 });
   }
@@ -37799,12 +37777,16 @@ var OssScout = class {
   // ── Search ──────────────────────────────────────────────────────────
   /**
    * Multi-strategy issue search. Returns scored, sorted candidates.
+   * Automatically culls expired skip entries and filters skipped issues.
    */
   async search(options) {
+    this.cullExpiredSkips();
+    const skippedUrls = new Set((this.state.skippedIssues ?? []).map((s) => s.url));
     const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
     const { candidates, strategiesUsed } = await discovery.searchIssues({
       maxResults: options?.maxResults,
-      strategies: options?.strategies
+      strategies: options?.strategies,
+      skippedUrls
     });
     this.state.lastSearchAt = (/* @__PURE__ */ new Date()).toISOString();
     this.dirty = true;
@@ -37905,9 +37887,6 @@ var OssScout = class {
   getStarredRepos() {
     return this.state.starredRepos;
   }
-  getPreferredOrgs() {
-    return this.state.preferences.preferredOrgs;
-  }
   getProjectCategories() {
     return this.state.preferences.projectCategories;
   }
@@ -38038,6 +38017,69 @@ var OssScout = class {
     this.state.savedResults = [];
     this.dirty = true;
   }
+  // ── Skip List ───────────────────────────────────────────────────────
+  /**
+   * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
+   */
+  skipIssue(url2, metadata) {
+    const existing = this.state.skippedIssues ?? [];
+    if (existing.some((s) => s.url === url2))
+      return;
+    this.state.skippedIssues = [
+      ...existing,
+      {
+        url: url2,
+        repo: metadata?.repo ?? "",
+        number: metadata?.number ?? 0,
+        title: metadata?.title ?? "",
+        skippedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    ];
+    if (this.state.savedResults) {
+      this.state.savedResults = this.state.savedResults.filter((r) => r.issueUrl !== url2);
+    }
+    this.dirty = true;
+  }
+  /**
+   * Get all skipped issues.
+   */
+  getSkippedIssues() {
+    return this.state.skippedIssues ?? [];
+  }
+  /**
+   * Remove a specific issue from the skip list.
+   */
+  unskipIssue(url2) {
+    this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => s.url !== url2);
+    this.dirty = true;
+  }
+  /**
+   * Clear all skipped issues.
+   */
+  clearSkippedIssues() {
+    this.state.skippedIssues = [];
+    this.dirty = true;
+  }
+  /**
+   * Remove skipped issues older than maxDays (default 90). Called automatically during search.
+   * @returns The number of expired entries that were removed.
+   */
+  cullExpiredSkips(maxDays = 90) {
+    const cutoff = /* @__PURE__ */ new Date();
+    cutoff.setDate(cutoff.getDate() - maxDays);
+    const before = (this.state.skippedIssues ?? []).length;
+    this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => {
+      const d = new Date(s.skippedAt);
+      if (isNaN(d.getTime())) {
+        return true;
+      }
+      return d >= cutoff;
+    });
+    const culled = before - this.state.skippedIssues.length;
+    if (culled > 0)
+      this.dirty = true;
+    return culled;
+  }
   // ── Persistence ─────────────────────────────────────────────────────
   /**
    * Check if state has uncommitted changes.
@@ -38097,6 +38139,17 @@ var OssScout = class {
 };
 
 // src/tools.ts
+var TOOL_TIMEOUT_MS = 6e4;
+function withTimeout(promise2, ms = TOOL_TIMEOUT_MS) {
+  let timeoutId;
+  const timer = new Promise((_, reject) => {
+    timeoutId = setTimeout(
+      () => reject(new Error(`Request timed out after ${ms / 1e3}s`)),
+      ms
+    );
+  });
+  return Promise.race([promise2, timer]).finally(() => clearTimeout(timeoutId));
+}
 function registerTools(server, scout) {
   server.tool(
     "search",
@@ -38104,16 +38157,18 @@ function registerTools(server, scout) {
     {
       maxResults: external_exports3.number().optional().describe("Maximum number of results to return (default 10)"),
       strategies: external_exports3.string().optional().describe(
-        "Comma-separated search strategies: merged, orgs, starred, broad, maintained, all"
+        "Comma-separated search strategies: merged, starred, broad, maintained, all"
       )
     },
     async ({ maxResults, strategies }) => {
       try {
         const parsedStrategies = strategies ? strategies.split(",").map((s) => SearchStrategySchema.parse(s.trim())) : void 0;
-        const result = await scout.search({
-          maxResults: maxResults ?? 10,
-          strategies: parsedStrategies
-        });
+        const result = await withTimeout(
+          scout.search({
+            maxResults: maxResults ?? 10,
+            strategies: parsedStrategies
+          })
+        );
         scout.saveResults(result.candidates);
         await scout.checkpoint();
         return {
@@ -38138,7 +38193,7 @@ function registerTools(server, scout) {
     },
     async ({ issueUrl }) => {
       try {
-        const candidate = await scout.vetIssue(issueUrl);
+        const candidate = await withTimeout(scout.vetIssue(issueUrl));
         return {
           content: [{ type: "text", text: JSON.stringify(candidate, null, 2) }]
         };
@@ -38161,11 +38216,93 @@ function registerTools(server, scout) {
       };
     }
   );
+  server.tool(
+    "skip",
+    "Skip, unskip, list, or clear skipped issues. Skipped issues are excluded from future searches and auto-expire after 90 days.",
+    {
+      action: external_exports3.enum(["add", "remove", "list", "clear"]).default("add").describe("Action to perform (default: add)"),
+      issueUrl: external_exports3.string().optional().describe("GitHub issue URL (required for add/remove actions)")
+    },
+    async ({ action, issueUrl }) => {
+      try {
+        if ((action === "add" || action === "remove") && !issueUrl) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: issueUrl is required for the "${action}" action.`
+              }
+            ],
+            isError: true
+          };
+        }
+        if (action === "list") {
+          const skipped = scout.getSkippedIssues();
+          return {
+            content: [{ type: "text", text: JSON.stringify(skipped, null, 2) }]
+          };
+        }
+        if (action === "clear") {
+          const count = scout.getSkippedIssues().length;
+          scout.clearSkippedIssues();
+          const synced2 = await scout.checkpoint();
+          const syncNote2 = synced2 ? "" : " (saved locally, gist sync failed)";
+          return {
+            content: [
+              {
+                type: "text",
+                text: count > 0 ? `Skip list cleared (${count} entries removed)${syncNote2}` : `Skip list already empty${syncNote2}`
+              }
+            ]
+          };
+        }
+        if (action === "remove") {
+          const wasPresent = scout.getSkippedIssues().some((s) => s.url === issueUrl);
+          scout.unskipIssue(issueUrl);
+          const synced2 = await scout.checkpoint();
+          const syncNote2 = synced2 ? "" : " (saved locally, gist sync failed)";
+          return {
+            content: [
+              {
+                type: "text",
+                text: wasPresent ? `Removed from skip list: ${issueUrl}${syncNote2}` : `Not in skip list: ${issueUrl}`
+              }
+            ]
+          };
+        }
+        const alreadySkipped = scout.getSkippedIssues().some((s) => s.url === issueUrl);
+        if (alreadySkipped) {
+          return {
+            content: [
+              { type: "text", text: `Already in skip list: ${issueUrl}` }
+            ]
+          };
+        }
+        const saved = scout.getSavedResults().find((r) => r.issueUrl === issueUrl);
+        const metadata = saved ? {
+          repo: saved.repo,
+          number: saved.number,
+          title: saved.title
+        } : void 0;
+        scout.skipIssue(issueUrl, metadata);
+        const synced = await scout.checkpoint();
+        const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+        return {
+          content: [{ type: "text", text: `Skipped: ${issueUrl}${syncNote}` }]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${msg}` }],
+          isError: true
+        };
+      }
+    }
+  );
   const VALID_KEYS = Object.keys(ScoutPreferencesSchema.shape);
   const ARRAY_KEYS = /* @__PURE__ */ new Set([
     "languages",
     "labels",
-    "preferredOrgs",
     "projectCategories",
     "excludeRepos",
     "excludeOrgs",
@@ -38321,7 +38458,7 @@ async function main() {
   }
   const scout = await createScout({ githubToken: token });
   const server = new McpServer(
-    { name: "@oss-scout/core", version: "0.1.0" },
+    { name: "oss-scout-mcp", version: "0.2.1" },
     { capabilities: { resources: {}, tools: {} } }
   );
   registerTools(server, scout);

package/dist/tools.js

@@ -1,5 +1,13 @@
 import { z } from "zod";
 import { SearchStrategySchema, ScoutPreferencesSchema } from "@oss-scout/core";
+const TOOL_TIMEOUT_MS = 60000;
+function withTimeout(promise, ms = TOOL_TIMEOUT_MS) {
+    let timeoutId;
+    const timer = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(`Request timed out after ${ms / 1000}s`)), ms);
+    });
+    return Promise.race([promise, timer]).finally(() => clearTimeout(timeoutId));
+}
 export function registerTools(server, scout) {
     server.tool("search", "Search for open source issues matching your preferences", {
         maxResults: z
@@ -9,7 +17,7 @@ export function registerTools(server, scout) {
         strategies: z
             .string()
             .optional()
-            .describe("Comma-separated search strategies: merged, orgs, starred, broad, maintained, all"),
+            .describe("Comma-separated search strategies: merged, starred, broad, maintained, all"),
     }, async ({ maxResults, strategies }) => {
         try {
             const parsedStrategies = strategies
@@ -17,10 +25,10 @@ export function registerTools(server, scout) {
                     .split(",")
                     .map((s) => SearchStrategySchema.parse(s.trim()))
                 : undefined;
-            const result = await scout.search({
+            const result = await withTimeout(scout.search({
                 maxResults: maxResults ?? 10,
                 strategies: parsedStrategies,
-            });
+            }));
             scout.saveResults(result.candidates);
             await scout.checkpoint();
             return {
@@ -41,7 +49,7 @@ export function registerTools(server, scout) {
             .describe("Full GitHub issue URL (e.g. https://github.com/owner/repo/issues/123)"),
     }, async ({ issueUrl }) => {
         try {
-            const candidate = await scout.vetIssue(issueUrl);
+            const candidate = await withTimeout(scout.vetIssue(issueUrl));
             return {
                 content: [{ type: "text", text: JSON.stringify(candidate, null, 2) }],
             };
@@ -60,11 +68,108 @@ export function registerTools(server, scout) {
             content: [{ type: "text", text: JSON.stringify(preferences, null, 2) }],
         };
     });
+    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"])
+            .default("add")
+            .describe("Action to perform (default: add)"),
+        issueUrl: z
+            .string()
+            .optional()
+            .describe("GitHub issue URL (required for add/remove actions)"),
+    }, async ({ action, issueUrl }) => {
+        try {
+            if ((action === "add" || action === "remove") && !issueUrl) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: issueUrl is required for the "${action}" action.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (action === "list") {
+                const skipped = scout.getSkippedIssues();
+                return {
+                    content: [{ type: "text", text: JSON.stringify(skipped, null, 2) }],
+                };
+            }
+            if (action === "clear") {
+                const count = scout.getSkippedIssues().length;
+                scout.clearSkippedIssues();
+                const synced = await scout.checkpoint();
+                const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: count > 0
+                                ? `Skip list cleared (${count} entries removed)${syncNote}`
+                                : `Skip list already empty${syncNote}`,
+                        },
+                    ],
+                };
+            }
+            if (action === "remove") {
+                const wasPresent = scout
+                    .getSkippedIssues()
+                    .some((s) => s.url === issueUrl);
+                scout.unskipIssue(issueUrl);
+                const synced = await scout.checkpoint();
+                const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: wasPresent
+                                ? `Removed from skip list: ${issueUrl}${syncNote}`
+                                : `Not in skip list: ${issueUrl}`,
+                        },
+                    ],
+                };
+            }
+            // action === "add"
+            const alreadySkipped = scout
+                .getSkippedIssues()
+                .some((s) => s.url === issueUrl);
+            if (alreadySkipped) {
+                return {
+                    content: [
+                        { type: "text", text: `Already in skip list: ${issueUrl}` },
+                    ],
+                };
+            }
+            const saved = scout
+                .getSavedResults()
+                .find((r) => r.issueUrl === issueUrl);
+            const metadata = saved
+                ? {
+                    repo: saved.repo,
+                    number: saved.number,
+                    title: saved.title,
+                }
+                : undefined;
+            scout.skipIssue(issueUrl, metadata);
+            const synced = await scout.checkpoint();
+            const syncNote = synced ? "" : " (saved locally, gist sync failed)";
+            return {
+                content: [{ type: "text", text: `Skipped: ${issueUrl}${syncNote}` }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
     const VALID_KEYS = Object.keys(ScoutPreferencesSchema.shape);
     const ARRAY_KEYS = new Set([
         "languages",
         "labels",
-        "preferredOrgs",
         "projectCategories",
         "excludeRepos",
         "excludeOrgs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP server for oss-scout — exposes issue discovery and vetting as MCP tools",
   "type": "module",
   "bin": {
@@ -15,19 +15,10 @@
   "files": [
     "dist/"
   ],
-  "scripts": {
-    "build": "tsc",
-    "bundle": "esbuild src/index.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",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm run build && pnpm run bundle"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@oss-scout/core": "workspace:^",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@oss-scout/core": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
@@ -37,6 +28,12 @@
     "@vitest/coverage-v8": "^4.1.0",
     "vitest": "^4.1.0"
   },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude",
+    "issue-discovery"
+  ],
   "engines": {
     "node": ">=20"
   },
@@ -45,5 +42,13 @@
     "type": "git",
     "url": "git+https://github.com/costajohnt/oss-scout.git",
     "directory": "packages/mcp-server"
+  },
+  "scripts": {
+    "build": "tsc",
+    "bundle": "esbuild src/index.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",
+    "typecheck": "tsc --noEmit"
   }
-}
+}