@dawmatt/api-grade-mcp 0.1.0

package/dist/tools/configure-ruleset.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { mcpError, ERROR_CODES } from '../utils/errors.js';
+import { saveWorkspaceConfig, saveGlobalConfig, getWorkspaceConfigPath, getGlobalConfigPath, ConfigWriteError, } from '../config/ruleset-config.js';
+export function registerConfigureRulesetTool(server, sessionState) {
+    server.tool('configure-ruleset', 'Set the default ruleset used by this MCP server when no rulesetPath is supplied on a grading request. Supports three scopes: session (in-memory, resets on server restart), workspace (persisted to .api-grade/config.json in the workspace root), and global (persisted to ~/.api-grade/config.json). Optionally configure authentication for rulesets hosted in secured locations.', {
+        scope: z
+            .enum(['session', 'workspace', 'global'])
+            .describe("Where to store this default: 'session' is in-memory for this server process only; 'workspace' persists to .api-grade/config.json in the current workspace root; 'global' persists to ~/.api-grade/config.json."),
+        rulesetPath: z
+            .string()
+            .nullish()
+            .describe('Absolute or relative file path, or HTTPS URL, to a Spectral-compatible ruleset file. To clear the default at this scope, omit this field or pass null.'),
+        auth: z
+            .object({
+            type: z.enum(['github-pat', 'entra-id']).describe("'github-pat' uses a Bearer token for GitHub Enterprise URLs. 'entra-id' uses Microsoft Entra ID OAuth 2.0 device-code flow."),
+            githubToken: z
+                .string()
+                .optional()
+                .describe("GitHub Personal Access Token. Only used when type is 'github-pat'. If omitted, falls back to GITHUB_TOKEN environment variable."),
+            tenantId: z
+                .string()
+                .optional()
+                .describe("Microsoft Entra ID tenant ID. Required when type is 'entra-id'."),
+            clientId: z
+                .string()
+                .optional()
+                .describe("Microsoft Entra ID application (client) ID. Required when type is 'entra-id'."),
+        })
+            .optional(),
+    }, async ({ scope, rulesetPath, auth }) => {
+        const input = { scope, rulesetPath, auth };
+        if (auth?.type === 'entra-id' && (!auth.tenantId || !auth.clientId)) {
+            return mcpError(ERROR_CODES.INVALID_AUTH_CONFIG, "auth.type 'entra-id' requires tenantId and clientId fields.", input);
+        }
+        const resolvedPath = rulesetPath ?? null;
+        const resolvedAuth = auth
+            ? {
+                type: auth.type,
+                ...(auth.type === 'github-pat' && auth.githubToken ? { githubToken: auth.githubToken } : {}),
+                ...(auth.type === 'entra-id' ? { tenantId: auth.tenantId, clientId: auth.clientId } : {}),
+            }
+            : null;
+        const config = { rulesetPath: resolvedPath, auth: resolvedAuth };
+        if (scope === 'session') {
+            sessionState.defaultRuleset = resolvedPath !== null ? config : null;
+            if (resolvedPath !== null) {
+                sessionState.sessionRulesetOverride = null;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            scope,
+                            rulesetPath: resolvedPath,
+                            auth: resolvedAuth ? { type: resolvedAuth.type } : null,
+                            message: resolvedPath !== null
+                                ? 'Session default ruleset configured. This setting applies for the duration of this server process.'
+                                : 'Session default ruleset cleared.',
+                        }),
+                    },
+                ],
+            };
+        }
+        const configFile = scope === 'workspace' ? getWorkspaceConfigPath() : getGlobalConfigPath();
+        const saveFn = scope === 'workspace' ? saveWorkspaceConfig : saveGlobalConfig;
+        try {
+            await saveFn(config);
+        }
+        catch (err) {
+            if (err instanceof ConfigWriteError) {
+                return mcpError(ERROR_CODES.CONFIG_WRITE_ERROR, err.message, input);
+            }
+            return mcpError(ERROR_CODES.CONFIG_WRITE_ERROR, `Could not write ${scope} config: ${err instanceof Error ? err.message : String(err)}`, input);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        scope,
+                        rulesetPath: resolvedPath,
+                        auth: resolvedAuth ? { type: resolvedAuth.type } : null,
+                        configFile,
+                        message: resolvedPath !== null
+                            ? `${scope.charAt(0).toUpperCase() + scope.slice(1)} default ruleset configured. This setting will apply to all grading requests in this ${scope} unless overridden by a higher-precedence default or a per-request rulesetPath.`
+                            : `${scope.charAt(0).toUpperCase() + scope.slice(1)} default ruleset cleared.`,
+                    }),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=configure-ruleset.js.map

package/dist/tools/configure-ruleset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure-ruleset.js","sourceRoot":"","sources":["../../src/tools/configure-ruleset.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-ruleset-config.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SessionState } from '../types.js';
+export declare function registerGetRulesetConfigTool(server: McpServer, sessionState: SessionState): void;
+//# sourceMappingURL=get-ruleset-config.d.ts.map

package/dist/tools/get-ruleset-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-ruleset-config.d.ts","sourceRoot":"","sources":["../../src/tools/get-ruleset-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAQ5D,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CA0DhG"}

package/dist/tools/get-ruleset-config.js

@@ -0,0 +1,53 @@
+import { loadWorkspaceConfig, loadGlobalConfig, getWorkspaceConfigPath, getGlobalConfigPath } from '../config/ruleset-config.js';
+import { resolveRuleset } from '../config/resolve-ruleset.js';
+function sanitizeAuth(auth, hasToken) {
+    if (!auth)
+        return null;
+    const tokenSource = hasToken ? 'config-file' : process.env.GITHUB_TOKEN ? 'env-var' : 'none';
+    return { type: auth.type, tokenSource };
+}
+export function registerGetRulesetConfigTool(server, sessionState) {
+    server.tool('get-ruleset-config', 'Return the active Spectral ruleset used by this MCP server when no rulesetPath is supplied on a grading request. Supports three scopes: session (in-memory, resets on server restart), workspace (persisted in workspace), and global (persisted to home). Return configuration at every scope, indicate which scope is currently in effect (the effective ruleset), and show the full resolution chain. Use this to diagnose why a particular ruleset is being applied or to confirm a set-ruleset-config call took effect.', {}, async () => {
+        const workspaceConfig = await loadWorkspaceConfig();
+        const globalConfig = await loadGlobalConfig();
+        const resolved = resolveRuleset(null, sessionState, workspaceConfig, globalConfig);
+        const sessionInfo = sessionState.defaultRuleset?.rulesetPath != null
+            ? {
+                rulesetPath: sessionState.defaultRuleset.rulesetPath,
+                auth: sanitizeAuth(sessionState.defaultRuleset.auth, !!(sessionState.defaultRuleset.auth?.githubToken)),
+            }
+            : null;
+        const workspaceInfo = workspaceConfig?.rulesetPath != null
+            ? {
+                rulesetPath: workspaceConfig.rulesetPath,
+                auth: sanitizeAuth(workspaceConfig.auth, false),
+                configFile: getWorkspaceConfigPath(),
+            }
+            : null;
+        const globalInfo = globalConfig?.rulesetPath != null
+            ? {
+                rulesetPath: globalConfig.rulesetPath,
+                auth: sanitizeAuth(globalConfig.auth, false),
+                configFile: getGlobalConfigPath(),
+            }
+            : null;
+        const effectiveAuth = resolved.auth
+            ? sanitizeAuth(resolved.auth, !!(resolved.auth.githubToken))
+            : null;
+        const response = {
+            effective: {
+                scope: resolved.scope,
+                rulesetPath: resolved.rulesetPath,
+                ...(effectiveAuth ? { auth: effectiveAuth } : {}),
+            },
+            session: sessionInfo,
+            workspace: workspaceInfo,
+            global: globalInfo,
+            builtIn: 'default',
+            precedenceOrder: ['session', 'workspace', 'global', 'built-in'],
+            note: 'Per-request rulesetPath (if supplied on a grading call) always takes precedence over all configured defaults.',
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+    });
+}
+//# sourceMappingURL=get-ruleset-config.js.map

package/dist/tools/get-ruleset-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-ruleset-config.js","sourceRoot":"","sources":["../../src/tools/get-ruleset-config.ts"],"names":[],"mappings":"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"}

package/dist/tools/grade-detailed.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SessionState } from '../types.js';
+export declare function registerGradeDetailedTool(server: McpServer, sessionState: SessionState): void;
+//# sourceMappingURL=grade-detailed.d.ts.map

package/dist/tools/grade-detailed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grade-detailed.d.ts","sourceRoot":"","sources":["../../src/tools/grade-detailed.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CAqJ7F"}

package/dist/tools/grade-detailed.js

@@ -0,0 +1,143 @@
+import { statSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { GradeEngine } from '@dawmatt/api-grade-core';
+import { mcpError, buildAuthFailureResponse, ERROR_CODES } from '../utils/errors.js';
+import { loadWorkspaceConfig, loadGlobalConfig } from '../config/ruleset-config.js';
+import { resolveRuleset } from '../config/resolve-ruleset.js';
+import { fetchRulesetContent, RulesetAuthError, INITIAL_FETCH_TIMEOUT_MS, RETRY_FETCH_TIMEOUT_MS } from '../auth/github.js';
+import { EntraAuthRequired, acquireEntraToken } from '../auth/entra.js';
+const LARGE_SPEC_THRESHOLD_BYTES = 500_000;
+const MAX_DIAGNOSTICS = 100;
+export function registerGradeDetailedTool(server, sessionState) {
+    server.tool('grade-api-detailed', 'Grade an API specification and return the full result including all individual violations, per-category breakdowns, and prioritised recommendations. Use this when you need to analyse specific violations or present detailed findings to the user. Supports OpenAPI (2.x, 3.x) and AsyncAPI (2.x, 3.x).', {
+        specPath: z
+            .string()
+            .describe('Absolute or relative path to the OpenAPI or AsyncAPI specification file (YAML or JSON)'),
+        rulesetPath: z
+            .string()
+            .optional()
+            .describe('Optional path to a custom Spectral-compatible ruleset file'),
+        recoveryOption: z
+            .enum(['retry', 'use-builtin-once', 'use-builtin-session', 'cancel'])
+            .optional()
+            .describe('Recovery action when the configured default ruleset is inaccessible. Only supply in response to a RULESET_AUTH_FAILED response.'),
+    }, async ({ specPath, rulesetPath, recoveryOption }) => {
+        if (recoveryOption === 'cancel') {
+            return mcpError(ERROR_CODES.REQUEST_CANCELLED, 'Grading request cancelled by user.', { specPath });
+        }
+        if (recoveryOption === 'use-builtin-session') {
+            sessionState.sessionRulesetOverride = 'builtin';
+        }
+        const workspaceConfig = await loadWorkspaceConfig();
+        const globalConfig = await loadGlobalConfig();
+        const resolved = resolveRuleset(rulesetPath, sessionState, workspaceConfig, globalConfig);
+        let effectiveRulesetPath = resolved.rulesetPath ?? undefined;
+        let tempRulesetFile;
+        if (resolved.rulesetPath?.startsWith('http')) {
+            if (recoveryOption === 'use-builtin-once') {
+                effectiveRulesetPath = undefined;
+            }
+            else {
+                const timeoutMs = recoveryOption === 'retry' ? RETRY_FETCH_TIMEOUT_MS : INITIAL_FETCH_TIMEOUT_MS;
+                try {
+                    let content;
+                    if (resolved.auth?.type === 'github-pat') {
+                        const token = resolved.auth.githubToken ?? process.env.GITHUB_TOKEN ?? '';
+                        content = await fetchRulesetContent(resolved.rulesetPath, token || undefined, timeoutMs);
+                    }
+                    else if (resolved.auth?.type === 'entra-id' && resolved.auth.tenantId && resolved.auth.clientId) {
+                        const token = await acquireEntraToken(resolved.auth.tenantId, resolved.auth.clientId);
+                        content = await fetchRulesetContent(resolved.rulesetPath, token, timeoutMs);
+                    }
+                    else {
+                        content = await fetchRulesetContent(resolved.rulesetPath, undefined, timeoutMs);
+                    }
+                    tempRulesetFile = join(tmpdir(), `api-grade-ruleset-${Date.now()}.yaml`);
+                    writeFileSync(tempRulesetFile, content);
+                    effectiveRulesetPath = tempRulesetFile;
+                }
+                catch (err) {
+                    if (err instanceof EntraAuthRequired) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: ERROR_CODES.ENTRA_AUTH_REQUIRED,
+                                        deviceCodeUrl: err.verificationUri,
+                                        userCode: err.userCode,
+                                        expiresIn: err.expiresIn,
+                                        message: `Complete Entra ID sign-in: Visit ${err.verificationUri} and enter code ${err.userCode}`,
+                                    }),
+                                }],
+                            isError: true,
+                        };
+                    }
+                    const reason = err instanceof RulesetAuthError ? err.reason : 'network-unreachable';
+                    return buildAuthFailureResponse(reason, resolved.rulesetPath, resolved.scope, `Could not fetch ruleset from '${resolved.rulesetPath}' (${resolved.scope} default): ${reason.replace('-', ' ')}.`);
+                }
+            }
+        }
+        else if (effectiveRulesetPath) {
+            try {
+                statSync(effectiveRulesetPath);
+            }
+            catch {
+                return mcpError(ERROR_CODES.RULESET_NOT_FOUND, `The ruleset file '${effectiveRulesetPath}' does not exist. Check the path and try again.`, { rulesetPath: effectiveRulesetPath });
+            }
+        }
+        let largeSpecWarning;
+        try {
+            const stat = statSync(specPath);
+            if (stat.size > LARGE_SPEC_THRESHOLD_BYTES) {
+                largeSpecWarning = `Specification exceeds 500KB (${stat.size} bytes); diagnostic results may be truncated`;
+            }
+        }
+        catch {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+            return mcpError(ERROR_CODES.SPEC_NOT_FOUND, `The specification file '${specPath}' does not exist. Check the path and try again.`, { specPath });
+        }
+        try {
+            const engine = new GradeEngine();
+            const result = await engine.grade({ specPath, rulesetPath: effectiveRulesetPath });
+            let truncated = false;
+            let diagnostics = result.diagnostics;
+            if (diagnostics.length > MAX_DIAGNOSTICS) {
+                diagnostics = diagnostics.slice(0, MAX_DIAGNOSTICS);
+                truncated = true;
+            }
+            const response = {
+                specPath: result.specPath,
+                format: result.format,
+                letterGrade: result.letterGrade,
+                gradeLabel: result.gradeLabel,
+                numericScore: result.numericScore,
+                summary: result.summary,
+                diagnostics,
+                rulesetSource: result.rulesetSource,
+                truncated,
+            };
+            if (largeSpecWarning) {
+                response.largeSpecWarning = largeSpecWarning;
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpError(ERROR_CODES.GRADE_ENGINE_ERROR, `GradeEngine error: ${message}`, { specPath });
+        }
+        finally {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+        }
+    });
+}
+//# sourceMappingURL=grade-detailed.js.map

package/dist/tools/grade-detailed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grade-detailed.js","sourceRoot":"","sources":["../../src/tools/grade-detailed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC5H,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGxE,MAAM,0BAA0B,GAAG,OAAO,CAAC;AAC3C,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B,MAAM,UAAU,yBAAyB,CAAC,MAAiB,EAAE,YAA0B;IACrF,MAAM,CAAC,IAAI,CACT,oBAAoB,EACpB,2SAA2S,EAC3S;QACE,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,CACP,wFAAwF,CACzF;QACH,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,4DAA4D,CAAC;QACzE,cAAc,EAAE,CAAC;aACd,IAAI,CAAC,CAAC,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,QAAQ,CAAC,CAAC;aACpE,QAAQ,EAAE;aACV,QAAQ,CACP,iIAAiI,CAClI;KACJ,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE,EAAE;QAClD,IAAI,cAAc,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,QAAQ,CAAC,WAAW,CAAC,iBAAiB,EAAE,oCAAoC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrG,CAAC;QAED,IAAI,cAAc,KAAK,qBAAqB,EAAE,CAAC;YAC7C,YAAY,CAAC,sBAAsB,GAAG,SAAS,CAAC;QAClD,CAAC;QAED,MAAM,eAAe,GAAG,MAAM,mBAAmB,EAAE,CAAC;QACpD,MAAM,YAAY,GAAG,MAAM,gBAAgB,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC;QAE1F,IAAI,oBAAoB,GAAuB,QAAQ,CAAC,WAAW,IAAI,SAAS,CAAC;QACjF,IAAI,eAAmC,CAAC;QAExC,IAAI,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7C,IAAI,cAAc,KAAK,kBAAkB,EAAE,CAAC;gBAC1C,oBAAoB,GAAG,SAAS,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,MAAM,SAAS,GAAG,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,wBAAwB,CAAC;gBACjG,IAAI,CAAC;oBACH,IAAI,OAAe,CAAC;oBACpB,IAAI,QAAQ,CAAC,IAAI,EAAE,IAAI,KAAK,YAAY,EAAE,CAAC;wBACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;wBAC1E,OAAO,GAAG,MAAM,mBAAmB,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,IAAI,SAAS,EAAE,SAAS,CAAC,CAAC;oBAC3F,CAAC;yBAAM,IAAI,QAAQ,CAAC,IAAI,EAAE,IAAI,KAAK,UAAU,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;wBAClG,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;wBACtF,OAAO,GAAG,MAAM,mBAAmB,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;oBAC9E,CAAC;yBAAM,CAAC;wBACN,OAAO,GAAG,MAAM,mBAAmB,CAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;oBAClF,CAAC;oBACD,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,qBAAqB,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;oBACzE,aAAa,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;oBACxC,oBAAoB,GAAG,eAAe,CAAC;gBACzC,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;wBACrC,OAAO;4BACL,OAAO,EAAE,CAAC;oCACR,IAAI,EAAE,MAAM;oCACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wCACnB,KAAK,EAAE,WAAW,CAAC,mBAAmB;wCACtC,aAAa,EAAE,GAAG,CAAC,eAAe;wCAClC,QAAQ,EAAE,GAAG,CAAC,QAAQ;wCACtB,SAAS,EAAE,GAAG,CAAC,SAAS;wCACxB,OAAO,EAAE,oCAAoC,GAAG,CAAC,eAAe,mBAAmB,GAAG,CAAC,QAAQ,EAAE;qCAClG,CAAC;iCACH,CAAC;4BACF,OAAO,EAAE,IAAa;yBACvB,CAAC;oBACJ,CAAC;oBACD,MAAM,MAAM,GAAG,GAAG,YAAY,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC;oBACpF,OAAO,wBAAwB,CAC7B,MAAM,EACN,QAAQ,CAAC,WAAW,EACpB,QAAQ,CAAC,KAAK,EACd,iCAAiC,QAAQ,CAAC,WAAW,MAAM,QAAQ,CAAC,KAAK,cAAc,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CACnH,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;aAAM,IAAI,oBAAoB,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,QAAQ,CAAC,oBAAoB,CAAC,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,QAAQ,CACb,WAAW,CAAC,iBAAiB,EAC7B,qBAAqB,oBAAoB,iDAAiD,EAC1F,EAAE,WAAW,EAAE,oBAAoB,EAAE,CACtC,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,gBAAoC,CAAC;QAEzC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAChC,IAAI,IAAI,CAAC,IAAI,GAAG,0BAA0B,EAAE,CAAC;gBAC3C,gBAAgB,GAAG,gCAAgC,IAAI,CAAC,IAAI,8CAA8C,CAAC;YAC7G,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,eAAe;gBAAE,IAAI,CAAC;oBAAC,UAAU,CAAC,eAAe,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;YAChF,OAAO,QAAQ,CACb,WAAW,CAAC,cAAc,EAC1B,2BAA2B,QAAQ,iDAAiD,EACpF,EAAE,QAAQ,EAAE,CACb,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC,CAAC;YAEnF,IAAI,SAAS,GAAG,KAAK,CAAC;YACtB,IAAI,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;YACrC,IAAI,WAAW,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;gBACzC,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;gBACpD,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;YAED,MAAM,QAAQ,GAA4B;gBACxC,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,WAAW;gBACX,aAAa,EAAE,MAAM,CAAC,aAAa;gBACnC,SAAS;aACV,CAAC;YAEF,IAAI,gBAAgB,EAAE,CAAC;gBACrB,QAAQ,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;YAC/C,CAAC;YAED,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACzE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,QAAQ,CACb,WAAW,CAAC,kBAAkB,EAC9B,sBAAsB,OAAO,EAAE,EAC/B,EAAE,QAAQ,EAAE,CACb,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,IAAI,eAAe;gBAAE,IAAI,CAAC;oBAAC,UAAU,CAAC,eAAe,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QAClF,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/grade.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SessionState } from '../types.js';
+export declare function registerGradeTool(server: McpServer, sessionState: SessionState): void;
+//# sourceMappingURL=grade.d.ts.map

package/dist/tools/grade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grade.d.ts","sourceRoot":"","sources":["../../src/tools/grade.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CA8IrF"}

package/dist/tools/grade.js

@@ -0,0 +1,134 @@
+import { statSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { GradeEngine } from '@dawmatt/api-grade-core';
+import { mcpError, buildAuthFailureResponse, ERROR_CODES } from '../utils/errors.js';
+import { loadWorkspaceConfig, loadGlobalConfig } from '../config/ruleset-config.js';
+import { resolveRuleset } from '../config/resolve-ruleset.js';
+import { fetchRulesetContent, RulesetAuthError, INITIAL_FETCH_TIMEOUT_MS, RETRY_FETCH_TIMEOUT_MS } from '../auth/github.js';
+import { EntraAuthRequired, acquireEntraToken } from '../auth/entra.js';
+const LARGE_SPEC_THRESHOLD_BYTES = 500_000;
+export function registerGradeTool(server, sessionState) {
+    server.tool('grade-api', 'Grade an API specification file and return quality score, letter grade, and diagnostic summary. Use this for a token-efficient overview without the full violations list. Supports OpenAPI (2.x, 3.x) and AsyncAPI (2.x, 3.x) specifications in YAML or JSON.', {
+        specPath: z
+            .string()
+            .describe('Absolute or relative path to the OpenAPI or AsyncAPI specification file (YAML or JSON)'),
+        rulesetPath: z
+            .string()
+            .optional()
+            .describe('Optional path to a custom Spectral-compatible ruleset file. If omitted, the default api-grade ruleset is used.'),
+        recoveryOption: z
+            .enum(['retry', 'use-builtin-once', 'use-builtin-session', 'cancel'])
+            .optional()
+            .describe('Recovery action when the configured default ruleset is inaccessible. Only supply in response to a RULESET_AUTH_FAILED response.'),
+    }, async ({ specPath, rulesetPath, recoveryOption }) => {
+        if (recoveryOption === 'cancel') {
+            return mcpError(ERROR_CODES.REQUEST_CANCELLED, 'Grading request cancelled by user.', { specPath });
+        }
+        if (recoveryOption === 'use-builtin-session') {
+            sessionState.sessionRulesetOverride = 'builtin';
+        }
+        const workspaceConfig = await loadWorkspaceConfig();
+        const globalConfig = await loadGlobalConfig();
+        const resolved = resolveRuleset(rulesetPath, sessionState, workspaceConfig, globalConfig);
+        let effectiveRulesetPath = resolved.rulesetPath ?? undefined;
+        let tempRulesetFile;
+        if (resolved.rulesetPath?.startsWith('http')) {
+            if (recoveryOption === 'use-builtin-once') {
+                effectiveRulesetPath = undefined;
+            }
+            else {
+                const timeoutMs = recoveryOption === 'retry' ? RETRY_FETCH_TIMEOUT_MS : INITIAL_FETCH_TIMEOUT_MS;
+                try {
+                    let content;
+                    if (resolved.auth?.type === 'github-pat') {
+                        const token = resolved.auth.githubToken ?? process.env.GITHUB_TOKEN ?? '';
+                        content = await fetchRulesetContent(resolved.rulesetPath, token || undefined, timeoutMs);
+                    }
+                    else if (resolved.auth?.type === 'entra-id' && resolved.auth.tenantId && resolved.auth.clientId) {
+                        const token = await acquireEntraToken(resolved.auth.tenantId, resolved.auth.clientId);
+                        content = await fetchRulesetContent(resolved.rulesetPath, token, timeoutMs);
+                    }
+                    else {
+                        content = await fetchRulesetContent(resolved.rulesetPath, undefined, timeoutMs);
+                    }
+                    tempRulesetFile = join(tmpdir(), `api-grade-ruleset-${Date.now()}.yaml`);
+                    writeFileSync(tempRulesetFile, content);
+                    effectiveRulesetPath = tempRulesetFile;
+                }
+                catch (err) {
+                    if (err instanceof EntraAuthRequired) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: ERROR_CODES.ENTRA_AUTH_REQUIRED,
+                                        deviceCodeUrl: err.verificationUri,
+                                        userCode: err.userCode,
+                                        expiresIn: err.expiresIn,
+                                        message: `Complete Entra ID sign-in: Visit ${err.verificationUri} and enter code ${err.userCode}`,
+                                    }),
+                                }],
+                            isError: true,
+                        };
+                    }
+                    const reason = err instanceof RulesetAuthError ? err.reason : 'network-unreachable';
+                    return buildAuthFailureResponse(reason, resolved.rulesetPath, resolved.scope, `Could not fetch ruleset from '${resolved.rulesetPath}' (${resolved.scope} default): ${reason.replace('-', ' ')}.`);
+                }
+            }
+        }
+        else if (effectiveRulesetPath) {
+            try {
+                statSync(effectiveRulesetPath);
+            }
+            catch {
+                return mcpError(ERROR_CODES.RULESET_NOT_FOUND, `The ruleset file '${effectiveRulesetPath}' does not exist. Check the path and try again.`, { rulesetPath: effectiveRulesetPath });
+            }
+        }
+        let largeSpecWarning;
+        try {
+            const stat = statSync(specPath);
+            if (stat.size > LARGE_SPEC_THRESHOLD_BYTES) {
+                largeSpecWarning = `Specification exceeds 500KB (${stat.size} bytes); diagnostic results may be truncated`;
+            }
+        }
+        catch {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+            return mcpError(ERROR_CODES.SPEC_NOT_FOUND, `The specification file '${specPath}' does not exist. Check the path and try again.`, { specPath });
+        }
+        try {
+            const engine = new GradeEngine();
+            const result = await engine.grade({ specPath, rulesetPath: effectiveRulesetPath });
+            const response = {
+                specPath: result.specPath,
+                format: result.format,
+                letterGrade: result.letterGrade,
+                gradeLabel: result.gradeLabel,
+                numericScore: result.numericScore,
+                summary: result.summary,
+                rulesetSource: result.rulesetSource,
+            };
+            if (largeSpecWarning) {
+                response.largeSpecWarning = largeSpecWarning;
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpError(ERROR_CODES.GRADE_ENGINE_ERROR, `GradeEngine error: ${message}`, { specPath });
+        }
+        finally {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+        }
+    });
+}
+//# sourceMappingURL=grade.js.map

package/dist/tools/grade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grade.js","sourceRoot":"","sources":["../../src/tools/grade.ts"],"names":[],"mappings":"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"}

package/dist/tools/non-breaking.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SessionState } from '../types.js';
+export declare function registerNonBreakingTool(server: McpServer, sessionState: SessionState): void;
+//# sourceMappingURL=non-breaking.d.ts.map

package/dist/tools/non-breaking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"non-breaking.d.ts","sourceRoot":"","sources":["../../src/tools/non-breaking.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CAgJ3F"}