@stacksfinder/mcp-server 1.5.1 → 1.6.0

package/dist/tools/audit.js

@@ -1,7 +1,7 @@
-import { z } from 'zod';
-import { apiRequest } from '../utils/api-client.js';
-import { McpError, ErrorCode, checkProAccess } from '../utils/errors.js';
-import { debug } from '../utils/logger.js';
+import { z } from "zod";
+import { apiRequest } from "../utils/api-client.js";
+import { McpError, ErrorCode, checkProAccess } from "../utils/errors.js";
+import { debug } from "../utils/logger.js";
 // ============================================================================
 // SCHEMAS
 // ============================================================================
@@ -9,36 +9,51 @@ import { debug } from '../utils/logger.js';
  * Input schema for create_audit tool.
  */
 export const CreateAuditInputSchema = z.object({
-    name: z.string().min(1).max(200).describe('Name for the audit report'),
+    name: z.string().min(1).max(200).describe("Name for the audit report"),
     technologies: z
         .array(z.object({
-        name: z.string().min(1).describe('Technology name (e.g., "react", "express", "lodash")'),
-        version: z.string().optional().describe('Version string (e.g., "18.2.0", "4.17.21")'),
-        category: z.string().optional().describe('Optional category (e.g., "frontend", "backend")')
+        name: z
+            .string()
+            .min(1)
+            .describe('Technology name (e.g., "react", "express", "lodash")'),
+        version: z
+            .string()
+            .optional()
+            .describe('Version string (e.g., "18.2.0", "4.17.21")'),
+        category: z
+            .string()
+            .optional()
+            .describe('Optional category (e.g., "frontend", "backend")'),
     }))
         .min(1)
         .max(50)
-        .describe('List of technologies to audit')
+        .describe("List of technologies to audit"),
 });
 /**
  * Input schema for get_audit tool.
  */
 export const GetAuditInputSchema = z.object({
-    auditId: z.string().uuid().describe('Audit report UUID')
+    auditId: z.string().uuid().describe("Audit report UUID"),
 });
 /**
  * Input schema for list_audits tool.
  */
 export const ListAuditsInputSchema = z.object({
-    limit: z.number().min(1).max(50).optional().default(10).describe('Max results to return'),
-    offset: z.number().min(0).optional().default(0).describe('Pagination offset')
+    limit: z
+        .number()
+        .min(1)
+        .max(50)
+        .optional()
+        .default(10)
+        .describe("Max results to return"),
+    offset: z.number().min(0).optional().default(0).describe("Pagination offset"),
 });
 /**
  * Input schema for compare_audits tool.
  */
 export const CompareAuditsInputSchema = z.object({
-    baseAuditId: z.string().uuid().describe('Base audit ID (older)'),
-    compareAuditId: z.string().uuid().describe('Compare audit ID (newer)')
+    baseAuditId: z.string().uuid().describe("Base audit ID (older)"),
+    compareAuditId: z.string().uuid().describe("Compare audit ID (newer)"),
 });
 /**
  * Input schema for get_audit_quota tool.
@@ -48,165 +63,168 @@ export const GetAuditQuotaInputSchema = z.object({});
  * Input schema for get_migration_recommendation tool.
  */
 export const GetMigrationRecommendationInputSchema = z.object({
-    auditId: z.string().uuid().describe('Audit report UUID to analyze for migration')
+    auditId: z
+        .string()
+        .uuid()
+        .describe("Audit report UUID to analyze for migration"),
 });
 // ============================================================================
 // TOOL DEFINITIONS
 // ============================================================================
 export const createAuditToolDefinition = {
-    name: 'create_audit',
-    description: `Create a technical debt audit for your tech stack. Analyzes for deprecated packages, security vulnerabilities, EOL versions, and upgrade recommendations.
-
-**Tier**: Requires Pro or Team subscription (OR OAuth session)
-
-**Prerequisites**:
-- Pro/Team account or authenticated via OAuth
-- List of technologies with versions (use package.json data)
-
-**Next Steps**:
-- Get full report: \`get_audit({ auditId: "returned-uuid" })\`
-- Get migration plan: \`get_migration_recommendation({ auditId: "uuid" })\`
-- Compare over time: \`compare_audits({ baseAuditId, compareAuditId })\`
-
-**Output includes**:
-- Health score (0-100)
-- Findings by severity (critical/high/medium/low/info)
-- Actionable upgrade recommendations
-- CVE detection for known vulnerabilities
-
-**Common Pitfalls**:
-- Include version numbers for accurate vulnerability detection
-- Use technology names as they appear in package managers
-
+    name: "create_audit",
+    description: `Create a technical debt audit for your tech stack. Analyzes for deprecated packages, security vulnerabilities, EOL versions, and upgrade recommendations.
+
+**Tier**: Requires Pro or Team subscription (OR OAuth session)
+
+**Prerequisites**:
+- Pro/Team account or authenticated via OAuth
+- List of technologies with versions (use package.json data)
+
+**Next Steps**:
+- Get full report: \`get_audit({ auditId: "returned-uuid" })\`
+- Get migration plan: \`get_migration_recommendation({ auditId: "uuid" })\`
+- Compare over time: \`compare_audits({ baseAuditId, compareAuditId })\`
+
+**Output includes**:
+- Health score (0-100)
+- Findings by severity (critical/high/medium/low/info)
+- Actionable upgrade recommendations
+- CVE detection for known vulnerabilities
+
+**Common Pitfalls**:
+- Include version numbers for accurate vulnerability detection
+- Use technology names as they appear in package managers
+
 **Example**: \`create_audit({ name: "Q1 2026 Stack Review", technologies: [{ name: "React", version: "17.0.0" }, { name: "Node.js", version: "14.0.0" }] })\``,
     inputSchema: {
-        type: 'object',
+        type: "object",
         properties: {
             name: {
-                type: 'string',
-                description: 'Name for the audit report (e.g., "Q1 2026 Stack Review")'
+                type: "string",
+                description: 'Name for the audit report (e.g., "Q1 2026 Stack Review")',
             },
             technologies: {
-                type: 'array',
+                type: "array",
                 items: {
-                    type: 'object',
+                    type: "object",
                     properties: {
-                        name: { type: 'string', description: 'Technology name' },
-                        version: { type: 'string', description: 'Version (optional)' },
-                        category: { type: 'string', description: 'Category (optional)' }
+                        name: { type: "string", description: "Technology name" },
+                        version: { type: "string", description: "Version (optional)" },
+                        category: { type: "string", description: "Category (optional)" },
                     },
-                    required: ['name']
+                    required: ["name"],
                 },
-                description: 'Technologies to audit'
-            }
+                description: "Technologies to audit",
+            },
         },
-        required: ['name', 'technologies']
-    }
+        required: ["name", "technologies"],
+    },
 };
 export const getAuditToolDefinition = {
-    name: 'get_audit',
-    description: 'Fetch a completed audit report by ID. Returns all findings and health score.',
+    name: "get_audit",
+    description: "Fetch a completed audit report by ID. Returns all findings and health score.",
     inputSchema: {
-        type: 'object',
+        type: "object",
         properties: {
             auditId: {
-                type: 'string',
-                format: 'uuid',
-                description: 'Audit report UUID'
-            }
+                type: "string",
+                format: "uuid",
+                description: "Audit report UUID",
+            },
         },
-        required: ['auditId']
-    }
+        required: ["auditId"],
+    },
 };
 export const listAuditsToolDefinition = {
-    name: 'list_audits',
-    description: 'List your audit reports with pagination. Shows name, status, health score, and creation date.',
+    name: "list_audits",
+    description: "List your audit reports with pagination. Shows name, status, health score, and creation date.",
     inputSchema: {
-        type: 'object',
+        type: "object",
         properties: {
             limit: {
-                type: 'number',
-                description: 'Max results (1-50, default 10)'
+                type: "number",
+                description: "Max results (1-50, default 10)",
             },
             offset: {
-                type: 'number',
-                description: 'Pagination offset (default 0)'
-            }
+                type: "number",
+                description: "Pagination offset (default 0)",
+            },
         },
-        required: []
-    }
+        required: [],
+    },
 };
 export const compareAuditsToolDefinition = {
-    name: 'compare_audits',
-    description: `Compare two audit reports to track technical debt trends over time.
-Shows new issues introduced, issues resolved, and health score change.
+    name: "compare_audits",
+    description: `Compare two audit reports to track technical debt trends over time.
+Shows new issues introduced, issues resolved, and health score change.
 Useful for measuring progress on debt reduction.`,
     inputSchema: {
-        type: 'object',
+        type: "object",
         properties: {
             baseAuditId: {
-                type: 'string',
-                format: 'uuid',
-                description: 'Base (older) audit ID'
+                type: "string",
+                format: "uuid",
+                description: "Base (older) audit ID",
             },
             compareAuditId: {
-                type: 'string',
-                format: 'uuid',
-                description: 'Compare (newer) audit ID'
-            }
+                type: "string",
+                format: "uuid",
+                description: "Compare (newer) audit ID",
+            },
         },
-        required: ['baseAuditId', 'compareAuditId']
-    }
+        required: ["baseAuditId", "compareAuditId"],
+    },
 };
 export const getAuditQuotaToolDefinition = {
-    name: 'get_audit_quota',
-    description: 'Check your remaining audit quota for this month.',
+    name: "get_audit_quota",
+    description: "Check your remaining audit quota for this month.",
     inputSchema: {
-        type: 'object',
+        type: "object",
         properties: {},
-        required: []
-    }
+        required: [],
+    },
 };
 export const getMigrationRecommendationToolDefinition = {
-    name: 'get_migration_recommendation',
-    description: `Analyze an audit report for migration opportunities.
-Returns a detailed migration recommendation including:
-- Technologies that should be replaced
-- Recommended modern alternatives
-- Migration roadmap with phases
-- Risk assessment
-- Builder constraints to pre-fill for generating a migration blueprint
-
+    name: "get_migration_recommendation",
+    description: `Analyze an audit report for migration opportunities.
+Returns a detailed migration recommendation including:
+- Technologies that should be replaced
+- Recommended modern alternatives
+- Migration roadmap with phases
+- Risk assessment
+- Builder constraints to pre-fill for generating a migration blueprint
+
 Use this after create_audit to get actionable migration guidance.`,
     inputSchema: {
-        type: 'object',
+        type: "object",
         properties: {
             auditId: {
-                type: 'string',
-                format: 'uuid',
-                description: 'Audit report UUID to analyze'
-            }
+                type: "string",
+                format: "uuid",
+                description: "Audit report UUID to analyze",
+            },
         },
-        required: ['auditId']
-    }
+        required: ["auditId"],
+    },
 };
 // ============================================================================
 // FORMATTERS
 // ============================================================================
 function formatSeverityMarker(severity) {
     switch (severity) {
-        case 'critical':
-            return '[CRITICAL]';
-        case 'high':
-            return '[HIGH]';
-        case 'medium':
-            return '[MEDIUM]';
-        case 'low':
-            return '[LOW]';
-        case 'info':
-            return '[INFO]';
+        case "critical":
+            return "[CRITICAL]";
+        case "high":
+            return "[HIGH]";
+        case "medium":
+            return "[MEDIUM]";
+        case "low":
+            return "[LOW]";
+        case "info":
+            return "[INFO]";
         default:
-            return '[-]';
+            return "[-]";
     }
 }
 function formatHealthScore(score) {
@@ -255,7 +273,7 @@ function formatAuditReport(audit) {
                 text += `**Migration Effort**: ${finding.migrationEffort}\n`;
             }
             if (finding.cveIds && finding.cveIds.length > 0) {
-                text += `**CVEs**: ${finding.cveIds.join(', ')}\n`;
+                text += `**CVEs**: ${finding.cveIds.join(", ")}\n`;
             }
             text += `\n**Action**: ${finding.suggestedAction}\n\n`;
             if (finding.references && finding.references.length > 0) {
@@ -267,7 +285,7 @@ function formatAuditReport(audit) {
             text += `---\n\n`;
         }
     }
-    else if (audit.status === 'completed') {
+    else if (audit.status === "completed") {
         text += `\n### All Clear\n`;
         text += `Your stack passed all checks. Great job maintaining your technical health!\n`;
     }
@@ -281,13 +299,13 @@ function formatComparison(comparison) {
     text += `| ${comparison.baseAudit.name} (base) | ${comparison.baseAudit.healthScore}/100 |\n`;
     text += `| ${comparison.compareAudit.name} (compare) | ${comparison.compareAudit.healthScore}/100 |\n`;
     text += `\n`;
-    const trendMarker = comparison.trend === 'improving'
-        ? '[UP]'
-        : comparison.trend === 'degrading'
-            ? '[DOWN]'
-            : '[STABLE]';
+    const trendMarker = comparison.trend === "improving"
+        ? "[UP]"
+        : comparison.trend === "degrading"
+            ? "[DOWN]"
+            : "[STABLE]";
     text += `### Trend: ${trendMarker} ${comparison.trend.toUpperCase()}\n`;
-    text += `**Health Score Change**: ${comparison.healthScoreDelta > 0 ? '+' : ''}${comparison.healthScoreDelta} points\n\n`;
+    text += `**Health Score Change**: ${comparison.healthScoreDelta > 0 ? "+" : ""}${comparison.healthScoreDelta} points\n\n`;
     if (comparison.resolvedCount > 0) {
         text += `### Resolved Issues (${comparison.resolvedCount})\n`;
         for (const finding of comparison.resolvedFindings) {
@@ -317,10 +335,10 @@ function formatMigrationRecommendation(response) {
         return `## Migration Analysis\n\nUnable to generate recommendation.`;
     }
     const urgencyMarker = {
-        critical: '[CRITICAL]',
-        high: '[HIGH]',
-        medium: '[MEDIUM]',
-        low: '[LOW]'
+        critical: "[CRITICAL]",
+        high: "[HIGH]",
+        medium: "[MEDIUM]",
+        low: "[LOW]",
     }[rec.urgency];
     let text = `## ${urgencyMarker} Migration Recommendation\n\n`;
     text += `### ${rec.title}\n\n`;
@@ -337,7 +355,7 @@ function formatMigrationRecommendation(response) {
         text += `| Technology | Version | Reason |\n`;
         text += `|------------|---------|--------|\n`;
         for (const tech of rec.techsToReplace) {
-            text += `| ${tech.name} | ${tech.currentVersion || '-'} | ${tech.reason} |\n`;
+            text += `| ${tech.name} | ${tech.currentVersion || "-"} | ${tech.reason} |\n`;
         }
         text += `\n`;
     }
@@ -346,8 +364,8 @@ function formatMigrationRecommendation(response) {
         text += `### Recommended Alternatives\n\n`;
         for (const alt of rec.suggestedAlternatives) {
             text += `**${alt.forTech}** → `;
-            const alts = alt.alternatives.map(a => a === alt.preferredChoice ? `**${a}** (recommended)` : a);
-            text += alts.join(', ');
+            const alts = alt.alternatives.map((a) => a === alt.preferredChoice ? `**${a}** (recommended)` : a);
+            text += alts.join(", ");
             text += `\n`;
             text += `  _${alt.reason}_\n\n`;
         }
@@ -359,7 +377,7 @@ function formatMigrationRecommendation(response) {
             text += `**Phase ${step.order}: ${step.phase}** (${step.effort} effort)\n`;
             text += `${step.description}\n`;
             if (step.techsAffected.length > 0) {
-                text += `Affects: ${step.techsAffected.join(', ')}\n`;
+                text += `Affects: ${step.techsAffected.join(", ")}\n`;
             }
             text += `\n`;
         }
@@ -368,7 +386,11 @@ function formatMigrationRecommendation(response) {
     if (rec.risks.length > 0) {
         text += `### Risk Assessment\n\n`;
         for (const risk of rec.risks) {
-            const riskMarker = risk.level === 'high' ? '[HIGH]' : risk.level === 'medium' ? '[MEDIUM]' : '[LOW]';
+            const riskMarker = risk.level === "high"
+                ? "[HIGH]"
+                : risk.level === "medium"
+                    ? "[MEDIUM]"
+                    : "[LOW]";
             text += `${riskMarker} **${risk.level.toUpperCase()} RISK**: ${risk.description}\n`;
             text += `   _Mitigation_: ${risk.mitigation}\n\n`;
         }
@@ -377,7 +399,7 @@ function formatMigrationRecommendation(response) {
     if (rec.inferredConstraints.length > 0) {
         text += `### Inferred Builder Constraints\n\n`;
         text += `These constraints will be pre-filled when generating a migration blueprint:\n`;
-        text += rec.inferredConstraints.map(c => `\`${c}\``).join(', ');
+        text += rec.inferredConstraints.map((c) => `\`${c}\``).join(", ");
         text += `\n\n`;
     }
     // Builder Pre-fill info
@@ -391,10 +413,10 @@ function formatMigrationRecommendation(response) {
             text += `- **Scale**: ${response.builderPreFill.context.scale}\n`;
         }
         if (response.builderPreFill.context.priorities.length > 0) {
-            text += `- **Priorities**: ${response.builderPreFill.context.priorities.join(', ')}\n`;
+            text += `- **Priorities**: ${response.builderPreFill.context.priorities.join(", ")}\n`;
         }
         if (response.builderPreFill.hints.techsToAvoid.length > 0) {
-            text += `- **Avoid**: ${response.builderPreFill.hints.techsToAvoid.join(', ')}\n`;
+            text += `- **Avoid**: ${response.builderPreFill.hints.techsToAvoid.join(", ")}\n`;
         }
         text += `\nVisit https://stacksfinder.com/builder to generate your migration blueprint.\n`;
     }
@@ -408,21 +430,24 @@ function formatMigrationRecommendation(response) {
  */
 export async function executeCreateAudit(input) {
     // Check Pro access
-    const tierCheck = await checkProAccess('create_audit');
+    const tierCheck = await checkProAccess("create_audit");
     if (tierCheck)
         return tierCheck;
-    debug('Creating audit', { name: input.name, techCount: input.technologies.length });
+    debug("Creating audit", {
+        name: input.name,
+        techCount: input.technologies.length,
+    });
     try {
-        const response = await apiRequest('/api/v1/audits', {
-            method: 'POST',
+        const response = await apiRequest("/api/v1/audits", {
+            method: "POST",
             body: {
                 name: input.name,
                 stackInput: {
-                    technologies: input.technologies
+                    technologies: input.technologies,
                 },
-                source: 'mcp'
+                source: "mcp",
             },
-            timeoutMs: 30000
+            timeoutMs: 30000,
         });
         const text = formatAuditReport(response);
         return { text };
@@ -431,7 +456,7 @@ export async function executeCreateAudit(input) {
         if (err instanceof McpError) {
             return { text: err.toResponseText(), isError: true };
         }
-        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : 'Failed to create audit');
+        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : "Failed to create audit");
         return { text: error.toResponseText(), isError: true };
     }
 }
@@ -440,10 +465,10 @@ export async function executeCreateAudit(input) {
  */
 export async function executeGetAudit(input) {
     // Check Pro access
-    const tierCheck = await checkProAccess('get_audit');
+    const tierCheck = await checkProAccess("get_audit");
     if (tierCheck)
         return tierCheck;
-    debug('Fetching audit', { auditId: input.auditId });
+    debug("Fetching audit", { auditId: input.auditId });
     try {
         const response = await apiRequest(`/api/v1/audits/${input.auditId}`);
         const text = formatAuditReport(response);
@@ -453,13 +478,13 @@ export async function executeGetAudit(input) {
         if (err instanceof McpError) {
             if (err.code === ErrorCode.NOT_FOUND) {
                 err.suggestions = [
-                    'Use list_audits to see your available audit reports.',
-                    'Create a new audit with create_audit.'
+                    "Use list_audits to see your available audit reports.",
+                    "Create a new audit with create_audit.",
                 ];
             }
             return { text: err.toResponseText(), isError: true };
         }
-        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : 'Failed to fetch audit');
+        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : "Failed to fetch audit");
         return { text: error.toResponseText(), isError: true };
     }
 }
@@ -468,22 +493,22 @@ export async function executeGetAudit(input) {
  */
 export async function executeListAudits(input) {
     // Check Pro access
-    const tierCheck = await checkProAccess('list_audits');
+    const tierCheck = await checkProAccess("list_audits");
     if (tierCheck)
         return tierCheck;
-    debug('Listing audits', { limit: input.limit, offset: input.offset });
+    debug("Listing audits", { limit: input.limit, offset: input.offset });
     try {
         const response = await apiRequest(`/api/v1/audits?limit=${input.limit}&offset=${input.offset}`);
         if (response.audits.length === 0) {
             return {
-                text: `## Your Audits\n\nNo audit reports found. Create one with the \`create_audit\` tool.`
+                text: `## Your Audits\n\nNo audit reports found. Create one with the \`create_audit\` tool.`,
             };
         }
         let text = `## Your Audits (${response.audits.length} of ${response.total})\n\n`;
         text += `| Name | Health Score | Status | Created |\n`;
         text += `|------|-------------|--------|--------|\n`;
         for (const audit of response.audits) {
-            const score = audit.summary?.healthScore ?? '-';
+            const score = audit.summary?.healthScore ?? "-";
             const date = new Date(audit.createdAt).toLocaleDateString();
             text += `| ${audit.name} | ${score}/100 | ${audit.status} | ${date} |\n`;
         }
@@ -496,7 +521,7 @@ export async function executeListAudits(input) {
         if (err instanceof McpError) {
             return { text: err.toResponseText(), isError: true };
         }
-        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : 'Failed to list audits');
+        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : "Failed to list audits");
         return { text: error.toResponseText(), isError: true };
     }
 }
@@ -505,17 +530,20 @@ export async function executeListAudits(input) {
  */
 export async function executeCompareAudits(input) {
     // Check Pro access
-    const tierCheck = await checkProAccess('compare_audits');
+    const tierCheck = await checkProAccess("compare_audits");
     if (tierCheck)
         return tierCheck;
-    debug('Comparing audits', { base: input.baseAuditId, compare: input.compareAuditId });
+    debug("Comparing audits", {
+        base: input.baseAuditId,
+        compare: input.compareAuditId,
+    });
     try {
-        const response = await apiRequest('/api/v1/audits/compare', {
-            method: 'POST',
+        const response = await apiRequest("/api/v1/audits/compare", {
+            method: "POST",
             body: {
                 baseAuditId: input.baseAuditId,
-                compareAuditId: input.compareAuditId
-            }
+                compareAuditId: input.compareAuditId,
+            },
         });
         const text = formatComparison(response.comparison);
         return { text };
@@ -524,7 +552,7 @@ export async function executeCompareAudits(input) {
         if (err instanceof McpError) {
             return { text: err.toResponseText(), isError: true };
         }
-        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : 'Failed to compare audits');
+        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : "Failed to compare audits");
         return { text: error.toResponseText(), isError: true };
     }
 }
@@ -533,12 +561,12 @@ export async function executeCompareAudits(input) {
  */
 export async function executeGetAuditQuota() {
     // Check Pro access
-    const tierCheck = await checkProAccess('get_audit_quota');
+    const tierCheck = await checkProAccess("get_audit_quota");
     if (tierCheck)
         return tierCheck;
-    debug('Getting audit quota');
+    debug("Getting audit quota");
     try {
-        const response = await apiRequest('/api/v1/audits/quota');
+        const response = await apiRequest("/api/v1/audits/quota");
         const { quota } = response;
         let text = `## Audit Quota\n\n`;
         text += `| Metric | Value |\n`;
@@ -555,7 +583,7 @@ export async function executeGetAuditQuota() {
         if (err instanceof McpError) {
             return { text: err.toResponseText(), isError: true };
         }
-        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : 'Failed to get audit quota');
+        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : "Failed to get audit quota");
         return { text: error.toResponseText(), isError: true };
     }
 }
@@ -564,10 +592,10 @@ export async function executeGetAuditQuota() {
  */
 export async function executeGetMigrationRecommendation(input) {
     // Check Pro access
-    const tierCheck = await checkProAccess('get_migration_recommendation');
+    const tierCheck = await checkProAccess("get_migration_recommendation");
     if (tierCheck)
         return tierCheck;
-    debug('Getting migration recommendation', { auditId: input.auditId });
+    debug("Getting migration recommendation", { auditId: input.auditId });
     try {
         const response = await apiRequest(`/api/v1/audits/${input.auditId}/migration`);
         const text = formatMigrationRecommendation(response);
@@ -577,14 +605,173 @@ export async function executeGetMigrationRecommendation(input) {
         if (err instanceof McpError) {
             if (err.code === ErrorCode.NOT_FOUND) {
                 err.suggestions = [
-                    'Use list_audits to see your available audit reports.',
-                    'Make sure the audit is completed before requesting migration analysis.',
-                    'Create a new audit with create_audit.'
+                    "Use list_audits to see your available audit reports.",
+                    "Make sure the audit is completed before requesting migration analysis.",
+                    "Create a new audit with create_audit.",
+                ];
+            }
+            return { text: err.toResponseText(), isError: true };
+        }
+        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error
+            ? err.message
+            : "Failed to get migration recommendation");
+        return { text: error.toResponseText(), isError: true };
+    }
+}
+// ============================================================================
+// BETTER-T-STACK IMPORT
+// ============================================================================
+/**
+ * Input schema for import_better_t_stack tool.
+ */
+export const ImportBetterTStackInputSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("github"),
+        url: z.string().url().describe("GitHub repository URL"),
+        name: z.string().min(1).max(200).optional().describe("Custom audit name"),
+    }),
+    z.object({
+        type: z.literal("package-json"),
+        content: z.string().min(2).max(500000).describe("Raw package.json content"),
+        name: z.string().min(1).max(200).optional().describe("Custom audit name"),
+    }),
+]);
+export const importBetterTStackToolDefinition = {
+    name: "import_better_t_stack",
+    description: `Import a Better-T-Stack project and create an audit.
+
+**Use case**: If a project was scaffolded with Better-T-Stack CLI, you can import it directly for a technical debt audit.
+
+**Input options**:
+1. GitHub URL - We'll fetch the package.json automatically
+2. Raw package.json content - Paste the file contents directly
+
+**What happens**:
+- Detects technologies from dependencies
+- Calculates a "BTS confidence score" (higher = more likely a Better-T-Stack project)
+- Creates and runs an audit automatically
+- Returns findings and health score
+
+**Tier**: Requires Pro or Team subscription (OR OAuth session)
+
+**Example (GitHub)**:
+\`\`\`json
+{
+  "type": "github",
+  "url": "https://github.com/username/my-bts-app",
+  "name": "My BTS App Audit"
+}
+\`\`\`
+
+**Example (package.json)**:
+\`\`\`json
+{
+  "type": "package-json",
+  "content": "{\"name\": \"my-app\", \"dependencies\": {...}}"
+}
+\`\`\`
+
+**Next Steps after import**:
+- Get migration plan: \`get_migration_recommendation({ auditId: "uuid" })\`
+- Compare with future audits: \`compare_audits({ baseAuditId, compareAuditId })\``,
+    inputSchema: {
+        type: "object",
+        oneOf: [
+            {
+                type: "object",
+                properties: {
+                    type: { type: "string", const: "github" },
+                    url: { type: "string", description: "GitHub repository URL" },
+                    name: { type: "string", description: "Custom audit name (optional)" },
+                },
+                required: ["type", "url"],
+            },
+            {
+                type: "object",
+                properties: {
+                    type: { type: "string", const: "package-json" },
+                    content: { type: "string", description: "Raw package.json content" },
+                    name: { type: "string", description: "Custom audit name (optional)" },
+                },
+                required: ["type", "content"],
+            },
+        ],
+    },
+};
+function formatImportResult(response) {
+    const { audit, import: imp } = response;
+    let text = `## Better-T-Stack Import Successful\n\n`;
+    // Import metadata
+    text += `### Project Analysis\n`;
+    text += `| Metric | Value |\n`;
+    text += `|--------|-------|\n`;
+    text += `| Project Name | ${imp.projectName} |\n`;
+    text += `| Import Source | ${imp.source} |\n`;
+    text += `| BTS Confidence | ${imp.confidence}% |\n`;
+    text += `| Technologies Detected | ${imp.technologiesDetected} |\n`;
+    if (imp.betterTStackVersion) {
+        text += `| Better-T-Stack Version | ${imp.betterTStackVersion} |\n`;
+    }
+    text += `\n`;
+    // Tech summary by category
+    const nonEmptyCategories = Object.entries(imp.techSummary).filter(([, techs]) => techs.length > 0);
+    if (nonEmptyCategories.length > 0) {
+        text += `### Detected Stack\n`;
+        for (const [category, techs] of nonEmptyCategories) {
+            text += `- **${category}**: ${techs.join(", ")}\n`;
+        }
+        text += `\n`;
+    }
+    // Warnings
+    if (imp.warnings.length > 0) {
+        text += `### Warnings\n`;
+        for (const warning of imp.warnings) {
+            text += `- [WARN] ${warning}\n`;
+        }
+        text += `\n`;
+    }
+    // Audit results
+    text += `---\n\n`;
+    text += formatAuditReport(audit);
+    return text;
+}
+/**
+ * Execute import_better_t_stack tool.
+ */
+export async function executeImportBetterTStack(input) {
+    // Check Pro access
+    const tierCheck = await checkProAccess("import_better_t_stack");
+    if (tierCheck)
+        return tierCheck;
+    debug("Importing Better-T-Stack project", {
+        type: input.type,
+        ...(input.type === "github"
+            ? { url: input.url }
+            : { contentLength: input.content.length }),
+    });
+    try {
+        const response = await apiRequest("/api/v1/audits/import/better-t-stack", {
+            method: "POST",
+            body: input,
+            timeoutMs: 30000,
+        });
+        const text = formatImportResult(response);
+        return { text };
+    }
+    catch (err) {
+        if (err instanceof McpError) {
+            if (err.code === ErrorCode.INVALID_INPUT) {
+                err.suggestions = [
+                    "For GitHub: Use format https://github.com/owner/repo",
+                    "For package.json: Make sure the content is valid JSON",
+                    "Check that the package.json has dependencies defined",
                 ];
             }
             return { text: err.toResponseText(), isError: true };
         }
-        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error ? err.message : 'Failed to get migration recommendation');
+        const error = new McpError(ErrorCode.API_ERROR, err instanceof Error
+            ? err.message
+            : "Failed to import Better-T-Stack project");
         return { text: error.toResponseText(), isError: true };
     }
 }