@aiready/mcp-server 0.5.2 → 0.6.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/mcp-server@0.3.0 build /Users/pengcao/projects/aiready/packages/mcp-server
+> @aiready/mcp-server@0.6.0 build /Users/pengcao/projects/aiready/packages/mcp-server
 > tsup src/index.ts --format esm --clean --dts
 
 CLI Building entry: src/index.ts
@@ -10,8 +10,8 @@
 CLI Target: node20
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 8.93 KB
-ESM ⚡️ Build success in 42ms
+ESM dist/index.js 13.17 KB
+ESM ⚡️ Build success in 20ms
 DTS Build start
-DTS ⚡️ Build success in 4156ms
+DTS ⚡️ Build success in 1369ms
 DTS dist/index.d.ts 482.00 B

package/.turbo/turbo-format-check.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/mcp-server@0.5.1 format-check /Users/pengcao/projects/aiready/packages/mcp-server
+> @aiready/mcp-server@0.5.3 format-check /Users/pengcao/projects/aiready/packages/mcp-server
 > prettier --check . --ignore-path ../../.prettierignore
 
 Checking formatting...

package/.turbo/turbo-lint.log

@@ -1,5 +1,5 @@
 
 
-> @aiready/mcp-server@0.5.1 lint /Users/pengcao/projects/aiready/packages/mcp-server
+> @aiready/mcp-server@0.5.3 lint /Users/pengcao/projects/aiready/packages/mcp-server
 > eslint src
 

package/.turbo/turbo-test.log

@@ -1,20 +1,68 @@
-
-> @aiready/mcp-server@0.2.10 test /Users/pengcao/projects/aiready/packages/mcp-server
-> vitest run
-
-
- RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/mcp-server
-
-AIReady MCP Server started
-[MCP] Dynamically loading @aiready/pattern-detect for tool pattern-detect
-[MCP] Executing pattern-detect on /Users/pengcao/projects/aiready/packages/core
-[MCP] Dynamically loading @aiready/non-existent-tool for tool non-existent-tool
-[MCP] Failed to load tool package @aiready/non-existent-tool: Cannot find package '@aiready/non-existent-tool' imported from /Users/pengcao/projects/aiready/packages/mcp-server/dist/index.js
- ✓ src/__tests__/server.test.ts (5 tests) 1147ms
-     ✓ should execute pattern-detect and return results  783ms
-
- Test Files  1 passed (1)
-      Tests  5 passed (5)
-   Start at  14:45:23
-   Duration  1.44s (transform 45ms, setup 0ms, import 89ms, tests 1.15s, environment 0ms)
-
+
+
+> @aiready/mcp-server@0.5.3 test /Users/pengcao/projects/aiready/packages/mcp-server
+> vitest run
+
+[?25l
+ RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/mcp-server
+
+[?2026h
+ ❯ src/__tests__/server.test.ts [queued]
+
+ Test Files 0 passed (1)
+      Tests 0 passed (0)
+   Start at 09:53:14
+   Duration 101ms
+[?2026l[?2026hAIReady MCP Server started
+[MCP] Dynamically loading @aiready/pattern-detect for tool pattern-detect
+[MCP] Executing pattern-detect on /Users/pengcao/projects/aiready/packages/core (summary only)
+
+ ❯ src/__tests__/server.test.ts 1/10
+
+ Test Files 0 passed (1)
+      Tests 1 passed (10)
+   Start at 09:53:14
+   Duration 709ms
+[?2026l[?2026h
+ ❯ src/__tests__/server.test.ts 2/10
+
+ Test Files 0 passed (1)
+      Tests 2 passed (10)
+   Start at 09:53:14
+   Duration 915ms
+[?2026l[?2026h
+ ❯ src/__tests__/server.test.ts 3/10
+
+ Test Files 0 passed (1)
+      Tests 3 passed (10)
+   Start at 09:53:14
+   Duration 1.22s
+[?2026l[?2026h[MCP] Executing pattern-detect on /Users/pengcao/projects/aiready/packages/core
+
+ ❯ src/__tests__/server.test.ts 4/10
+
+ Test Files 0 passed (1)
+      Tests 4 passed (10)
+   Start at 09:53:14
+   Duration 1.63s
+[?2026l[MCP] Dynamically loading @aiready/non-existent-tool for tool non-existent-tool
+[MCP] Failed to load tool package @aiready/non-existent-tool: Cannot find package '@aiready/non-existent-tool' imported from /Users/pengcao/projects/aiready/packages/mcp-server/dist/index.js
+ ✓ src/__tests__/server.test.ts (10 tests) 1476ms
+   ✓ AIReady MCP Server Integration (10)
+     ✓ should list available tools 4ms
+     ✓ should expose correct input schema for tools including summary_only 3ms
+     ✓ should execute pattern-detect with summary_only: true and return only summary  590ms
+     ✓ should execute pattern-detect and return results  424ms
+     ✓ should return error for unknown tool 4ms
+     ✓ should return error for missing arguments 2ms
+     ✓ should list available resources 2ms
+     ✓ should read resource content 1ms
+     ✓ should list available prompts 1ms
+     ✓ should get prompt content 1ms
+
+ Test Files  1 passed (1)
+      Tests  10 passed (10)
+   Start at  09:53:14
+   Duration  1.72s (transform 63ms, setup 0ms, import 87ms, tests 1.48s, environment 0ms)
+
+[?25h

package/.turbo/turbo-type-check.log

@@ -1,5 +1,5 @@
 
 
-> @aiready/mcp-server@0.5.1 type-check /Users/pengcao/projects/aiready/packages/mcp-server
+> @aiready/mcp-server@0.5.3 type-check /Users/pengcao/projects/aiready/packages/mcp-server
 > tsc --noEmit
 

package/README.md

@@ -2,64 +2,70 @@
 
 The AIReady MCP Server provides an integration point for AI agents (like Claude Desktop, Cursor, Windsurf, etc.) to assess AI-readiness and improve AI leverage directly within their conversational interfaces using the Model Context Protocol (MCP).
 
-## Installation & Distribution Channels
+## 🛠 Capabilities
 
-You can install and use the AIReady MCP server through several supported channels.
+The AIReady MCP server exposes the following capabilities:
 
-### 1. Dedicated MCP Registries
+### 1. Analysis Tools
+
+- **Scan Tools**: Run localized scans for `pattern-detect`, `context-analyzer`, `consistency`, `ai-signal-clarity`, `agent-grounding`, `testability`, `doc-drift`, `deps-health`, `change-amp`, and `contract-enforce`.
+- **`get_remediation_diff`**: Get a precise code diff to fix identified AI-readiness issues.
+
+### 2. Resources (Contextual Data)
+
+- **`aiready://project/summary`**: A high-level overview of the project's AI-readiness score and issue count.
+- **`aiready://project/issues`**: A JSON list of the top 10 most critical issues found in the latest scan.
+- **`aiready://project/graph`**: Raw dependency and fragmentation graph data for visualization.
+
+### 3. Prompts (Templates)
+
+- **`analyze-project`**: A guided prompt to perform a full AI-readiness audit.
+- **`remediate-issue`**: A template for fixing a specific issue using its ID.
+
+---
 
-- **[Smithery](https://smithery.ai)**: Discover and install our server directly via the Smithery CLI:
-  ```bash
-  npx @smithery/cli install @aiready/mcp-server
-  ```
-- **[Glama](https://glama.ai/mcp)**: View our listing and integration options on the Glama directory.
-- **[Pulsar](https://gotopulsar.com)**: Find us on the Pulsar registry for MCP servers.
+## 🧱 Extension: AST Explorer Sibling
 
-### 2. Direct IDE / Assistant Integrations
+For deep code exploration, we also provide the **@aiready/ast-mcp-server**, which provides:
 
-#### Claude Desktop App
+- Symbol resolution (`resolve_definition`)
+- Reference finding (`find_references`)
+- Call hierarchy (`get_call_hierarchy`)
+- Implementation lookup (`find_implementations`)
 
-To use the AIReady MCP server in the Claude Desktop app, add the following configuration to your `claude_desktop_config.json`:
+Configure it alongside AIReady:
 
 ```json
 "mcpServers": {
   "aiready": {
     "command": "npx",
     "args": ["-y", "@aiready/mcp-server"]
+  },
+  "ast-explorer": {
+    "command": "npx",
+    "args": ["-y", "@aiready/ast-mcp-server"]
   }
 }
 ```
 
-#### Cursor IDE
+## Installation & Distribution Channels
 
-1. Open Cursor Settings.
-2. Navigate to **Features** -> **MCP Servers**.
-3. Add a new server.
-4. Set the command to: `npx -y @aiready/mcp-server`
+### 1. Dedicated MCP Registries
 
-#### Windsurf IDE
+- **[Smithery](https://smithery.ai)**: `npx @smithery/cli install @aiready/mcp-server`
+- **[Glama](https://glama.ai/mcp)**: View listing.
+- **[Pulsar](https://gotopulsar.com)**: Find on registry.
 
-1. Open Windsurf Settings or local environment configuration.
-2. Add a new MCP Server integration.
-3. Configure the execution command: `npx -y @aiready/mcp-server`
+### 2. Direct IDE Integrations
 
-### 3. Containerized Distribution (Docker)
+#### Claude Desktop App / Cursor / Windsurf
 
-If you prefer running MCP servers in isolated environments, you can use our Docker image:
+Use the following command configuration:
 
 ```bash
-docker run -i --rm ghcr.io/getaiready/aiready-mcp-server
+npx -y @aiready/mcp-server
 ```
 
-_(Note: Docker image distribution is currently being set up. Use the command above once published.)_
-
-### 4. Existing AIReady Channels
-
-We are also integrating the MCP server with our existing distribution methods:
-
-- **Homebrew**: `brew install aiready-mcp` (Coming soon)
-- **VS Code Extension**: Bundled within the AIReady extension for editor-native AI chats. (Coming soon)
-
 ## Quick Start
 
 To test the server locally, you can run:

package/dist/index.js

@@ -5,7 +5,11 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { ToolRegistry, ToolName } from "@aiready/core";
 import { z } from "zod";
@@ -30,6 +34,7 @@ var TOOL_PACKAGE_MAP = {
   [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",
@@ -40,7 +45,8 @@ var TOOL_PACKAGE_MAP = {
   grounding: "@aiready/agent-grounding",
   testability: "@aiready/testability",
   "deps-health": "@aiready/deps",
-  "change-amp": "@aiready/change-amplification"
+  "change-amp": "@aiready/change-amplification",
+  "contract-enforce": "@aiready/contract-enforcement"
 };
 var AIReadyMcpServer = class {
   constructor() {
@@ -52,7 +58,9 @@ var AIReadyMcpServer = class {
       },
       {
         capabilities: {
-          tools: {}
+          tools: {},
+          resources: {},
+          prompts: {}
         }
       }
     );
@@ -118,6 +126,123 @@ ${data.rationale}`
     }
   }
   setupHandlers() {
+    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"
+          }
+        ]
+      };
+    });
+    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}`);
+      }
+    );
+    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
+              }
+            ]
+          }
+        ]
+      };
+    });
+    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}`);
+    });
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
       const toolsToAdvertise = [
         ToolName.PatternDetect,
@@ -128,7 +253,8 @@ ${data.rationale}`
         ToolName.TestabilityIndex,
         ToolName.DocDrift,
         ToolName.DependencyHealth,
-        ToolName.ChangeAmplification
+        ToolName.ChangeAmplification,
+        ToolName.ContractEnforcement
       ];
       const tools = [
         ...toolsToAdvertise.map((id) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/mcp-server",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "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",
@@ -13,16 +13,16 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chalk": "^5.3.0",
     "zod": "^4.3.6",
-    "@aiready/agent-grounding": "0.14.15",
     "@aiready/ai-signal-clarity": "0.14.17",
-    "@aiready/change-amplification": "0.14.15",
     "@aiready/consistency": "0.21.15",
+    "@aiready/agent-grounding": "0.14.15",
+    "@aiready/change-amplification": "0.14.15",
     "@aiready/context-analyzer": "0.22.15",
+    "@aiready/doc-drift": "0.14.15",
     "@aiready/core": "0.24.16",
+    "@aiready/testability": "0.7.16",
     "@aiready/deps": "0.14.15",
-    "@aiready/doc-drift": "0.14.15",
-    "@aiready/pattern-detect": "0.17.15",
-    "@aiready/testability": "0.7.16"
+    "@aiready/pattern-detect": "0.17.15"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/server.test.ts

@@ -127,4 +127,42 @@ describe('AIReady MCP Server Integration', () => {
       'Invalid arguments for pattern-detect'
     );
   });
+
+  it('should list available resources', async () => {
+    const result = await client.listResources();
+    expect(result.resources).toBeDefined();
+    const uris = result.resources.map((r) => r.uri);
+    expect(uris).toContain('aiready://project/summary');
+    expect(uris).toContain('aiready://project/issues');
+  });
+
+  it('should read resource content', async () => {
+    const result = await client.readResource({
+      uri: 'aiready://project/summary',
+    });
+    expect(result.contents).toBeDefined();
+    expect(result.contents[0].uri).toBe('aiready://project/summary');
+    expect(result.contents[0].text).toContain('# AIReady Summary');
+  });
+
+  it('should list available prompts', async () => {
+    const result = await client.listPrompts();
+    expect(result.prompts).toBeDefined();
+    const promptNames = result.prompts.map((p) => p.name);
+    expect(promptNames).toContain('analyze-project');
+    expect(promptNames).toContain('remediate-issue');
+  });
+
+  it('should get prompt content', async () => {
+    const result = await client.getPrompt({
+      name: 'analyze-project',
+      arguments: { path: '/test/path' },
+    });
+    expect(result.messages).toBeDefined();
+    expect(result.messages[0].role).toBe('user');
+    expect(
+      (result.messages[0].content as any).text ||
+        (result.messages[0].content as any).content[0].text
+    ).toContain('/test/path');
+  });
 });

package/src/index.ts

@@ -3,6 +3,10 @@ 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';
@@ -40,6 +44,7 @@ const TOOL_PACKAGE_MAP: Record<string, string> = {
   [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',
@@ -51,6 +56,7 @@ const TOOL_PACKAGE_MAP: Record<string, string> = {
   testability: '@aiready/testability',
   'deps-health': '@aiready/deps',
   'change-amp': '@aiready/change-amplification',
+  'contract-enforce': '@aiready/contract-enforcement',
 };
 
 /**
@@ -69,6 +75,8 @@ export class AIReadyMcpServer {
       {
         capabilities: {
           tools: {},
+          resources: {},
+          prompts: {},
         },
       }
     );
@@ -141,6 +149,141 @@ export class AIReadyMcpServer {
   }
 
   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',
+          },
+        ],
+      };
+    });
+
+    // 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}`);
+    });
+
     // List available tools
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
       // Define canonical tool names to advertise to the client
@@ -155,6 +298,7 @@ export class AIReadyMcpServer {
         ToolName.DocDrift,
         ToolName.DependencyHealth,
         ToolName.ChangeAmplification,
+        ToolName.ContractEnforcement,
       ];
 
       const tools: any[] = [