README Generator MCP Server

Instructions

Implementation Reference

• src/index.ts:126-214 (handler)

  The core handler function that performs the project analysis: reads directory structure, parses package.json, detects technologies and config files, formats structure, and returns structured data including a README template.

  async function analyzeProject(projectPath: string): Promise<any> {
    try {
      const structure = await getDirectoryStructure(projectPath);
  
      let packageJson: any = null;
      try {
        const packagePath = join(projectPath, "package.json");
        const packageContent = await readFile(packagePath, "utf-8");
        packageJson = JSON.parse(packageContent);
      } catch {
        // package.json might not exist
      }
  
      const files = await readdir(projectPath);
      const detectedTechnologies: string[] = [];
      const configFiles: string[] = [];
  
      if (files.includes("package.json")) {
        detectedTechnologies.push("Node.js");
        configFiles.push("package.json");
      }
      if (files.includes("tsconfig.json")) {
        detectedTechnologies.push("TypeScript");
        configFiles.push("tsconfig.json");
      }
      if (files.includes("requirements.txt")) {
        detectedTechnologies.push("Python");
        configFiles.push("requirements.txt");
      }
      if (files.includes("setup.py")) {
        detectedTechnologies.push("Python");
        configFiles.push("setup.py");
      }
      if (files.includes("Cargo.toml")) {
        detectedTechnologies.push("Rust");
        configFiles.push("Cargo.toml");
      }
      if (files.includes("go.mod")) {
        detectedTechnologies.push("Go");
        configFiles.push("go.mod");
      }
      if (files.includes("pom.xml")) {
        detectedTechnologies.push("Java");
        configFiles.push("pom.xml");
      }
      if (files.includes("build.gradle")) {
        detectedTechnologies.push("Java/Gradle");
        configFiles.push("build.gradle");
      }
      if (files.includes("Dockerfile")) {
        detectedTechnologies.push("Docker");
        configFiles.push("Dockerfile");
      }
      if (files.includes(".env.example") || files.includes(".env.template")) {
        configFiles.push(
          files.find((f) => f === ".env.example") || ".env.template",
        );
      }
  
      const structureString = formatDirectoryStructure(structure, 0);
  
      return {
        template: README_TEMPLATE,
        projectData: {
          projectName: packageJson?.name || parse(projectPath).base,
          description: packageJson?.description || null,
          version: packageJson?.version || null,
          author: packageJson?.author || null,
          license: packageJson?.license || null,
          homepage: packageJson?.homepage || null,
          repository: packageJson?.repository || null,
          scripts: packageJson?.scripts || {},
          dependencies: packageJson?.dependencies
            ? Object.keys(packageJson.dependencies)
            : [],
          devDependencies: packageJson?.devDependencies
            ? Object.keys(packageJson.devDependencies)
            : [],
          detectedTechnologies,
          configFiles,
          directoryStructure: structure,
          directoryStructureFormatted: structureString,
          rootFiles: files,
        },
      };
    } catch (error) {
      throw new Error(`Failed to analyze project: ${error}`);
    }
  }

• src/index.ts:424-442 (registration)

  Tool registration in the ListTools handler, including name, detailed description, and input schema.

  {
    name: "analyze_project",
    description:
      "Analyze a project directory and return structured data about the project along with a README template. " +
      "Returns: (1) A template structure with recommended README sections (some required, some optional), " +
      "and (2) Detailed project analysis including detected technologies, package.json data, directory structure, scripts, dependencies, and configuration files. " +
      "The LLM should use this information to construct a comprehensive README following the template structure as a guide, " +
      "adapting sections based on what's relevant for the specific project.",
    inputSchema: {
      type: "object",
      properties: {
        projectPath: {
          type: "string",
          description: "The absolute path to the project directory",
        },
      },
      required: ["projectPath"],
    },
  },

• src/index.ts:432-441 (schema)

  Input schema definition for the analyze_project tool, specifying the projectPath parameter.

  inputSchema: {
    type: "object",
    properties: {
      projectPath: {
        type: "string",
        description: "The absolute path to the project directory",
      },
    },
    required: ["projectPath"],
  },

• src/index.ts:499-510 (registration)

  Dispatch/registration in the CallToolRequestSchema switch statement that invokes the analyzeProject handler.

  case "analyze_project": {
    const { projectPath } = args as { projectPath: string };
    const analysis = await analyzeProject(projectPath);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(analysis, null, 2),
        },
      ],
    };
  }

• src/index.ts:68-123 (helper)

  Supporting helper function to recursively build the directory structure tree, used by analyzeProject.

  async function getDirectoryStructure(
    dirPath: string,
    maxDepth: number = 3,
    currentDepth: number = 0,
    ignorePatterns: string[] = [
      "node_modules",
      ".git",
      "dist",
      "build",
      ".next",
      "coverage",
    ],
  ): Promise<any> {
    if (currentDepth >= maxDepth) {
      return null;
    }
  
    try {
      const entries = await readdir(dirPath, { withFileTypes: true });
      const structure: any = {
        type: "directory",
        name: parse(dirPath).base || dirPath,
        children: [],
      };
  
      for (const entry of entries) {
        if (ignorePatterns.some((pattern) => entry.name.includes(pattern))) {
          continue;
        }
  
        const fullPath = join(dirPath, entry.name);
  
        if (entry.isDirectory()) {
          const subStructure = await getDirectoryStructure(
            fullPath,
            maxDepth,
            currentDepth + 1,
            ignorePatterns,
          );
          if (subStructure) {
            structure.children.push(subStructure);
          }
        } else {
          structure.children.push({
            type: "file",
            name: entry.name,
            path: fullPath,
          });
        }
      }
  
      return structure;
    } catch (error) {
      throw new Error(`Failed to read directory: ${error}`);
    }
  }