ai-readme-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1073 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// src/tools/discover.ts
+import { z } from "zod";
+
+// src/core/scanner.ts
+import { glob } from "glob";
+import { readFile } from "fs/promises";
+import { dirname, join } from "path";
+var AIReadmeScanner = class {
+  projectRoot;
+  options;
+  constructor(projectRoot, options) {
+    this.projectRoot = projectRoot;
+    this.options = {
+      excludePatterns: options?.excludePatterns || [
+        "**/node_modules/**",
+        "**/.git/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/.next/**",
+        "**/coverage/**"
+      ],
+      cacheContent: options?.cacheContent ?? true,
+      readmeFilename: options?.readmeFilename || "AI_README.md"
+    };
+  }
+  /**
+   * Scan the project directory for AI_README.md files
+   */
+  async scan() {
+    const pattern = `**/${this.options.readmeFilename}`;
+    const ignore = this.options.excludePatterns;
+    const files = await glob(pattern, {
+      cwd: this.projectRoot,
+      ignore,
+      absolute: false,
+      nodir: true
+    });
+    const readmes = [];
+    for (const file of files) {
+      const entry = await this.createReadmeEntry(file);
+      readmes.push(entry);
+    }
+    readmes.sort((a, b) => a.level - b.level);
+    return {
+      projectRoot: this.projectRoot,
+      readmes,
+      lastUpdated: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Create a ReadmeEntry from a file path
+   */
+  async createReadmeEntry(filePath) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const dir = dirname(normalizedPath);
+    const level = dir === "." ? 0 : dir.split("/").length;
+    const scope = dir === "." ? "root" : dir.replace(/\//g, "-");
+    const patterns = this.generatePatterns(dir);
+    let content;
+    if (this.options.cacheContent) {
+      try {
+        const fullPath = join(this.projectRoot, filePath);
+        content = await readFile(fullPath, "utf-8");
+      } catch (error) {
+        console.error(`Failed to read ${filePath}:`, error);
+      }
+    }
+    return {
+      path: normalizedPath,
+      scope,
+      level,
+      patterns,
+      content
+    };
+  }
+  /**
+   * Generate glob patterns that this README covers
+   */
+  generatePatterns(dir) {
+    if (dir === ".") {
+      return ["**/*"];
+    }
+    return [
+      `${dir}/**/*`,
+      // All files in this directory and subdirectories
+      `${dir}/*`
+      // Direct children
+    ];
+  }
+  /**
+   * Refresh the scan (re-scan the project)
+   */
+  async refresh() {
+    return this.scan();
+  }
+  /**
+   * Get the project root directory
+   */
+  getProjectRoot() {
+    return this.projectRoot;
+  }
+  /**
+   * Get current scanner options
+   */
+  getOptions() {
+    return { ...this.options };
+  }
+};
+
+// src/tools/discover.ts
+var discoverSchema = z.object({
+  projectRoot: z.string().describe("The root directory of the project"),
+  excludePatterns: z.array(z.string()).optional().describe("Glob patterns to exclude (e.g., ['node_modules/**', '.git/**'])")
+});
+async function discoverAIReadmes(input) {
+  const { projectRoot, excludePatterns } = input;
+  const scanner = new AIReadmeScanner(projectRoot, {
+    excludePatterns,
+    cacheContent: false
+    // Don't cache content in discovery phase
+  });
+  const index = await scanner.scan();
+  return {
+    projectRoot: index.projectRoot,
+    totalFound: index.readmes.length,
+    readmeFiles: index.readmes.map((readme) => ({
+      path: readme.path,
+      scope: readme.scope,
+      level: readme.level,
+      patterns: readme.patterns
+    })),
+    lastUpdated: index.lastUpdated.toISOString()
+  };
+}
+
+// src/tools/getContext.ts
+import { z as z2 } from "zod";
+
+// src/core/router.ts
+import { minimatch } from "minimatch";
+import { dirname as dirname2, join as join2 } from "path";
+import { readFile as readFile2 } from "fs/promises";
+var ContextRouter = class {
+  index;
+  constructor(index) {
+    this.index = index;
+  }
+  /**
+   * Get relevant AI_README contexts for a specific file path
+   * @param filePath - The file path relative to project root
+   * @param includeRoot - Whether to include root-level README (default: true)
+   */
+  async getContextForFile(filePath, includeRoot = true) {
+    const contexts = [];
+    for (const readme of this.index.readmes) {
+      const match = this.matchesPath(filePath, readme);
+      if (!match) continue;
+      if (!includeRoot && readme.level === 0) continue;
+      const distance = this.calculateDistance(filePath, readme);
+      const content = await this.getReadmeContent(readme);
+      const relevance = this.determineRelevance(filePath, readme);
+      contexts.push({
+        path: readme.path,
+        content,
+        relevance,
+        distance
+      });
+    }
+    contexts.sort((a, b) => {
+      if (a.distance !== b.distance) {
+        return a.distance - b.distance;
+      }
+      const relevanceOrder = { direct: 0, parent: 1, root: 2 };
+      return relevanceOrder[a.relevance] - relevanceOrder[b.relevance];
+    });
+    return contexts;
+  }
+  /**
+   * Get contexts for multiple files
+   */
+  async getContextForFiles(filePaths) {
+    const results = /* @__PURE__ */ new Map();
+    for (const filePath of filePaths) {
+      const contexts = await this.getContextForFile(filePath);
+      results.set(filePath, contexts);
+    }
+    return results;
+  }
+  /**
+   * Check if a file path matches a README's patterns
+   */
+  matchesPath(filePath, readme) {
+    return readme.patterns.some((pattern) => {
+      return minimatch(filePath, pattern, { dot: true });
+    });
+  }
+  /**
+   * Calculate the directory distance between a file and a README
+   */
+  calculateDistance(filePath, readme) {
+    const fileDir = dirname2(filePath);
+    const readmeDir = dirname2(readme.path);
+    if (readmeDir === ".") {
+      return fileDir === "." ? 0 : fileDir.split("/").length;
+    }
+    if (fileDir === readmeDir) {
+      return 0;
+    }
+    if (fileDir.startsWith(readmeDir + "/")) {
+      const subPath = fileDir.slice(readmeDir.length + 1);
+      return subPath.split("/").length;
+    }
+    const fileParts = fileDir.split("/");
+    const readmeParts = readmeDir.split("/");
+    let commonDepth = 0;
+    for (let i = 0; i < Math.min(fileParts.length, readmeParts.length); i++) {
+      if (fileParts[i] === readmeParts[i]) {
+        commonDepth++;
+      } else {
+        break;
+      }
+    }
+    return fileParts.length - commonDepth + (readmeParts.length - commonDepth);
+  }
+  /**
+   * Determine the relevance type of a README for a file
+   */
+  determineRelevance(filePath, readme) {
+    const fileDir = dirname2(filePath);
+    const readmeDir = dirname2(readme.path);
+    if (readmeDir === ".") {
+      return "root";
+    }
+    if (fileDir === readmeDir) {
+      return "direct";
+    }
+    if (fileDir.startsWith(readmeDir + "/")) {
+      return "parent";
+    }
+    return "parent";
+  }
+  /**
+   * Get the content of a README (from cache or file system)
+   */
+  async getReadmeContent(readme) {
+    if (readme.content) {
+      return readme.content;
+    }
+    try {
+      const fullPath = join2(this.index.projectRoot, readme.path);
+      return await readFile2(fullPath, "utf-8");
+    } catch (error) {
+      console.error(`Failed to read ${readme.path}:`, error);
+      return `[Error: Could not read ${readme.path}]`;
+    }
+  }
+  /**
+   * Update the index (useful after re-scanning)
+   */
+  updateIndex(index) {
+    this.index = index;
+  }
+  /**
+   * Get the current index
+   */
+  getIndex() {
+    return this.index;
+  }
+};
+
+// src/tools/getContext.ts
+var getContextSchema = z2.object({
+  projectRoot: z2.string().describe("The root directory of the project"),
+  filePath: z2.string().describe("The file path to get context for (relative to project root)"),
+  includeRoot: z2.boolean().optional().default(true).describe("Whether to include root-level AI_README (default: true)"),
+  excludePatterns: z2.array(z2.string()).optional().describe("Glob patterns to exclude when scanning")
+});
+async function getContextForFile(input) {
+  const { projectRoot, filePath, includeRoot, excludePatterns } = input;
+  const scanner = new AIReadmeScanner(projectRoot, {
+    excludePatterns,
+    cacheContent: true
+    // Cache content for context retrieval
+  });
+  const index = await scanner.scan();
+  const router = new ContextRouter(index);
+  const contexts = await router.getContextForFile(filePath, includeRoot);
+  const formattedContexts = contexts.map((ctx) => ({
+    path: ctx.path,
+    relevance: ctx.relevance,
+    distance: ctx.distance,
+    content: ctx.content
+  }));
+  let promptText = `## \u{1F4DA} Project Context for: ${filePath}
+
+`;
+  for (const ctx of formattedContexts) {
+    if (ctx.relevance === "root") {
+      promptText += `### Root Conventions (${ctx.path})
+
+`;
+    } else if (ctx.relevance === "direct") {
+      promptText += `### Direct Module Conventions (${ctx.path})
+
+`;
+    } else {
+      promptText += `### Parent Module Conventions (${ctx.path})
+
+`;
+    }
+    promptText += ctx.content + "\n\n";
+  }
+  promptText += `---
+**Important Reminders:**
+`;
+  promptText += `- Follow the above conventions when making changes
+`;
+  promptText += `- If your changes affect architecture or conventions, consider updating the relevant AI_README
+`;
+  return {
+    filePath,
+    totalContexts: contexts.length,
+    contexts: formattedContexts,
+    formattedPrompt: promptText
+  };
+}
+
+// src/tools/update.ts
+import { z as z3 } from "zod";
+import { dirname as dirname3 } from "path";
+
+// src/core/updater.ts
+import { readFile as readFile3, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+var ReadmeUpdater = class {
+  constructor() {
+  }
+  /**
+   * Update a README file with given operations
+   *
+   * @param readmePath - Path to the AI_README.md file
+   * @param operations - List of update operations
+   * @returns Update result with changes
+   */
+  async update(readmePath, operations) {
+    try {
+      if (!existsSync(readmePath)) {
+        return {
+          success: false,
+          error: `File not found: ${readmePath}`,
+          changes: []
+        };
+      }
+      const content = await readFile3(readmePath, "utf-8");
+      let updatedContent = content;
+      const changes = [];
+      for (const operation of operations) {
+        const result = await this.applyOperation(updatedContent, operation);
+        updatedContent = result.content;
+        changes.push(result.change);
+      }
+      await writeFile(readmePath, updatedContent, "utf-8");
+      return {
+        success: true,
+        changes
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        changes: []
+      };
+    }
+  }
+  /**
+   * Apply a single update operation to content
+   *
+   * @param content - Current content
+   * @param operation - Operation to apply
+   * @returns Updated content and change info
+   */
+  async applyOperation(content, operation) {
+    const lines = content.split("\n");
+    let updatedLines = [...lines];
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    switch (operation.type) {
+      case "append": {
+        updatedLines.push("", operation.content);
+        linesAdded = operation.content.split("\n").length + 1;
+        break;
+      }
+      case "prepend": {
+        updatedLines.unshift(operation.content, "");
+        linesAdded = operation.content.split("\n").length + 1;
+        break;
+      }
+      case "replace": {
+        if (!operation.searchText) {
+          throw new Error("searchText is required for replace operation");
+        }
+        const originalContent = updatedLines.join("\n");
+        const newContent = originalContent.replace(
+          operation.searchText,
+          operation.content
+        );
+        if (originalContent === newContent) {
+          throw new Error(`Text not found: ${operation.searchText}`);
+        }
+        updatedLines = newContent.split("\n");
+        linesRemoved = operation.searchText.split("\n").length;
+        linesAdded = operation.content.split("\n").length;
+        break;
+      }
+      case "insert-after": {
+        if (!operation.section) {
+          throw new Error("section is required for insert-after operation");
+        }
+        const sectionIndex = this.findSectionIndex(updatedLines, operation.section);
+        if (sectionIndex === -1) {
+          throw new Error(`Section not found: ${operation.section}`);
+        }
+        const insertIndex = this.findSectionEnd(updatedLines, sectionIndex);
+        updatedLines.splice(insertIndex, 0, "", operation.content);
+        linesAdded = operation.content.split("\n").length + 1;
+        break;
+      }
+      case "insert-before": {
+        if (!operation.section) {
+          throw new Error("section is required for insert-before operation");
+        }
+        const sectionIndex = this.findSectionIndex(updatedLines, operation.section);
+        if (sectionIndex === -1) {
+          throw new Error(`Section not found: ${operation.section}`);
+        }
+        updatedLines.splice(sectionIndex, 0, operation.content, "");
+        linesAdded = operation.content.split("\n").length + 1;
+        break;
+      }
+      default:
+        throw new Error(`Unknown operation type: ${operation.type}`);
+    }
+    return {
+      content: updatedLines.join("\n"),
+      change: {
+        operation: operation.type,
+        section: operation.section,
+        linesAdded,
+        linesRemoved
+      }
+    };
+  }
+  /**
+   * Find the index of a section heading
+   *
+   * @param lines - Content lines
+   * @param section - Section heading (e.g., "## Coding Conventions")
+   * @returns Index of the section, or -1 if not found
+   */
+  findSectionIndex(lines, section) {
+    return lines.findIndex((line) => line.trim() === section.trim());
+  }
+  /**
+   * Find the end of a section (before the next section of same or higher level)
+   *
+   * @param lines - Content lines
+   * @param startIndex - Index of the section heading
+   * @returns Index where the section ends
+   */
+  findSectionEnd(lines, startIndex) {
+    const startLine = lines[startIndex];
+    if (!startLine) {
+      return lines.length;
+    }
+    const sectionLevel = this.getSectionLevel(startLine);
+    for (let i = startIndex + 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line) continue;
+      const trimmedLine = line.trim();
+      if (trimmedLine.startsWith("#")) {
+        const level = this.getSectionLevel(trimmedLine);
+        if (level <= sectionLevel) {
+          return i;
+        }
+      }
+    }
+    return lines.length;
+  }
+  /**
+   * Get the heading level of a markdown section
+   *
+   * @param line - Line containing a heading
+   * @returns Heading level (1-6)
+   */
+  getSectionLevel(line) {
+    const match = line.match(/^(#{1,6})\s/);
+    return match && match[1] ? match[1].length : 0;
+  }
+};
+
+// src/core/validator.ts
+import { readFile as readFile4 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join as join3 } from "path";
+
+// src/types/index.ts
+var DEFAULT_VALIDATION_CONFIG = {
+  maxTokens: 400,
+  rules: {
+    requireH1: true,
+    requireSections: [],
+    allowCodeBlocks: false,
+    maxLineLength: 100
+  },
+  tokenLimits: {
+    excellent: 200,
+    good: 400,
+    warning: 600,
+    error: 1e3
+  }
+};
+
+// src/core/validator.ts
+var ReadmeValidator = class {
+  config;
+  constructor(config) {
+    this.config = this.mergeConfig(config || {});
+  }
+  /**
+   * Merge user config with default config
+   */
+  mergeConfig(userConfig) {
+    return {
+      maxTokens: userConfig.maxTokens ?? DEFAULT_VALIDATION_CONFIG.maxTokens,
+      rules: {
+        ...DEFAULT_VALIDATION_CONFIG.rules,
+        ...userConfig.rules || {}
+      },
+      tokenLimits: {
+        ...DEFAULT_VALIDATION_CONFIG.tokenLimits,
+        ...userConfig.tokenLimits || {}
+      }
+    };
+  }
+  /**
+   * Validate a single AI_README.md file
+   *
+   * @param readmePath - Path to the README file
+   * @returns Validation result
+   */
+  async validate(readmePath) {
+    const issues = [];
+    if (!existsSync2(readmePath)) {
+      return {
+        valid: false,
+        filePath: readmePath,
+        issues: [
+          {
+            type: "error",
+            rule: "structure",
+            message: `File not found: ${readmePath}`
+          }
+        ]
+      };
+    }
+    const content = await readFile4(readmePath, "utf-8");
+    if (content.trim().length === 0) {
+      issues.push({
+        type: "error",
+        rule: "empty-content",
+        message: "README file is empty",
+        suggestion: "Add content to the README file"
+      });
+    }
+    const lines = content.split("\n");
+    const tokens = this.estimateTokens(content);
+    const characters = content.length;
+    this.validateTokenCount(tokens, issues);
+    this.validateStructure(content, lines, issues);
+    this.validateLineLength(lines, issues);
+    this.validateCodeBlocks(content, issues);
+    const score = this.calculateScore(issues, tokens);
+    return {
+      valid: !issues.some((i) => i.type === "error"),
+      filePath: readmePath,
+      issues,
+      score,
+      stats: {
+        tokens,
+        lines: lines.length,
+        characters
+      }
+    };
+  }
+  /**
+   * Estimate token count (simple word-based estimation)
+   * Formula: words * 1.3 (approximate token-to-word ratio)
+   */
+  estimateTokens(content) {
+    const words = content.split(/\s+/).filter((w) => w.length > 0).length;
+    return Math.round(words * 1.3);
+  }
+  /**
+   * Validate token count against limits
+   */
+  validateTokenCount(tokens, issues) {
+    const { tokenLimits, maxTokens } = this.config;
+    if (tokens > tokenLimits.error) {
+      issues.push({
+        type: "error",
+        rule: "token-count",
+        message: `README is too long (${tokens} tokens). Maximum recommended: ${maxTokens} tokens.`,
+        suggestion: "Remove unnecessary content, use bullet points instead of paragraphs, and avoid code examples."
+      });
+    } else if (tokens > tokenLimits.warning) {
+      issues.push({
+        type: "warning",
+        rule: "token-count",
+        message: `README is quite long (${tokens} tokens). Consider keeping it under ${tokenLimits.good} tokens.`,
+        suggestion: "Simplify content and remove redundant information."
+      });
+    } else if (tokens > tokenLimits.good) {
+      issues.push({
+        type: "info",
+        rule: "token-count",
+        message: `README length is acceptable (${tokens} tokens).`
+      });
+    }
+  }
+  /**
+   * Validate README structure
+   */
+  validateStructure(_content, lines, issues) {
+    if (this.config.rules.requireH1) {
+      const hasH1 = lines.some((line) => line.trim().match(/^#\s+[^#]/));
+      if (!hasH1) {
+        issues.push({
+          type: "error",
+          rule: "require-h1",
+          message: "README must have a H1 heading (# Title)",
+          suggestion: "Add a title at the beginning of the file: # Project Name"
+        });
+      }
+    }
+    if (this.config.rules.requireSections && this.config.rules.requireSections.length > 0) {
+      for (const section of this.config.rules.requireSections) {
+        const hasSection = lines.some((line) => line.trim() === section);
+        if (!hasSection) {
+          issues.push({
+            type: "warning",
+            rule: "require-sections",
+            message: `Missing required section: ${section}`,
+            suggestion: `Add section: ${section}`
+          });
+        }
+      }
+    }
+  }
+  /**
+   * Validate line length
+   */
+  validateLineLength(lines, issues) {
+    const { maxLineLength } = this.config.rules;
+    const longLines = lines.map((line, index) => ({ line, index })).filter(({ line }) => line.length > maxLineLength);
+    if (longLines.length > 3) {
+      issues.push({
+        type: "info",
+        rule: "line-length",
+        message: `${longLines.length} lines exceed ${maxLineLength} characters`,
+        suggestion: "Consider breaking long lines for better readability"
+      });
+    }
+  }
+  /**
+   * Validate code blocks
+   */
+  validateCodeBlocks(content, issues) {
+    if (!this.config.rules.allowCodeBlocks) {
+      const codeBlockCount = (content.match(/```/g) || []).length / 2;
+      if (codeBlockCount > 0) {
+        issues.push({
+          type: "warning",
+          rule: "code-blocks",
+          message: `Found ${codeBlockCount} code blocks. Code examples consume many tokens.`,
+          suggestion: "Remove code examples or move them to separate documentation."
+        });
+      }
+    }
+  }
+  /**
+   * Calculate quality score (0-100)
+   */
+  calculateScore(issues, tokens) {
+    let score = 100;
+    for (const issue of issues) {
+      if (issue.type === "error") score -= 20;
+      else if (issue.type === "warning") score -= 10;
+      else if (issue.type === "info") score -= 2;
+    }
+    const { tokenLimits } = this.config;
+    if (tokens > tokenLimits.error) score -= 30;
+    else if (tokens > tokenLimits.warning) score -= 15;
+    else if (tokens < tokenLimits.excellent) score += 10;
+    return Math.max(0, Math.min(100, score));
+  }
+  /**
+   * Load validation config from .aireadme.config.json
+   *
+   * @param projectRoot - Project root directory
+   * @returns Validation config or null if not found
+   */
+  static async loadConfig(projectRoot) {
+    const configPath = join3(projectRoot, ".aireadme.config.json");
+    if (!existsSync2(configPath)) {
+      return null;
+    }
+    try {
+      const content = await readFile4(configPath, "utf-8");
+      const config = JSON.parse(content);
+      return config.validation || config;
+    } catch (error) {
+      console.error(`Failed to load config from ${configPath}:`, error);
+      return null;
+    }
+  }
+};
+
+// src/tools/update.ts
+var updateOperationSchema = z3.object({
+  type: z3.enum(["replace", "append", "prepend", "insert-after", "insert-before"]).describe(
+    "Type of update operation"
+  ),
+  section: z3.string().optional().describe(
+    'Section heading to target (e.g., "## Coding Conventions")'
+  ),
+  searchText: z3.string().optional().describe(
+    "Text to search for (required for replace operation)"
+  ),
+  content: z3.string().describe("Content to add or replace")
+});
+var updateSchema = z3.object({
+  readmePath: z3.string().describe("Path to the AI_README.md file to update"),
+  operations: z3.array(updateOperationSchema).describe(
+    "List of update operations to perform"
+  )
+});
+async function updateAIReadme(input) {
+  const { readmePath, operations } = input;
+  const updater = new ReadmeUpdater();
+  const result = await updater.update(readmePath, operations);
+  if (!result.success) {
+    return {
+      success: false,
+      readmePath,
+      error: result.error,
+      summary: `Failed to update ${readmePath}: ${result.error}`
+    };
+  }
+  try {
+    const projectRoot = dirname3(dirname3(readmePath));
+    const config = await ReadmeValidator.loadConfig(projectRoot);
+    const validator = new ReadmeValidator(config || void 0);
+    const validation = await validator.validate(readmePath);
+    const warnings = validation.issues.filter((i) => i.type === "warning" || i.type === "error").map((i) => `[${i.type.toUpperCase()}] ${i.message}`);
+    return {
+      success: true,
+      readmePath,
+      changes: result.changes,
+      summary: `Successfully updated ${readmePath} with ${result.changes.length} operation(s). Use 'git diff' to review changes.`,
+      validation: {
+        valid: validation.valid,
+        score: validation.score,
+        warnings: warnings.length > 0 ? warnings : void 0,
+        stats: validation.stats
+      }
+    };
+  } catch (validationError) {
+    return {
+      success: true,
+      readmePath,
+      changes: result.changes,
+      summary: `Successfully updated ${readmePath} with ${result.changes.length} operation(s). Use 'git diff' to review changes.`,
+      validation: {
+        valid: false,
+        error: validationError instanceof Error ? validationError.message : "Validation failed"
+      }
+    };
+  }
+}
+
+// src/tools/validate.ts
+import { z as z4 } from "zod";
+var validateSchema = z4.object({
+  projectRoot: z4.string().describe("The root directory of the project"),
+  excludePatterns: z4.array(z4.string()).optional().describe(
+    'Glob patterns to exclude (e.g., ["node_modules/**", ".git/**"])'
+  ),
+  config: z4.object({
+    maxTokens: z4.number().optional(),
+    rules: z4.object({
+      requireH1: z4.boolean().optional(),
+      requireSections: z4.array(z4.string()).optional(),
+      allowCodeBlocks: z4.boolean().optional(),
+      maxLineLength: z4.number().optional()
+    }).optional(),
+    tokenLimits: z4.object({
+      excellent: z4.number().optional(),
+      good: z4.number().optional(),
+      warning: z4.number().optional(),
+      error: z4.number().optional()
+    }).optional()
+  }).optional().describe("Custom validation configuration (optional, uses defaults if not provided)")
+});
+async function validateAIReadmes(input) {
+  const { projectRoot, excludePatterns, config: userConfig } = input;
+  try {
+    let config = userConfig;
+    if (!config) {
+      const fileConfig = await ReadmeValidator.loadConfig(projectRoot);
+      if (fileConfig) {
+        config = fileConfig;
+      }
+    }
+    const validator = new ReadmeValidator(config);
+    const scanner = new AIReadmeScanner(projectRoot, {
+      excludePatterns: excludePatterns || [],
+      cacheContent: false
+    });
+    const index = await scanner.scan();
+    const results = [];
+    for (const readme of index.readmes) {
+      const result = await validator.validate(readme.path);
+      results.push(result);
+    }
+    const totalFiles = results.length;
+    const validFiles = results.filter((r) => r.valid).length;
+    const totalIssues = results.reduce((sum, r) => sum + r.issues.length, 0);
+    const averageScore = totalFiles > 0 ? Math.round(results.reduce((sum, r) => sum + (r.score || 0), 0) / totalFiles) : 0;
+    const issuesBySeverity = {
+      error: 0,
+      warning: 0,
+      info: 0
+    };
+    for (const result of results) {
+      for (const issue of result.issues) {
+        issuesBySeverity[issue.type]++;
+      }
+    }
+    return {
+      success: true,
+      projectRoot,
+      summary: {
+        totalFiles,
+        validFiles,
+        invalidFiles: totalFiles - validFiles,
+        totalIssues,
+        averageScore,
+        issuesBySeverity
+      },
+      results,
+      message: totalIssues === 0 ? `All ${totalFiles} README files passed validation! Average score: ${averageScore}/100` : `Found ${totalIssues} issues across ${totalFiles} README files. ${validFiles} files passed validation.`
+    };
+  } catch (error) {
+    return {
+      success: false,
+      projectRoot,
+      error: error instanceof Error ? error.message : String(error),
+      message: `Validation failed: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+
+// src/tools/init.ts
+import { z as z5 } from "zod";
+import { readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import { join as join4, dirname as dirname4 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { fileURLToPath } from "url";
+var initSchema = z5.object({
+  targetPath: z5.string().describe("Directory where AI_README.md will be created"),
+  projectName: z5.string().optional().describe("Project name to use in the template (optional)"),
+  overwrite: z5.boolean().optional().describe("Whether to overwrite existing AI_README.md (default: false)")
+});
+async function initAIReadme(input) {
+  const { targetPath, projectName, overwrite = false } = input;
+  try {
+    if (!existsSync3(targetPath)) {
+      return {
+        success: false,
+        error: `Target directory does not exist: ${targetPath}`,
+        message: `Failed to create AI_README.md: Directory not found`
+      };
+    }
+    const readmePath = join4(targetPath, "AI_README.md");
+    if (existsSync3(readmePath) && !overwrite) {
+      return {
+        success: false,
+        error: "AI_README.md already exists",
+        message: `AI_README.md already exists at ${readmePath}. Use overwrite: true to replace it.`,
+        existingPath: readmePath
+      };
+    }
+    const __filename2 = fileURLToPath(import.meta.url);
+    const __dirname2 = dirname4(__filename2);
+    const templatePath = join4(__dirname2, "..", "..", "docs", "templates", "basic.md");
+    if (!existsSync3(templatePath)) {
+      return {
+        success: false,
+        error: `Template file not found: ${templatePath}`,
+        message: "Template file is missing. Please check installation."
+      };
+    }
+    let content = await readFile5(templatePath, "utf-8");
+    const finalProjectName = projectName || "Project Name";
+    content = content.replace(/\{\{PROJECT_NAME\}\}/g, finalProjectName);
+    await writeFile2(readmePath, content, "utf-8");
+    return {
+      success: true,
+      readmePath,
+      projectName: finalProjectName,
+      message: `Successfully created AI_README.md at ${readmePath}. Edit the file to customize it for your project.`
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      message: `Failed to create AI_README.md: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+
+// src/index.ts
+var server = new Server(
+  {
+    name: "ai-readme-mcp",
+    version: "0.1.0"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "discover_ai_readmes",
+        description: "Scan the project and discover all AI_README.md files. Returns an index of all README files with their paths, scopes, and coverage patterns.",
+        inputSchema: zodToJsonSchema(discoverSchema)
+      },
+      {
+        name: "get_context_for_file",
+        description: "Get relevant AI_README context for a specific file path. Returns formatted context from relevant README files to help understand project conventions.",
+        inputSchema: zodToJsonSchema(getContextSchema)
+      },
+      {
+        name: "update_ai_readme",
+        description: "Update an AI_README.md file with specified operations (append, prepend, replace, insert-after, insert-before). Auto-validates after update. Changes are written directly; use Git for version control.",
+        inputSchema: zodToJsonSchema(updateSchema)
+      },
+      {
+        name: "validate_ai_readmes",
+        description: "Validate all AI_README.md files in a project. Checks token count, structure, and content quality. Returns validation results with suggestions for improvement.",
+        inputSchema: zodToJsonSchema(validateSchema)
+      },
+      {
+        name: "init_ai_readme",
+        description: "Initialize a new AI_README.md file from a template. Creates a basic structure with common sections to help you get started quickly.",
+        inputSchema: zodToJsonSchema(initSchema)
+      }
+    ]
+  };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    if (name === "discover_ai_readmes") {
+      const input = discoverSchema.parse(args);
+      const result = await discoverAIReadmes(input);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+    if (name === "get_context_for_file") {
+      const input = getContextSchema.parse(args);
+      const result = await getContextForFile(input);
+      return {
+        content: [
+          {
+            type: "text",
+            text: result.formattedPrompt
+          }
+        ]
+      };
+    }
+    if (name === "update_ai_readme") {
+      const input = updateSchema.parse(args);
+      const result = await updateAIReadme(input);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+    if (name === "validate_ai_readmes") {
+      const input = validateSchema.parse(args);
+      const result = await validateAIReadmes(input);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+    if (name === "init_ai_readme") {
+      const input = initSchema.parse(args);
+      const result = await initAIReadme(input);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+    throw new Error(`Unknown tool: ${name}`);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${errorMessage}`
+        }
+      ],
+      isError: true
+    };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("AI_README MCP Server started");
+  console.error("Available tools: discover_ai_readmes, get_context_for_file, update_ai_readme, validate_ai_readmes, init_ai_readme");
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map