@oss-scout/mcp 0.1.0

package/dist/resources.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,26 @@
+export function registerResources(server, scout) {
+    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',
+                text: JSON.stringify(scout.getSavedResults(), null, 2),
+            }],
+    }));
+    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',
+                    text: JSON.stringify(state.repoScores, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { SearchStrategySchema, ScoutPreferencesSchema } from '@oss-scout/core';
+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'),
+    }, 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) }] };
+    });
+    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) }] };
+    });
+    server.tool('config', 'Show current oss-scout configuration preferences', async () => {
+        const preferences = scout.getPreferences();
+        return { content: [{ type: 'text', text: JSON.stringify(preferences, null, 2) }] };
+    });
+    const VALID_KEYS = Object.keys(ScoutPreferencesSchema.shape);
+    const ARRAY_KEYS = new Set([
+        'languages', 'labels', 'preferredOrgs', 'projectCategories',
+        'excludeRepos', 'aiPolicyBlocklist', 'scope', 'defaultStrategy',
+    ]);
+    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'),
+    }, 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;
+        }
+        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('; ');
+            return {
+                content: [{ type: 'text', text: `Validation error: ${issues}` }],
+                isError: true,
+            };
+        }
+        scout.updatePreferences({ [key]: parsed });
+        const updated = scout.getPreferences();
+        return { content: [{ type: 'text', text: JSON.stringify(updated, null, 2) }] };
+    });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@oss-scout/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for oss-scout — exposes issue discovery and vetting as MCP tools",
+  "type": "module",
+  "bin": {
+    "oss-scout-mcp": "./dist/mcp-server.bundle.cjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "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"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "esbuild": "^0.27.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "@vitest/coverage-v8": "^4.1.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/costajohnt/oss-scout.git",
+    "directory": "packages/mcp-server"
+  }
+}