@aiready/mcp-server 0.6.0 → 0.6.2

package/src/resources/index.ts

@@ -0,0 +1,94 @@
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { StateStore } from '../state-store.js';
+
+export function registerResourceHandlers(server: any, stateStore: StateStore) {
+  // List available resources
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+      resources: [
+        {
+          uri: 'aiready://project/summary',
+          name: 'AIReady Project Summary',
+          description: 'Quick top-level AI-readiness summary.',
+          mimeType: 'text/markdown',
+        },
+        {
+          uri: 'aiready://project/issues',
+          name: 'AIReady Critical Issues',
+          description: 'List of top 10 critical readiness issues.',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'aiready://project/graph',
+          name: 'AIReady Codebase Graph',
+          description: 'Force-directed graph data for visualization.',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'aiready://project/roadmap',
+          name: 'AIReady Readiness Roadmap',
+          description: 'A prioritized plan to reach elite readiness.',
+          mimeType: 'text/markdown',
+        },
+      ],
+    };
+  });
+
+  // Read resource content
+  server.setRequestHandler(ReadResourceRequestSchema, async (request: any) => {
+    const { uri } = request.params;
+
+    if (uri === 'aiready://project/summary') {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'text/markdown',
+            text: stateStore.getSummaryMarkdown(),
+          },
+        ],
+      };
+    }
+
+    if (uri === 'aiready://project/issues') {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'application/json',
+            text: stateStore.getIssuesJson(),
+          },
+        ],
+      };
+    }
+
+    if (uri === 'aiready://project/graph') {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'application/json',
+            text: stateStore.getGraphJson(),
+          },
+        ],
+      };
+    }
+
+    if (uri === 'aiready://project/roadmap') {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'text/markdown',
+            text: stateStore.getRoadmapMarkdown(),
+          },
+        ],
+      };
+    }
+
+    throw new Error(`Resource not found: ${uri}`);
+  });
+}

package/src/state-store.ts

@@ -0,0 +1,111 @@
+import { UnifiedReport } from '@aiready/core';
+
+export class StateStore {
+  private lastResults: UnifiedReport | null = null;
+  private lastScanTimestamp: string | null = null;
+
+  updateLastResults(results: UnifiedReport) {
+    this.lastResults = results;
+    this.lastScanTimestamp = new Date().toISOString();
+  }
+
+  getLastResults(): UnifiedReport | null {
+    return this.lastResults;
+  }
+
+  getSummaryMarkdown(): string {
+    if (!this.lastResults) {
+      return '# AIReady Summary\n\nNo scan has been run yet. Run an AIReady scan tool to see results here.';
+    }
+
+    const { score, summary } = this.lastResults;
+    const grade = this.calculateGrade(score);
+
+    return `# AIReady Summary
+    
+Project Score: **${score}/100 (${grade})**
+Last Scan: ${this.lastScanTimestamp}
+
+## Issue Breakdown
+- Critical: ${summary.criticalIssues}
+- Major: ${summary.majorIssues}
+- Total Issues: ${summary.totalIssues}
+- Files Analyzed: ${summary.totalFiles}
+
+Run the \`aiready-mcp\` tool for a detailed analysis.`;
+  }
+
+  getIssuesJson(): string {
+    if (!this.lastResults) {
+      return JSON.stringify({
+        message: 'No issues found. Please run a scan first.',
+      });
+    }
+
+    // Return top 10 issues
+    const topIssues = this.lastResults.issues.slice(0, 10);
+    return JSON.stringify(topIssues, null, 2);
+  }
+
+  getGraphJson(): string {
+    if (!this.lastResults || !this.lastResults.metadata.graph) {
+      return JSON.stringify({
+        message:
+          'Graph data not available. Run a scan with graph analysis enabled.',
+      });
+    }
+    return JSON.stringify(this.lastResults.metadata.graph, null, 2);
+  }
+
+  getRoadmapMarkdown(): string {
+    if (!this.lastResults) {
+      return '# AIReady Roadmap\n\nNo scan has been run yet. Run an AIReady scan to generate a prioritized roadmap.';
+    }
+
+    const { score, issues } = this.lastResults;
+    const grade = this.calculateGrade(score);
+
+    let roadmap = `# AIReady Roadmap\n\n`;
+    roadmap += `Current Score: **${score}/100 (${grade})**\n\n`;
+
+    roadmap += `## Phase 1: High-Impact Fixes (Readiness Score 90+)\n`;
+    const criticalIssues = issues
+      .filter((i: any) => i.severity === 'critical')
+      .slice(0, 3);
+    if (criticalIssues.length > 0) {
+      criticalIssues.forEach((i: any) => {
+        roadmap += ` - [ ] **Fix ${i.type}** in \`${i.location.file}:L${i.location.line}\`: ${i.message}\n`;
+      });
+    } else {
+      roadmap += ` - ✅ All critical issues resolved!\n`;
+    }
+
+    roadmap += `\n## Phase 2: Structural Optimization (Efficiency)\n`;
+    const majorIssues = issues
+      .filter((i: any) => i.severity === 'major')
+      .slice(0, 3);
+    if (majorIssues.length > 0) {
+      majorIssues.forEach((i: any) => {
+        roadmap += ` - [ ] **Address ${i.type}**: ${i.message} (\`${i.location.file}\`)\n`;
+      });
+    } else {
+      roadmap += ` - ✅ All major structural issues resolved!\n`;
+    }
+
+    roadmap += `\n## Phase 3: Continuous AI Excellence\n`;
+    roadmap += ` - [ ] Implement \`mcp-server\` in CI/CD pipeline.\n`;
+    roadmap += ` - [ ] Achieve consistency score > 95 across all naming patterns.\n`;
+
+    return roadmap;
+  }
+
+  private calculateGrade(score: number): string {
+    if (score >= 90) return 'A';
+    if (score >= 80) return 'B';
+    if (score >= 70) return 'C';
+    if (score >= 60) return 'D';
+    return 'F';
+  }
+}
+
+export const stateStore = new StateStore();

package/src/tools/best-practices.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolve skills path: go up to src, then to package root, then to monorepo root, then into skills
+// Actually, it's easier to use a relative path if they are in the same monorepo
+const SKILLS_AGENTS_MD_PATH = path.resolve(
+  __dirname,
+  '../../skills/aiready-best-practices/AGENTS.md'
+);
+
+export const BestPracticesArgsSchema = z.object({
+  category: z
+    .string()
+    .describe(
+      'Category of best practices (e.g., patterns, context, consistency, signal, grounding)'
+    ),
+});
+
+export const ComplianceArgsSchema = z.object({
+  file_path: z.string().describe('Absolute path to the file to check'),
+});
+
+export async function handleGetBestPractices(
+  args: z.infer<typeof BestPracticesArgsSchema>
+) {
+  const { category } = args;
+
+  try {
+    const content = await fs.promises.readFile(SKILLS_AGENTS_MD_PATH, 'utf-8');
+
+    // Simple parsing to extract the relevant section based on ## <Number>. <Category>
+    // We'll search for the heading that starts with the number and contains the category name in parentheses
+    // e.g., "## 1. Pattern Detection (patterns)"
+    const lines = content.split('\n');
+    let inSection = false;
+    const sectionContent: string[] = [];
+
+    for (const line of lines) {
+      if (
+        line.startsWith('## ') &&
+        line.toLowerCase().includes(`(${category.toLowerCase()})`)
+      ) {
+        inSection = true;
+        sectionContent.push(line);
+        continue;
+      }
+
+      if (
+        inSection &&
+        line.startsWith('## ') &&
+        !line.toLowerCase().includes(`(${category.toLowerCase()})`)
+      ) {
+        break; // Next main section
+      }
+
+      if (inSection) {
+        sectionContent.push(line);
+      }
+    }
+
+    if (sectionContent.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Category "${category}" not found in AIReady Best Practices.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: sectionContent.join('\n') }],
+    };
+  } catch (error: any) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error reading best practices: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+export async function handleCheckCompliance(
+  args: z.infer<typeof ComplianceArgsSchema>
+) {
+  const { file_path } = args;
+
+  try {
+    const content = await fs.promises.readFile(file_path, 'utf-8');
+    const issues: string[] = [];
+
+    // Lightweight checks based on AGENTS.md rules
+
+    // 1. File Length (>500 lines)
+    const lineCount = content.split('\n').length;
+    if (lineCount > 500) {
+      issues.push(
+        `⚠️ **Context Optimization (2.3)**: File has ${lineCount} lines. Large files waste context. Consider splitting into smaller modules.`
+      );
+    }
+
+    // 2. Boolean Trap Parameters
+    if (
+      content.includes('true, false') ||
+      content.includes('false, true') ||
+      content.includes('true, true')
+    ) {
+      issues.push(
+        `🚩 **AI Signal Clarity (4.1)**: Detected potential positional boolean traps. Prefer named options objects for clarity.`
+      );
+    }
+
+    // 3. Magic Literals
+    const magicNumberRegex = /[^A-Z_a-z][0-9]{2,}[^A-Z_a-z0-9]/g;
+    if (magicNumberRegex.test(content)) {
+      issues.push(
+        `🚩 **AI Signal Clarity (4.3)**: Detected potential magic literals (raw numbers). Use named constants/enums for business rules.`
+      );
+    }
+
+    // 4. Entropy
+    const entropyRegex = /\b(data|info|handle|obj|item)\b/gi;
+    const matches = content.match(entropyRegex);
+    if (matches && matches.length > 5) {
+      issues.push(
+        `🚩 **AI Signal Clarity (4.2)**: High-entropy names detected (${[...new Set(matches.map((m) => m.toLowerCase()))].join(', ')}). Use specific domain names instead.`
+      );
+    }
+
+    if (issues.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `✅ File "${path.basename(file_path)}" is compliant with lightweight AIReady Best Practices.`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `AIReady Compliance Report for "${path.basename(file_path)}":\n\n${issues.join('\n')}`,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      content: [
+        { type: 'text', text: `Error checking compliance: ${error.message}` },
+      ],
+      isError: true,
+    };
+  }
+}

package/src/tools/context-budget.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import fs from 'fs';
+import path from 'path';
+
+export const ContextBudgetArgsSchema = z.object({
+  file_path: z.string().describe('Absolute path to the file to analyze'),
+});
+
+export interface TokenEstimation {
+  tokens: number;
+  budgetPercentage: number;
+  tier: string;
+}
+
+export async function handleAnalyzeContextBudget(
+  args: z.infer<typeof ContextBudgetArgsSchema>
+) {
+  const { file_path } = args;
+
+  try {
+    const content = await fs.promises.readFile(file_path, 'utf-8');
+
+    // Token estimation (approx 4 chars/token)
+    const charCount = content.length;
+    const tokens = Math.ceil(charCount / 4);
+
+    // Tiers according to common context windows
+    const tiers = [
+      { name: '8k (GPT-4/Turbo)', threshold: 8000 },
+      { name: '32k (GPT-4o/Mini)', threshold: 32000 },
+      { name: '128k (GPT-4o/Claude 3)', threshold: 128000 },
+      { name: '200k (Claude 3.5 Sonnet)', threshold: 200000 },
+      { name: '1M (Gemini 1.5 Pro)', threshold: 1000000 },
+    ];
+
+    let result = `# Context Budget for "${path.basename(file_path)}"\n\n`;
+    result += `**Estimated Tokens:** ${tokens.toLocaleString()}\n\n`;
+
+    result += `### Context Usage By Tier\n`;
+    tiers.forEach((tier) => {
+      const percentage = (tokens / tier.threshold) * 100;
+      const barLength = Math.min(Math.ceil(percentage / 5), 20);
+      const bar =
+        '█'.repeat(barLength) + '░'.repeat(Math.max(0, 20 - barLength));
+      result += ` - **${tier.name}:** ${bar} ${percentage.toFixed(1)}%\n`;
+    });
+
+    result += `\n### Recommendations\n`;
+
+    if (tokens > 5000) {
+      result += `⚠️ **High Context Usage:** This file alone takes up a significant chunk of smaller context windows. Consider refactoring to extract logical sub-modules.\n`;
+    } else {
+      result += `✅ **Optimal Size:** This file is well-sized for AI context windows.\n`;
+    }
+
+    // Check for large imports
+    const importCount = (content.match(/^import /gm) || []).length;
+    if (importCount > 20) {
+      result += `⚠️ **High Dependency Load:** ${importCount} imports found. AI will need to load many dependent files, multiplying the context budget needed. Use barrel exports (index.ts) to flatten the dependency tree.\n`;
+    }
+
+    return {
+      content: [{ type: 'text', text: result }],
+    };
+  } catch (error: any) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error analyzing context budget: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+import { ToolRegistry, ToolName } from '@aiready/core';
+import {
+  handleGetBestPractices,
+  handleCheckCompliance,
+  BestPracticesArgsSchema,
+  ComplianceArgsSchema,
+} from './best-practices.js';
+import {
+  handleAnalyzeContextBudget,
+  ContextBudgetArgsSchema,
+} from './context-budget.js';
+
+/**
+ * Zod schemas for tool arguments
+ */
+export const AnalysisArgsSchema = z.object({
+  path: z.string().describe('Path to the directory to analyze'),
+  summary_only: z
+    .boolean()
+    .optional()
+    .describe(
+      'If true, returns only the summary and skips the detailed issue list. Best for large projects to save context.'
+    ),
+});
+
+export const RemediationArgsSchema = z.object({
+  issue_id: z.string().describe('The unique ID of the issue to fix'),
+  file_path: z.string().describe('The path to the file containing the issue'),
+  context: z.string().describe('The content of the file or surrounding code'),
+});
+
+export {
+  BestPracticesArgsSchema,
+  ComplianceArgsSchema,
+  ContextBudgetArgsSchema,
+};
+
+/**
+ * Mapping between tool names and @aiready/ package names.
+ * Used for dynamic registration on-demand to minimize initial context budget.
+ */
+export const TOOL_PACKAGE_MAP: Record<string, string> = {
+  [ToolName.PatternDetect]: '@aiready/pattern-detect',
+  [ToolName.ContextAnalyzer]: '@aiready/context-analyzer',
+  [ToolName.NamingConsistency]: '@aiready/consistency',
+  [ToolName.AiSignalClarity]: '@aiready/ai-signal-clarity',
+  [ToolName.AgentGrounding]: '@aiready/agent-grounding',
+  [ToolName.TestabilityIndex]: '@aiready/testability',
+  [ToolName.DocDrift]: '@aiready/doc-drift',
+  [ToolName.DependencyHealth]: '@aiready/deps',
+  [ToolName.ChangeAmplification]: '@aiready/change-amplification',
+  [ToolName.ContractEnforcement]: '@aiready/contract-enforcement',
+  // New tools from core
+  [ToolName.CognitiveLoad]: '@aiready/cognitive-load',
+  [ToolName.PatternEntropy]: '@aiready/pattern-entropy',
+  [ToolName.ConceptCohesion]: '@aiready/concept-cohesion',
+  [ToolName.SemanticDistance]: '@aiready/semantic-distance',
+  // Aliases
+  patterns: '@aiready/pattern-detect',
+  duplicates: '@aiready/pattern-detect',
+  context: '@aiready/context-analyzer',
+  fragmentation: '@aiready/context-analyzer',
+  consistency: '@aiready/consistency',
+  'ai-signal': '@aiready/ai-signal-clarity',
+  grounding: '@aiready/agent-grounding',
+  testability: '@aiready/testability',
+  'deps-health': '@aiready/deps',
+  'change-amp': '@aiready/change-amplification',
+  'contract-enforce': '@aiready/contract-enforcement',
+};
+
+/**
+ * List of tools to advertise to the client
+ */
+export const ADVERTISED_TOOLS = [
+  ToolName.PatternDetect,
+  ToolName.ContextAnalyzer,
+  ToolName.NamingConsistency,
+  ToolName.AiSignalClarity,
+  ToolName.AgentGrounding,
+  ToolName.TestabilityIndex,
+  ToolName.DocDrift,
+  ToolName.DependencyHealth,
+  ToolName.ChangeAmplification,
+  ToolName.ContractEnforcement,
+  ToolName.CognitiveLoad,
+  ToolName.PatternEntropy,
+  ToolName.ConceptCohesion,
+  ToolName.SemanticDistance,
+  'get_best_practices',
+  'check_best_practice_compliance',
+  'analyze_context_budget',
+];
+
+export {
+  handleGetBestPractices,
+  handleCheckCompliance,
+  handleAnalyzeContextBudget,
+};
+
+export async function handleAnalysis(
+  name: string,
+  args: any,
+  stateStore?: any
+) {
+  const parsedArgs = AnalysisArgsSchema.safeParse(args);
+  if (!parsedArgs.success) {
+    throw new Error(
+      `Invalid arguments for ${name}: ${parsedArgs.error.message}`
+    );
+  }
+  const { path: rootDir, summary_only } = parsedArgs.data;
+
+  let provider = ToolRegistry.find(name);
+
+  // Dynamic loading if not already registered
+  if (!provider) {
+    const packageName =
+      TOOL_PACKAGE_MAP[name] ??
+      (name.startsWith('@aiready/') ? name : `@aiready/${name}`);
+
+    try {
+      console.error(
+        `[MCP] Dynamically loading ${packageName} for tool ${name}`
+      );
+      await import(packageName);
+      provider = ToolRegistry.find(name);
+    } catch (importError: unknown) {
+      const importErrorMessage =
+        importError instanceof Error
+          ? importError.message
+          : String(importError);
+      const error = new Error(
+        `Tool ${name} not found and failed to load package ${packageName}: ${importErrorMessage}`
+      );
+      (error as any).cause = importError;
+      throw error;
+    }
+  }
+
+  if (!provider) {
+    throw new Error(`Tool ${name} not found after attempting to load`);
+  }
+
+  console.error(
+    `[MCP] Executing ${name} on ${rootDir}${summary_only ? ' (summary only)' : ''}`
+  );
+
+  const results = await provider.analyze({
+    rootDir,
+  });
+
+  // Update state store if provided
+  if (stateStore) {
+    stateStore.updateLastResults(results);
+  }
+
+  // Format results for the agent
+  if (summary_only) {
+    const summary = results.summary;
+    return {
+      summary: `## Issue Breakdown
+- Critical: ${summary.criticalIssues}
+- Major: ${summary.majorIssues}
+- Total Issues: ${summary.totalIssues}
+- Files Analyzed: ${summary.totalFiles}`,
+      metadata: results.metadata,
+      notice:
+        'Detailed issues were omitted (summary_only: true). Run without summary_only for full details.',
+    };
+  }
+
+  return results;
+}
+
+export async function handleRemediation(
+  args: z.infer<typeof RemediationArgsSchema>
+) {
+  const apiKey = process.env.AIREADY_API_KEY;
+  const serverUrl =
+    process.env.AIREADY_PLATFORM_URL || 'https://platform.getaiready.dev';
+
+  if (!apiKey) {
+    throw new Error(
+      'AIREADY_API_KEY is not set. Remediation requires an active subscription.'
+    );
+  }
+
+  console.error(`[MCP] Requesting remediation for ${args.issue_id}...`);
+
+  try {
+    const response = await fetch(`${serverUrl}/api/v1/remediate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-KEY': apiKey,
+      },
+      body: JSON.stringify({
+        issueId: args.issue_id,
+        filePath: args.file_path,
+        context: args.context,
+        agent: 'mcp-server',
+      }),
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new Error(
+        `Platform Error: ${errorData.message || response.statusText}`
+      );
+    }
+
+    const data = await response.json();
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Recommended Fix (Diff):\n\n${data.diff}\n\nRationale:\n${data.rationale}`,
+        },
+      ],
+    };
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Failed to get remediation: ${errorMessage}. Please visit the dashboard to fix manually.`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}

package/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "src",
+    "ignoreDeprecations": "6.0"
   },
   "include": ["src/**/*"]
 }