@oss-scout/mcp 0.2.0 → 0.3.0

package/dist/resources.d.ts

@@ -1,3 +1,3 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { OssScout } from '@oss-scout/core';
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OssScout } from "@oss-scout/core";
 export declare function registerResources(server: McpServer, scout: OssScout): void;

package/dist/resources.js

@@ -1,26 +1,32 @@
 export function registerResources(server, scout) {
-    server.resource('config', 'scout://config', { description: 'Current oss-scout preferences' }, async () => ({
-        contents: [{
-                uri: 'scout://config',
-                mimeType: 'application/json',
+    server.resource("config", "scout://config", { description: "Current oss-scout preferences" }, async () => ({
+        contents: [
+            {
+                uri: "scout://config",
+                mimeType: "application/json",
                 text: JSON.stringify(scout.getPreferences(), null, 2),
-            }],
+            },
+        ],
     }));
-    server.resource('results', 'scout://results', { description: 'Saved search results from previous runs' }, async () => ({
-        contents: [{
-                uri: 'scout://results',
-                mimeType: 'application/json',
+    server.resource("results", "scout://results", { description: "Saved search results from previous runs" }, async () => ({
+        contents: [
+            {
+                uri: "scout://results",
+                mimeType: "application/json",
                 text: JSON.stringify(scout.getSavedResults(), null, 2),
-            }],
+            },
+        ],
     }));
-    server.resource('scores', 'scout://scores', { description: 'Repository score data based on contribution history' }, async () => {
+    server.resource("scores", "scout://scores", { description: "Repository score data based on contribution history" }, async () => {
         const state = scout.getState();
         return {
-            contents: [{
-                    uri: 'scout://scores',
-                    mimeType: 'application/json',
+            contents: [
+                {
+                    uri: "scout://scores",
+                    mimeType: "application/json",
                     text: JSON.stringify(state.repoScores, null, 2),
-                }],
+                },
+            ],
         };
     });
 }

package/dist/tools.d.ts

@@ -1,3 +1,3 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { OssScout } from '@oss-scout/core';
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OssScout } from "@oss-scout/core";
 export declare function registerTools(server: McpServer, scout: OssScout): void;

package/dist/tools.js

@@ -1,43 +1,204 @@
-import { z } from 'zod';
-import { SearchStrategySchema, ScoutPreferencesSchema } from '@oss-scout/core';
+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.number().optional().describe('Maximum number of results to return (default 10)'),
-        strategies: z.string().optional().describe('Comma-separated search strategies: merged, orgs, starred, broad, maintained, all'),
+    server.tool("search", "Search for open source issues matching your preferences", {
+        maxResults: z
+            .number()
+            .optional()
+            .describe("Maximum number of results to return (default 10)"),
+        strategies: z
+            .string()
+            .optional()
+            .describe("Comma-separated search strategies: merged, starred, broad, maintained, all"),
     }, async ({ maxResults, strategies }) => {
-        const parsedStrategies = strategies
-            ? strategies.split(',').map((s) => SearchStrategySchema.parse(s.trim()))
-            : undefined;
-        const result = await scout.search({
-            maxResults: maxResults ?? 10,
-            strategies: parsedStrategies,
-        });
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        try {
+            const parsedStrategies = strategies
+                ? strategies
+                    .split(",")
+                    .map((s) => SearchStrategySchema.parse(s.trim()))
+                : undefined;
+            const result = await withTimeout(scout.search({
+                maxResults: maxResults ?? 10,
+                strategies: parsedStrategies,
+            }));
+            scout.saveResults(result.candidates);
+            await scout.checkpoint();
+            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('vet', 'Vet a specific GitHub issue for contribution viability', {
-        issueUrl: z.string().describe('Full GitHub issue URL (e.g. https://github.com/owner/repo/issues/123)'),
+    server.tool("vet", "Vet a specific GitHub issue for contribution viability", {
+        issueUrl: z
+            .string()
+            .describe("Full GitHub issue URL (e.g. https://github.com/owner/repo/issues/123)"),
     }, async ({ issueUrl }) => {
-        const candidate = await scout.vetIssue(issueUrl);
-        return { content: [{ type: 'text', text: JSON.stringify(candidate, null, 2) }] };
+        try {
+            const candidate = await withTimeout(scout.vetIssue(issueUrl));
+            return {
+                content: [{ type: "text", text: JSON.stringify(candidate, null, 2) }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${msg}` }],
+                isError: true,
+            };
+        }
     });
-    server.tool('config', 'Show current oss-scout configuration preferences', async () => {
+    server.tool("config", "Show current oss-scout configuration preferences", async () => {
         const preferences = scout.getPreferences();
-        return { content: [{ type: 'text', text: JSON.stringify(preferences, null, 2) }] };
+        return {
+            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', 'aiPolicyBlocklist', 'scope', 'defaultStrategy',
+        "languages",
+        "labels",
+        "projectCategories",
+        "excludeRepos",
+        "excludeOrgs",
+        "aiPolicyBlocklist",
+        "scope",
+        "defaultStrategy",
+    ]);
+    const NUMBER_KEYS = new Set([
+        "minStars",
+        "maxIssueAgeDays",
+        "minRepoScoreThreshold",
     ]);
-    const NUMBER_KEYS = new Set(['minStars', 'maxIssueAgeDays', 'minRepoScoreThreshold']);
-    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)'),
-        value: z.string().describe('New value — comma-separated for arrays, plain string for scalars'),
+    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)"),
+        value: z
+            .string()
+            .describe("New value — comma-separated for arrays, plain string for scalars"),
     }, async ({ key, value }) => {
         if (!VALID_KEYS.includes(key)) {
             return {
-                content: [{ type: 'text', text: `Unknown config key: "${key}". Valid keys: ${VALID_KEYS.join(', ')}` }],
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown config key: "${key}". Valid keys: ${VALID_KEYS.join(", ")}`,
+                    },
+                ],
                 isError: true,
             };
         }
@@ -47,18 +208,26 @@ export function registerTools(server, scout) {
             try {
                 parsed = JSON.parse(value);
                 if (!Array.isArray(parsed)) {
-                    parsed = value.split(',').map((s) => s.trim()).filter(Boolean);
+                    parsed = value
+                        .split(",")
+                        .map((s) => s.trim())
+                        .filter(Boolean);
                 }
             }
             catch {
-                parsed = value.split(',').map((s) => s.trim()).filter(Boolean);
+                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}"` }],
+                    content: [
+                        { type: "text", text: `Invalid number for "${key}": "${value}"` },
+                    ],
                     isError: true,
                 };
             }
@@ -66,13 +235,18 @@ export function registerTools(server, scout) {
         }
         else if (BOOLEAN_KEYS.has(key)) {
             const lower = value.toLowerCase();
-            if (lower === 'true' || lower === 'yes')
+            if (lower === "true" || lower === "yes")
                 parsed = true;
-            else if (lower === 'false' || lower === 'no')
+            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.` }],
+                    content: [
+                        {
+                            type: "text",
+                            text: `Invalid boolean for "${key}": "${value}". Use true/false or yes/no.`,
+                        },
+                    ],
                     isError: true,
                 };
             }
@@ -86,14 +260,19 @@ export function registerTools(server, scout) {
         // 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('; ');
+            const issues = result.error.issues
+                .map((i) => `${i.path.join(".")}: ${i.message}`)
+                .join("; ");
             return {
-                content: [{ type: 'text', text: `Validation error: ${issues}` }],
+                content: [{ type: "text", text: `Validation error: ${issues}` }],
                 isError: true,
             };
         }
         scout.updatePreferences({ [key]: parsed });
+        await scout.checkpoint();
         const updated = scout.getPreferences();
-        return { content: [{ type: 'text', text: JSON.stringify(updated, null, 2) }] };
+        return {
+            content: [{ type: "text", text: JSON.stringify(updated, null, 2) }],
+        };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/mcp",
-  "version": "0.2.0",
+  "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"
   }
-}
+}