@aiready/mcp-server 0.6.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/mcp-server",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "The AIReady Model Context Protocol (MCP) Server for Agentic Readiness. Optimize codebases for AI agents like Cursor, Windsurf, and Claude directly via MCP.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,26 +10,26 @@
     "mcp-server": "./dist/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "chalk": "^5.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.6.2",
     "zod": "^4.3.6",
-    "@aiready/agent-grounding": "0.14.16",
-    "@aiready/ai-signal-clarity": "0.14.18",
-    "@aiready/change-amplification": "0.14.16",
-    "@aiready/consistency": "0.21.16",
-    "@aiready/context-analyzer": "0.22.16",
-    "@aiready/core": "0.24.19",
-    "@aiready/deps": "0.14.16",
-    "@aiready/doc-drift": "0.14.16",
-    "@aiready/pattern-detect": "0.17.16",
+    "@aiready/agent-grounding": "0.14.17",
+    "@aiready/ai-signal-clarity": "0.14.19",
+    "@aiready/change-amplification": "0.14.17",
+    "@aiready/consistency": "0.21.17",
+    "@aiready/core": "0.24.20",
+    "@aiready/doc-drift": "0.14.17",
+    "@aiready/deps": "0.14.17",
+    "@aiready/context-analyzer": "0.22.17",
+    "@aiready/pattern-detect": "0.17.17",
     "@aiready/testability": "0.7.17"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
-    "esbuild": "^0.27.3",
-    "tsup": "^8.3.5",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.0"
+    "@types/node": "^24.12.2",
+    "esbuild": "^0.27.7",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
   },
   "keywords": [
     "aiready",
@@ -57,6 +57,7 @@
     "type-check": "tsc --noEmit",
     "format-check": "prettier --check . --ignore-path ../../.prettierignore",
     "format": "prettier --write . --ignore-path ../../.prettierignore",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "test:coverage": "vitest run --coverage"
   }
 }

package/src/__tests__/schema-sync.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ToolName } from '@aiready/core';
+import {
+  ADVERTISED_TOOLS,
+  TOOL_PACKAGE_MAP,
+  handleAnalysis,
+} from '../tools/index.js';
+
+describe('MCP Schema Sync Validation', () => {
+  it('every advertised tool should have a package mapping or a custom handler', () => {
+    // 1. Spoke tools that use handleAnalysis
+    const spokeTools = ADVERTISED_TOOLS.filter(
+      (t) =>
+        ![
+          'get_best_practices',
+          'check_best_practice_compliance',
+          'analyze_context_budget',
+        ].includes(t)
+    );
+
+    for (const tool of spokeTools) {
+      expect(
+        TOOL_PACKAGE_MAP[tool],
+        `Tool "${tool}" is missing a mapping in TOOL_PACKAGE_MAP`
+      ).toBeDefined();
+    }
+  });
+
+  it('every package in TOOL_PACKAGE_MAP should be a valid @aiready package name', () => {
+    for (const [tool, pkg] of Object.entries(TOOL_PACKAGE_MAP)) {
+      expect(
+        pkg.startsWith('@aiready/'),
+        `Mapping for "${tool}" -> "${pkg}" must use a scoped @aiready package`
+      ).toBe(true);
+    }
+  });
+
+  it('handleAnalysis should correctly resolve and attempt to load packages from the map', async () => {
+    // Mock the dynamic import to verify it's called with the correct package
+    const importMock = vi.fn().mockRejectedValue(new Error('Stop here'));
+    vi.stubGlobal('import', importMock);
+
+    // Testing dynamic loading path
+    const toolName = ToolName.PatternDetect;
+    const expectedPackage = TOOL_PACKAGE_MAP[toolName];
+
+    try {
+      await handleAnalysis(toolName, { path: './test' });
+    } catch (e: any) {
+      // We expect it to fail at the import stage because of our mock
+      expect(e.message).toContain(`failed to load package ${expectedPackage}`);
+    }
+  });
+});

package/src/__tests__/server.test.ts

@@ -142,7 +142,34 @@ describe('AIReady MCP Server Integration', () => {
     });
     expect(result.contents).toBeDefined();
     expect(result.contents[0].uri).toBe('aiready://project/summary');
-    expect(result.contents[0].text).toContain('# AIReady Summary');
+    expect((result.contents[0] as any).text).toContain('# AIReady Summary');
+  });
+
+  it('should execute get_best_practices', async () => {
+    const result = await client.callTool({
+      name: 'get_best_practices',
+      arguments: { category: 'patterns' },
+    });
+    const typedResult = result as ToolCallResponse;
+    expect(typedResult.content[0].text).toContain('Pattern Detection');
+  });
+
+  it('should execute check_best_practice_compliance', async () => {
+    const result = await client.callTool({
+      name: 'check_best_practice_compliance',
+      arguments: { file_path: path.resolve(__dirname, '../index.ts') },
+    });
+    const typedResult = result as ToolCallResponse;
+    expect(typedResult.content[0].text).toContain('is compliant');
+  });
+
+  it('should execute analyze_context_budget', async () => {
+    const result = await client.callTool({
+      name: 'analyze_context_budget',
+      arguments: { file_path: path.resolve(__dirname, '../index.ts') },
+    });
+    const typedResult = result as ToolCallResponse;
+    expect(typedResult.content[0].text).toContain('Context Budget');
   });
 
   it('should list available prompts', async () => {

package/src/index.ts

@@ -3,68 +3,29 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import { ToolRegistry, ToolName } from '@aiready/core';
-import { z } from 'zod';
-
-/**
- * Zod schemas for tool arguments
- */
-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.'
-    ),
-});
-
-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'),
-});
-
-/**
- * Mapping between tool names and @aiready/ package names.
- * Used for dynamic registration on-demand to minimize initial context budget.
- */
-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',
-  // 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',
-};
+import {
+  handleAnalysis,
+  handleRemediation,
+  ADVERTISED_TOOLS,
+  RemediationArgsSchema,
+  BestPracticesArgsSchema,
+  handleGetBestPractices,
+  ComplianceArgsSchema,
+  handleCheckCompliance,
+  ContextBudgetArgsSchema,
+  handleAnalyzeContextBudget,
+} from './tools/index.js';
+import { registerResourceHandlers } from './resources/index.js';
+import { registerPromptHandlers } from './prompts/index.js';
+import { stateStore } from './state-store.js';
 
 /**
  * AIReady MCP Server Implementation
  */
 export class AIReadyMcpServer {
   private server: Server;
-  private version: string = '0.2.10';
+  private version: string = '0.3.0';
 
   constructor() {
     this.server = new Server(
@@ -88,221 +49,17 @@ export class AIReadyMcpServer {
     };
   }
 
-  private async 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,
-      };
-    }
-  }
-
   private setupHandlers() {
-    // List available resources
-    this.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',
-          },
-        ],
-      };
-    });
+    // Register Resource Handlers
+    registerResourceHandlers(this.server, stateStore);
 
-    // Read resource content
-    this.server.setRequestHandler(
-      ReadResourceRequestSchema,
-      async (request) => {
-        const { uri } = request.params;
-
-        if (uri === 'aiready://project/summary') {
-          return {
-            contents: [
-              {
-                uri,
-                mimeType: 'text/markdown',
-                text: '# AIReady Summary\n\nProject: Current Directory\nScore: 84/100 (B)\n\nCritical Issues: 2\nMajor Issues: 14\n\nRun the `aiready-mcp` tool for full analysis.',
-              },
-            ],
-          };
-        }
-
-        if (
-          uri === 'aiready://project/issues' ||
-          uri === 'aiready://project/graph'
-        ) {
-          return {
-            contents: [
-              {
-                uri,
-                mimeType: 'application/json',
-                text: JSON.stringify({
-                  message: 'Resource content coming from latest scan...',
-                }),
-              },
-            ],
-          };
-        }
-
-        throw new Error(`Resource not found: ${uri}`);
-      }
-    );
-
-    // List available prompts
-    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
-      return {
-        prompts: [
-          {
-            name: 'analyze-project',
-            description:
-              'Audit the project for AI-readiness and suggest improvements.',
-            arguments: [
-              {
-                name: 'path',
-                description: 'Path/directory to analyze',
-                required: true,
-              },
-            ],
-          },
-          {
-            name: 'remediate-issue',
-            description: 'Help the user fix a specific AIReady issue.',
-            arguments: [
-              {
-                name: 'issueId',
-                description: 'The unique ID of the issue to fix',
-                required: true,
-              },
-            ],
-          },
-        ],
-      };
-    });
-
-    // Get prompt content
-    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const { name, arguments: args } = request.params;
-
-      if (name === 'analyze-project') {
-        const path = args?.path || '.';
-        return {
-          description: 'Project audit instructions',
-          messages: [
-            {
-              role: 'user',
-              content: {
-                type: 'text',
-                text: `I want to audit the project at "${path}" for AI-readiness. Please use the AIReady tools to identify duplication patterns, context fragmentation, and naming inconsistencies. Then, provide a prioritized list of improvements to help me leverage AI agents more effectively.`,
-              },
-            },
-          ],
-        };
-      }
-
-      if (name === 'remediate-issue') {
-        const issueId = args?.issueId;
-        return {
-          description: 'Issue remediation instructions',
-          messages: [
-            {
-              role: 'user',
-              content: {
-                type: 'text',
-                text: `I've identified an AIReady issue with ID: ${issueId}. Please use the \`get_remediation_diff\` tool to find a fix, explain the rationale behind the recommended change, and then help me apply it to the codebase.`,
-              },
-            },
-          ],
-        };
-      }
-
-      throw new Error(`Prompt not found: ${name}`);
-    });
+    // Register Prompt Handlers
+    registerPromptHandlers(this.server);
 
     // List available tools
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      // Define canonical tool names to advertise to the client
-      // These will be dynamically loaded on demand
-      const toolsToAdvertise = [
-        ToolName.PatternDetect,
-        ToolName.ContextAnalyzer,
-        ToolName.NamingConsistency,
-        ToolName.AiSignalClarity,
-        ToolName.AgentGrounding,
-        ToolName.TestabilityIndex,
-        ToolName.DocDrift,
-        ToolName.DependencyHealth,
-        ToolName.ChangeAmplification,
-        ToolName.ContractEnforcement,
-      ];
-
       const tools: any[] = [
-        ...toolsToAdvertise.map((id) => ({
+        ...ADVERTISED_TOOLS.map((id) => ({
           name: id,
           description: `Scan the directory for ${id} issues to improve AI-readiness.`,
           inputSchema: {
@@ -355,82 +112,32 @@ export class AIReadyMcpServer {
 
       try {
         if (name === 'get_remediation_diff') {
-          const parsedArgs = RemediationArgsSchema.safeParse(args);
-          if (!parsedArgs.success) {
-            throw new Error(
-              `Invalid arguments for ${name}: ${parsedArgs.error.message}`
-            );
-          }
-          return await this.handleRemediation(parsedArgs.data);
+          const parsedArgs = RemediationArgsSchema.parse(args);
+          return await handleRemediation(parsedArgs);
         }
 
-        const parsedArgs = AnalysisArgsSchema.safeParse(args);
-        if (!parsedArgs.success) {
-          throw new Error(
-            `Invalid arguments for ${name}: ${parsedArgs.error.message}`
-          );
+        if (name === 'get_best_practices') {
+          const parsedArgs = BestPracticesArgsSchema.parse(args);
+          return await handleGetBestPractices(parsedArgs);
         }
-        const { path: rootDir, summary_only } = parsedArgs.data;
 
-        let provider = ToolRegistry.find(name);
-
-        // Dynamic loading if not already registered (CLI pattern)
-        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);
-            console.error(
-              `[MCP] Failed to load tool package ${packageName}: ${importErrorMessage}`
-            );
-            const error = new Error(
-              `Tool ${name} not found and failed to load package ${packageName}: ${importErrorMessage}`
-            );
-            (error as { cause?: unknown }).cause = importError;
-            throw error;
-          }
+        if (name === 'check_best_practice_compliance') {
+          const parsedArgs = ComplianceArgsSchema.parse(args);
+          return await handleCheckCompliance(parsedArgs);
         }
 
-        if (!provider) {
-          throw new Error(`Tool ${name} not found after attempting to load`);
+        if (name === 'analyze_context_budget') {
+          const parsedArgs = ContextBudgetArgsSchema.parse(args);
+          return await handleAnalyzeContextBudget(parsedArgs);
         }
 
-        console.error(
-          `[MCP] Executing ${name} on ${rootDir}${
-            summary_only ? ' (summary only)' : ''
-          }`
-        );
-
-        const results = await provider.analyze({
-          rootDir,
-        });
-
-        // Format results for the agent
-        const responseData = summary_only
-          ? {
-              summary: results.summary,
-              metadata: results.metadata,
-              notice:
-                'Detailed issues were omitted (summary_only: true). Run without summary_only for full details.',
-            }
-          : results;
+        const results = await handleAnalysis(name, args, stateStore);
 
         return {
           content: [
             {
               type: 'text',
-              text: JSON.stringify(responseData, null, 2),
+              text: JSON.stringify(results, null, 2),
             },
           ],
         };

package/src/prompts/index.ts

@@ -0,0 +1,76 @@
+import {
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+export function registerPromptHandlers(server: any) {
+  // List available prompts
+  server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+      prompts: [
+        {
+          name: 'analyze-project',
+          description:
+            'Audit the project for AI-readiness and suggest improvements.',
+          arguments: [
+            {
+              name: 'path',
+              description: 'Path/directory to analyze',
+              required: true,
+            },
+          ],
+        },
+        {
+          name: 'remediate-issue',
+          description: 'Help the user fix a specific AIReady issue.',
+          arguments: [
+            {
+              name: 'issueId',
+              description: 'The unique ID of the issue to fix',
+              required: true,
+            },
+          ],
+        },
+      ],
+    };
+  });
+
+  // Get prompt content
+  server.setRequestHandler(GetPromptRequestSchema, async (request: any) => {
+    const { name, arguments: args } = request.params;
+
+    if (name === 'analyze-project') {
+      const path = args?.path || '.';
+      return {
+        description: 'Project audit instructions',
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `I want to audit the project at "${path}" for AI-readiness. Please use the AIReady tools to identify duplication patterns, context fragmentation, and naming inconsistencies. Then, provide a prioritized list of improvements to help me leverage AI agents more effectively.`,
+            },
+          },
+        ],
+      };
+    }
+
+    if (name === 'remediate-issue') {
+      const issueId = args?.issueId;
+      return {
+        description: 'Issue remediation instructions',
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `I've identified an AIReady issue with ID: ${issueId}. Please use the \`get_remediation_diff\` tool to find a fix, explain the rationale behind the recommended change, and then help me apply it to the codebase.`,
+            },
+          },
+        ],
+      };
+    }
+
+    throw new Error(`Prompt not found: ${name}`);
+  });
+}