ai-readme-mcp 0.2.0 → 0.3.1

package/dist/index.js

@@ -305,29 +305,56 @@ async function getContextForFile(input) {
   let promptText = `## \u{1F4DA} Project Context for: ${filePath}
 
 `;
-  for (const ctx of formattedContexts) {
-    if (ctx.relevance === "root") {
-      promptText += `### Root Conventions (${ctx.path})
+  if (contexts.length === 0) {
+    promptText += `\u26A0\uFE0F **No AI_README.md files found in this project.**
 
 `;
-    } else if (ctx.relevance === "direct") {
-      promptText += `### Direct Module Conventions (${ctx.path})
+    promptText += `To get the most out of AI assistance, consider creating an AI_README.md file to document:
+`;
+    promptText += `- Project architecture and conventions
+`;
+    promptText += `- Coding standards and best practices
+`;
+    promptText += `- Testing requirements
+`;
+    promptText += `- Common patterns to follow
 
 `;
-    } else {
-      promptText += `### Parent Module Conventions (${ctx.path})
+    promptText += `**Quick Start:**
+`;
+    promptText += `Use the \`init_ai_readme\` tool to create a template:
+`;
+    promptText += `- Creates AI_README.md from a customizable template
+`;
+    promptText += `- Helps maintain consistency across your team
+`;
+    promptText += `- Improves AI output quality
+`;
+  } else {
+    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 += ctx.content + "\n\n";
-  }
-  promptText += `---
+    promptText += `---
 **Important Reminders:**
 `;
-  promptText += `- Follow the above conventions when making changes
+    promptText += `- Follow the above conventions when making changes
 `;
-  promptText += `- If your changes affect architecture or conventions, consider updating the relevant AI_README
+    promptText += `- If your changes affect architecture or conventions, consider updating the relevant AI_README
 `;
+  }
   return {
     filePath,
     totalContexts: contexts.length,
@@ -883,53 +910,199 @@ async function validateAIReadmes(input) {
 
 // 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 { readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
+import { join as join5, dirname as dirname4, relative } from "path";
+import { existsSync as existsSync4 } from "fs";
 import { fileURLToPath } from "url";
+
+// src/core/detector.ts
+import { readFile as readFile5, readdir, stat } from "fs/promises";
+import { join as join4 } from "path";
+import { existsSync as existsSync3 } from "fs";
+var ProjectDetector = class {
+  constructor(targetPath) {
+    this.targetPath = targetPath;
+  }
+  /**
+   * Detect project information by analyzing files and structure
+   */
+  async detect() {
+    const info = {
+      projectName: "Project",
+      projectType: "unknown",
+      language: "JavaScript",
+      hasTests: false,
+      mainDirs: []
+    };
+    const packageJsonPath = join4(this.targetPath, "package.json");
+    if (existsSync3(packageJsonPath)) {
+      await this.analyzePackageJson(packageJsonPath, info);
+    }
+    if (existsSync3(join4(this.targetPath, "requirements.txt")) || existsSync3(join4(this.targetPath, "setup.py")) || existsSync3(join4(this.targetPath, "pyproject.toml"))) {
+      info.language = "Python";
+    }
+    if (existsSync3(join4(this.targetPath, "go.mod"))) {
+      info.language = "Go";
+    }
+    if (existsSync3(join4(this.targetPath, "Cargo.toml"))) {
+      info.language = "Rust";
+    }
+    if (existsSync3(join4(this.targetPath, "pom.xml")) || existsSync3(join4(this.targetPath, "build.gradle"))) {
+      info.language = "Java";
+    }
+    await this.analyzeStructure(info);
+    return info;
+  }
+  /**
+   * Analyze package.json to extract project information
+   */
+  async analyzePackageJson(path, info) {
+    try {
+      const content = await readFile5(path, "utf-8");
+      const pkg = JSON.parse(content);
+      if (pkg.name) {
+        info.projectName = pkg.name;
+      }
+      if (pkg.devDependencies?.typescript || pkg.dependencies?.typescript) {
+        info.language = "TypeScript";
+      }
+      if (pkg.dependencies?.react || pkg.devDependencies?.react) {
+        info.framework = "React";
+      } else if (pkg.dependencies?.vue || pkg.devDependencies?.vue) {
+        info.framework = "Vue";
+      } else if (pkg.dependencies?.["@angular/core"]) {
+        info.framework = "Angular";
+      } else if (pkg.dependencies?.next) {
+        info.framework = "Next.js";
+      } else if (pkg.dependencies?.express) {
+        info.framework = "Express";
+      } else if (pkg.dependencies?.nestjs || pkg.dependencies?.["@nestjs/core"]) {
+        info.framework = "NestJS";
+      }
+      const lockFiles = await readdir(this.targetPath);
+      if (lockFiles.includes("pnpm-lock.yaml")) {
+        info.packageManager = "pnpm";
+      } else if (lockFiles.includes("yarn.lock")) {
+        info.packageManager = "yarn";
+      } else if (lockFiles.includes("bun.lockb")) {
+        info.packageManager = "bun";
+      } else if (lockFiles.includes("package-lock.json")) {
+        info.packageManager = "npm";
+      }
+      if (pkg.workspaces || existsSync3(join4(this.targetPath, "pnpm-workspace.yaml"))) {
+        info.projectType = "monorepo";
+      }
+      if (!info.projectType || info.projectType === "unknown") {
+        if (pkg.main || pkg.exports) {
+          info.projectType = "library";
+        } else {
+          info.projectType = "application";
+        }
+      }
+      if (pkg.dependencies) {
+        info.dependencies = Object.keys(pkg.dependencies).slice(0, 5);
+      }
+    } catch (error) {
+    }
+  }
+  /**
+   * Analyze directory structure
+   */
+  async analyzeStructure(info) {
+    try {
+      const entries = await readdir(this.targetPath);
+      const dirs = [];
+      for (const entry of entries) {
+        try {
+          const entryPath = join4(this.targetPath, entry);
+          const stats = await stat(entryPath);
+          if (stats.isDirectory()) {
+            if (["src", "lib", "app", "pages", "components", "api", "server", "client"].includes(entry)) {
+              dirs.push(entry);
+            }
+            if (["test", "tests", "__tests__", "spec"].includes(entry)) {
+              info.hasTests = true;
+            }
+            if (["apps", "packages", "modules"].includes(entry)) {
+              info.projectType = "monorepo";
+              dirs.push(entry);
+            }
+          }
+        } catch {
+        }
+      }
+      info.mainDirs = dirs;
+    } catch (error) {
+    }
+  }
+};
+
+// src/tools/init.ts
 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)")
+  overwrite: z5.boolean().optional().describe("Whether to overwrite existing AI_README.md (default: false)"),
+  smart: z5.boolean().optional().describe("Enable smart content generation based on project analysis (default: true)")
 });
 async function initAIReadme(input) {
   const { targetPath, projectName, overwrite = false } = input;
+  const smart = input.smart !== false;
+  console.error(`[DEBUG] init_ai_readme: smart=${smart}, input.smart=${input.smart}`);
   try {
-    if (!existsSync3(targetPath)) {
+    if (!existsSync4(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 readmePath = join5(targetPath, "AI_README.md");
+    const fileExists = existsSync4(readmePath);
+    let isEmpty = false;
+    if (fileExists) {
+      const existingContent = await readFile6(readmePath, "utf-8");
+      isEmpty = existingContent.trim().length < 50;
+      if (!isEmpty && !overwrite) {
+        return {
+          success: false,
+          error: "AI_README.md already exists with content",
+          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;
+    let detectedInfo = {};
+    if (smart) {
+      const detector = new ProjectDetector(targetPath);
+      const projectInfo = await detector.detect();
+      detectedInfo = projectInfo;
+      const parentReadme = await findParentReadme(targetPath);
+      const isSubdirectory = parentReadme !== null;
+      content = await generateSmartContent(projectInfo, targetPath, isSubdirectory, parentReadme);
+    } else {
+      const __filename2 = fileURLToPath(import.meta.url);
+      const __dirname2 = dirname4(__filename2);
+      const templatePath = join5(__dirname2, "..", "..", "docs", "templates", "basic.md");
+      if (!existsSync4(templatePath)) {
+        return {
+          success: false,
+          error: `Template file not found: ${templatePath}`,
+          message: "Template file is missing. Please check installation."
+        };
+      }
+      content = await readFile6(templatePath, "utf-8");
+      const finalProjectName = projectName || "Project Name";
+      content = content.replace(/\{\{PROJECT_NAME\}\}/g, finalProjectName);
     }
-    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");
+    const action = fileExists ? isEmpty ? "filled" : "overwritten" : "created";
     return {
       success: true,
       readmePath,
-      projectName: finalProjectName,
-      message: `Successfully created AI_README.md at ${readmePath}. Edit the file to customize it for your project.`
+      action,
+      projectInfo: smart ? detectedInfo : void 0,
+      message: `Successfully ${action} AI_README.md at ${readmePath}. ${smart ? "Content generated based on project analysis." : "Edit the file to customize it for your project."}`
     };
   } catch (error) {
     return {
@@ -939,6 +1112,152 @@ async function initAIReadme(input) {
     };
   }
 }
+async function findParentReadme(targetPath) {
+  let currentPath = dirname4(targetPath);
+  const root = "/";
+  while (currentPath !== root) {
+    const readmePath = join5(currentPath, "AI_README.md");
+    if (existsSync4(readmePath)) {
+      const content = await readFile6(readmePath, "utf-8");
+      if (content.trim().length > 50) {
+        return currentPath;
+      }
+    }
+    const parentPath = dirname4(currentPath);
+    if (parentPath === currentPath) break;
+    currentPath = parentPath;
+  }
+  return null;
+}
+async function generateSmartContent(projectInfo, targetPath, isSubdirectory, parentPath) {
+  let content = `# ${projectInfo.projectName}
+
+`;
+  if (isSubdirectory && parentPath) {
+    const relativePath = relative(parentPath, targetPath);
+    content += `> This README extends the root AI_README.md with ${relativePath}-specific conventions.
+
+`;
+  }
+  content += `## Architecture
+
+`;
+  content += `- **Type:** ${projectInfo.projectType}
+`;
+  content += `- **Language:** ${projectInfo.language}
+`;
+  if (projectInfo.framework) {
+    content += `- **Framework:** ${projectInfo.framework}
+`;
+  }
+  content += `
+`;
+  if (projectInfo.mainDirs && projectInfo.mainDirs.length > 0) {
+    content += `## Directory Structure
+
+`;
+    for (const dir of projectInfo.mainDirs) {
+      content += `- ${dir}/ - [Add description]
+`;
+    }
+    content += `
+`;
+  }
+  content += `## Coding Conventions
+
+`;
+  content += `### File Naming
+`;
+  content += `- [Add your file naming conventions here]
+
+`;
+  content += `### Code Style
+`;
+  if (projectInfo.language === "TypeScript") {
+    content += `- Use TypeScript strict mode
+`;
+    content += `- Prefer interfaces over types for object shapes
+`;
+  } else if (projectInfo.language === "Python") {
+    content += `- Follow PEP 8 style guide
+`;
+    content += `- Use type hints
+`;
+  }
+  content += `- [Add more style guidelines]
+
+`;
+  if (projectInfo.framework) {
+    content += `### ${projectInfo.framework} Conventions
+`;
+    if (projectInfo.framework === "React") {
+      content += `- Component naming: PascalCase
+`;
+      content += `- Hooks naming: use prefix 'use'
+`;
+      content += `- Prefer functional components
+`;
+    } else if (projectInfo.framework === "Vue") {
+      content += `- Component naming: PascalCase or kebab-case
+`;
+      content += `- Use Composition API
+`;
+    }
+    content += `
+`;
+  }
+  content += `## Testing
+
+`;
+  if (projectInfo.hasTests) {
+    content += `- Tests are located in test directories
+`;
+  }
+  if (projectInfo.packageManager) {
+    content += `- Run: \`${projectInfo.packageManager} test\`
+`;
+  } else {
+    content += `- Run: [Add test command]
+`;
+  }
+  content += `- Coverage target: [Add target or "not enforced"]
+
+`;
+  if (projectInfo.dependencies && projectInfo.dependencies.length > 0) {
+    content += `## Key Dependencies
+
+`;
+    for (const dep of projectInfo.dependencies) {
+      content += `- ${dep} - [Add purpose]
+`;
+    }
+    content += `
+`;
+  }
+  content += `## Development
+
+`;
+  if (projectInfo.packageManager) {
+    content += `- Install: \`${projectInfo.packageManager} install\`
+`;
+    content += `- Dev: \`${projectInfo.packageManager} run dev\`
+`;
+    content += `- Build: \`${projectInfo.packageManager} run build\`
+`;
+  }
+  content += `
+`;
+  content += `## Important Notes
+
+`;
+  content += `- [Add critical information that AI should know]
+`;
+  content += `- [Security considerations]
+`;
+  content += `- [Performance considerations]
+`;
+  return content;
+}
 
 // src/index.ts
 var server = new Server(
@@ -962,12 +1281,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         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.",
+        description: "Get relevant AI_README context for a specific file path. Returns formatted context from relevant README files to help understand project conventions. Use this BEFORE creating or editing files to understand conventions - works even if the file does not exist yet.",
         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.",
+        description: "Update an AI_README.md file when you discover important conventions, patterns, or rules while editing code. Use this to keep documentation in sync with code changes. Supports append, prepend, replace, insert-after, insert-before operations. Auto-validates after update. Note: Only update when you find NEW conventions not already documented - avoid duplicate updates.",
         inputSchema: zodToJsonSchema(updateSchema)
       },
       {
@@ -977,7 +1296,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         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.",
+        description: "Initialize or fill an AI_README.md file with smart content based on project analysis. Auto-detects project type, language, and framework. Use this to create new READMEs or fill empty ones.",
         inputSchema: zodToJsonSchema(initSchema)
       }
     ]