generate-codebase-analysis - Spec MCP Server

Generate Codebase Analysis Documents

generate-codebase-analysis

Analyze codebases to generate foundational documentation including product features, technology stack, and project structure analysis in .spec/steering/ directory, with optional regeneration control.

Instructions

Analyzes codebase and generates three foundational analysis documents: product.md, tech.md, and structure.md in .spec/steering/ directory. These documents provide comprehensive analysis of the product features, technology stack, and project structure. Checks if files already exist and skips generation unless force_regenerate is true.

Input Schema

TableJSON Schema

Name	Required	Description
`additional_context`	No	Additional context about the project
`force_regenerate`	No	Force regeneration even if files exist (default: false)
`project_path`	No	Path to the project directory (defaults to current directory)

Implementation Reference

src/server.ts:30-228 (handler)

The handler function constructs a comprehensive prompt that instructs an AI agent to analyze the codebase and generate three markdown documents (product.md, tech.md, structure.md) in the .spec/steering/ directory. It includes checks for existing files unless force_regenerate is true, and provides detailed templates and execution steps for file creation using filesystem tools.

  async ({ project_path = '.', additional_context, force_regenerate = false }) => {
    const prompt = `# ⚠️ IMPORTANT: YOU MUST EXECUTE THE FOLLOWING ACTIONS

This MCP tool provides instructions that YOU (the AI assistant) must execute using your available file system tools.
**DO NOT** just report success - you MUST actually create the files using Write or MultiEdit tools.

# Generate Steering Documents for ${project_path}

## PREREQUISITE: CHECK IF FILES ALREADY EXIST
${!force_regenerate ? `
IMPORTANT: Before generating new files, FIRST check if steering documents already exist:
1. **USE Read tool** to check if file exists: ${project_path}/.spec/steering/product.md
2. **USE Read tool** to check if file exists: ${project_path}/.spec/steering/tech.md
3. **USE Read tool** to check if file exists: ${project_path}/.spec/steering/structure.md

If ALL THREE files already exist:
- STOP HERE and return: "✅ Steering documents already exist at ${project_path}/.spec/steering/. No regeneration needed. Use force_regenerate=true to regenerate."
- Do NOT proceed with generation

If ANY files are missing, proceed with generation below.
` : 'FORCE REGENERATE MODE: Regenerating all steering documents even if they exist.'}

You MUST create THREE separate steering documents that match exact structure and content approach.

## 🔴 CRITICAL: YOU MUST CREATE THE FILES - NOT JUST REPORT SUCCESS
### File Creation Instructions:
1. **USE Bash tool** to create directory: mkdir -p ${project_path}/.spec/steering/
2. **USE Write tool** to create THREE separate files with exact filenames:
   - ${project_path}/.spec/steering/product.md
   - ${project_path}/.spec/steering/tech.md
   - ${project_path}/.spec/steering/structure.md
3. **USE Read tool** to verify each file exists after creation

⚠️ The files MUST be physically created on the filesystem. Do NOT proceed without using the Write tool.

## DOCUMENT SPECIFICATIONS:

### 1. PRODUCT.MD - Product Overview
Create ${project_path}/.spec/steering/product.md with:

# Product Overview

## Purpose
[Analyze the codebase and describe what this product/application does]

## Target Users
- [Primary user type]: [Their needs and use cases]
- [Secondary user type]: [Their needs and use cases]

## Key Features
- [Feature 1]: [Description based on codebase analysis]
- [Feature 2]: [Description based on codebase analysis]
- [Feature 3]: [Description based on codebase analysis]

## Business Objectives
- [Objective 1 derived from codebase context]
- [Objective 2 derived from codebase context]

## Product Context
[Additional context about the product's market, competition, or unique value proposition]

---

### 2. TECH.MD - Technology Stack
Create ${project_path}/.spec/steering/tech.md with:

# Technology Stack

## Core Technologies
- **Primary Language**: [Language and version from package.json/requirements/etc]
- **Framework**: [Main framework detected]
- **Runtime**: [Node.js, Python, .NET, etc. with version]
- **Database**: [Database system if detected]

## Development Tools
- **Package Manager**: [npm, yarn, pip, maven, cargo, dotnet, etc.]
- **Build System**: [webpack, vite, gradle, maven, cargo, msbuild, etc.]
- **Testing Framework**: [jest, pytest, junit, nunit, go test, etc.]
- **Linter/Formatter**: [eslint, prettier, black, checkstyle, clippy, etc.]

## Build and Test Commands
[Auto-detect from project configuration files and scripts]

### Essential Commands
- **Install Dependencies**: [e.g., npm install, pip install -r requirements.txt, dotnet restore]
- **Build Project**: [e.g., npm run build, mvn compile, cargo build, dotnet build]
- **Run Tests**: [e.g., npm test, pytest, mvn test, dotnet test, go test ./...]
- **Lint/Format Check**: [e.g., npm run lint, ruff check, gradle checkstyle, cargo clippy]
- **Type Check**: [e.g., tsc --noEmit, mypy, if applicable]
- **Start Development**: [e.g., npm run dev, python app.py, dotnet run]
- **Production Build**: [e.g., npm run build:prod, mvn package, cargo build --release]

### Project-Specific Commands
[Any custom commands specific to this project from package.json, Makefile, etc.]

## Libraries and Dependencies
### Required Libraries
[List key dependencies from package.json/requirements with purpose]
- [Library]: [Version] - [Purpose]

### Preferred Libraries
[Document preferred libraries for common tasks]
- UI Components: [Library preference]
- State Management: [Library preference]
- HTTP Client: [Library preference]

## Development Guidelines
- Variable naming: [Convention detected from codebase]
- Function naming: [Convention detected from codebase]
- File naming: [Convention detected from codebase]
- Code style: [Style detected from config files]

## Performance Requirements
[Any performance considerations detected or inferred]

## Security Requirements
[Any security patterns or requirements detected]

## Technical Constraints
[Any constraints detected from the codebase]

---

### 3. STRUCTURE.MD - Project Structure
Create ${project_path}/.spec/steering/structure.md with:

# Project Structure

## Directory Organization
\`\`\`
[Generate actual directory tree from the project]
\`\`\`

## File Naming Conventions
- Components: [Pattern detected from codebase]
- Services: [Pattern detected from codebase]
- Types: [Pattern detected from codebase]
- Tests: [Pattern detected from codebase]

## Import Patterns
- Relative imports: [Rules detected from codebase]
- Absolute imports: [Rules detected from codebase]
- External dependencies: [Patterns detected]

## Code Organization
- [Organizational principle 1 detected]
- [Organizational principle 2 detected]
- [Index file strategy if detected]

## Architectural Patterns
- [Pattern 1]: [Description of how it's implemented]
- [Pattern 2]: [Description of how it's implemented]

## Testing Structure
- Unit tests: [Location pattern]
- Integration tests: [Location pattern if exists]
- Test naming: [Convention detected]

## Configuration Files
[List and explain key config files: .env, config/, etc.]

${additional_context ? `\n## Additional Context\n${additional_context}` : ''}

---

## 🔴 EXECUTION STEPS - YOU MUST FOLLOW EXACTLY:
1. Analyze the codebase at: ${project_path} using Read, Grep, and Glob tools
   - **IMPORTANT**: Check package.json, pom.xml, build.gradle, Cargo.toml, go.mod, requirements.txt, *.csproj, Makefile, etc.
   - Extract actual build/test/lint commands from these files
   - Look for CI configuration files (.github/workflows, .gitlab-ci.yml, Jenkinsfile, etc.)
2. **USE Bash tool** to create directory: mkdir -p ${project_path}/.spec/steering/
3. **USE Write tool** to create product.md with product overview and business context
4. **USE Write tool** to create tech.md with comprehensive technology stack analysis
   - **CRITICAL**: In the "Build and Test Commands" section, document ACTUAL commands found in the project
   - Do not use placeholder text like "[e.g., npm test]" - use the real commands from package.json scripts or build files
5. **USE Write tool** to create structure.md with detailed project organization
6. **USE Read tool** to verify all three files exist and contain expected content:
   - ${project_path}/.spec/steering/product.md
   - ${project_path}/.spec/steering/tech.md
   - ${project_path}/.spec/steering/structure.md

## SUCCESS CRITERIA:
✅ Three separate markdown files PHYSICALLY CREATED on filesystem (not just reported)
✅ Files verified to exist using Read tool
✅ Each file follows content structure exactly
✅ All content derived from actual codebase analysis
✅ Files ready for use with generate-tasks tool

⚠️ FINAL REMINDER: You MUST use Write tool to create the files. Do not just say they were created.

These files should be automatically included in every AI interaction.`;

    return {
      content: [{
        type: "text",
        text: prompt
      }]
    };
  }

src/server.ts:21-28 (schema)

Tool metadata including title, description, and Zod input schema defining optional parameters: project_path, additional_context, force_regenerate.

{
  title: 'Generate Codebase Analysis Documents',
  description: 'Analyzes codebase and generates three foundational analysis documents: product.md, tech.md, and structure.md in .spec/steering/ directory. These documents provide comprehensive analysis of the product features, technology stack, and project structure. Checks if files already exist and skips generation unless force_regenerate is true.',
  inputSchema: {
    project_path: z.string().optional().describe("Path to the project directory (defaults to current directory)"),
    additional_context: z.string().optional().describe("Additional context about the project"),
    force_regenerate: z.boolean().optional().describe("Force regeneration even if files exist (default: false)")
  }

src/server.ts:19-229 (registration)

Registers the 'generate-codebase-analysis' tool with the MCP server using server.registerTool, providing the tool name, schema/metadata, and inline handler function.

server.registerTool(
  'generate-codebase-analysis',
  {
    title: 'Generate Codebase Analysis Documents',
    description: 'Analyzes codebase and generates three foundational analysis documents: product.md, tech.md, and structure.md in .spec/steering/ directory. These documents provide comprehensive analysis of the product features, technology stack, and project structure. Checks if files already exist and skips generation unless force_regenerate is true.',
    inputSchema: {
      project_path: z.string().optional().describe("Path to the project directory (defaults to current directory)"),
      additional_context: z.string().optional().describe("Additional context about the project"),
      force_regenerate: z.boolean().optional().describe("Force regeneration even if files exist (default: false)")
    }
  },
  async ({ project_path = '.', additional_context, force_regenerate = false }) => {
    const prompt = `# ⚠️ IMPORTANT: YOU MUST EXECUTE THE FOLLOWING ACTIONS

This MCP tool provides instructions that YOU (the AI assistant) must execute using your available file system tools.
**DO NOT** just report success - you MUST actually create the files using Write or MultiEdit tools.

# Generate Steering Documents for ${project_path}

## PREREQUISITE: CHECK IF FILES ALREADY EXIST
${!force_regenerate ? `
IMPORTANT: Before generating new files, FIRST check if steering documents already exist:
1. **USE Read tool** to check if file exists: ${project_path}/.spec/steering/product.md
2. **USE Read tool** to check if file exists: ${project_path}/.spec/steering/tech.md
3. **USE Read tool** to check if file exists: ${project_path}/.spec/steering/structure.md

If ALL THREE files already exist:
- STOP HERE and return: "✅ Steering documents already exist at ${project_path}/.spec/steering/. No regeneration needed. Use force_regenerate=true to regenerate."
- Do NOT proceed with generation

If ANY files are missing, proceed with generation below.
` : 'FORCE REGENERATE MODE: Regenerating all steering documents even if they exist.'}

You MUST create THREE separate steering documents that match exact structure and content approach.

## 🔴 CRITICAL: YOU MUST CREATE THE FILES - NOT JUST REPORT SUCCESS
### File Creation Instructions:
1. **USE Bash tool** to create directory: mkdir -p ${project_path}/.spec/steering/
2. **USE Write tool** to create THREE separate files with exact filenames:
   - ${project_path}/.spec/steering/product.md
   - ${project_path}/.spec/steering/tech.md
   - ${project_path}/.spec/steering/structure.md
3. **USE Read tool** to verify each file exists after creation

⚠️ The files MUST be physically created on the filesystem. Do NOT proceed without using the Write tool.

## DOCUMENT SPECIFICATIONS:

### 1. PRODUCT.MD - Product Overview
Create ${project_path}/.spec/steering/product.md with:

# Product Overview

## Purpose
[Analyze the codebase and describe what this product/application does]

## Target Users
- [Primary user type]: [Their needs and use cases]
- [Secondary user type]: [Their needs and use cases]

## Key Features
- [Feature 1]: [Description based on codebase analysis]
- [Feature 2]: [Description based on codebase analysis]
- [Feature 3]: [Description based on codebase analysis]

## Business Objectives
- [Objective 1 derived from codebase context]
- [Objective 2 derived from codebase context]

## Product Context
[Additional context about the product's market, competition, or unique value proposition]

---

### 2. TECH.MD - Technology Stack
Create ${project_path}/.spec/steering/tech.md with:

# Technology Stack

## Core Technologies
- **Primary Language**: [Language and version from package.json/requirements/etc]
- **Framework**: [Main framework detected]
- **Runtime**: [Node.js, Python, .NET, etc. with version]
- **Database**: [Database system if detected]

## Development Tools
- **Package Manager**: [npm, yarn, pip, maven, cargo, dotnet, etc.]
- **Build System**: [webpack, vite, gradle, maven, cargo, msbuild, etc.]
- **Testing Framework**: [jest, pytest, junit, nunit, go test, etc.]
- **Linter/Formatter**: [eslint, prettier, black, checkstyle, clippy, etc.]

## Build and Test Commands
[Auto-detect from project configuration files and scripts]

### Essential Commands
- **Install Dependencies**: [e.g., npm install, pip install -r requirements.txt, dotnet restore]
- **Build Project**: [e.g., npm run build, mvn compile, cargo build, dotnet build]
- **Run Tests**: [e.g., npm test, pytest, mvn test, dotnet test, go test ./...]
- **Lint/Format Check**: [e.g., npm run lint, ruff check, gradle checkstyle, cargo clippy]
- **Type Check**: [e.g., tsc --noEmit, mypy, if applicable]
- **Start Development**: [e.g., npm run dev, python app.py, dotnet run]
- **Production Build**: [e.g., npm run build:prod, mvn package, cargo build --release]

### Project-Specific Commands
[Any custom commands specific to this project from package.json, Makefile, etc.]

## Libraries and Dependencies
### Required Libraries
[List key dependencies from package.json/requirements with purpose]
- [Library]: [Version] - [Purpose]

### Preferred Libraries
[Document preferred libraries for common tasks]
- UI Components: [Library preference]
- State Management: [Library preference]
- HTTP Client: [Library preference]

## Development Guidelines
- Variable naming: [Convention detected from codebase]
- Function naming: [Convention detected from codebase]
- File naming: [Convention detected from codebase]
- Code style: [Style detected from config files]

## Performance Requirements
[Any performance considerations detected or inferred]

## Security Requirements
[Any security patterns or requirements detected]

## Technical Constraints
[Any constraints detected from the codebase]

---

### 3. STRUCTURE.MD - Project Structure
Create ${project_path}/.spec/steering/structure.md with:

# Project Structure

## Directory Organization
\`\`\`
[Generate actual directory tree from the project]
\`\`\`

## File Naming Conventions
- Components: [Pattern detected from codebase]
- Services: [Pattern detected from codebase]
- Types: [Pattern detected from codebase]
- Tests: [Pattern detected from codebase]

## Import Patterns
- Relative imports: [Rules detected from codebase]
- Absolute imports: [Rules detected from codebase]
- External dependencies: [Patterns detected]

## Code Organization
- [Organizational principle 1 detected]
- [Organizational principle 2 detected]
- [Index file strategy if detected]

## Architectural Patterns
- [Pattern 1]: [Description of how it's implemented]
- [Pattern 2]: [Description of how it's implemented]

## Testing Structure
- Unit tests: [Location pattern]
- Integration tests: [Location pattern if exists]
- Test naming: [Convention detected]

## Configuration Files
[List and explain key config files: .env, config/, etc.]

${additional_context ? `\n## Additional Context\n${additional_context}` : ''}

---

## 🔴 EXECUTION STEPS - YOU MUST FOLLOW EXACTLY:
1. Analyze the codebase at: ${project_path} using Read, Grep, and Glob tools
   - **IMPORTANT**: Check package.json, pom.xml, build.gradle, Cargo.toml, go.mod, requirements.txt, *.csproj, Makefile, etc.
   - Extract actual build/test/lint commands from these files
   - Look for CI configuration files (.github/workflows, .gitlab-ci.yml, Jenkinsfile, etc.)
2. **USE Bash tool** to create directory: mkdir -p ${project_path}/.spec/steering/
3. **USE Write tool** to create product.md with product overview and business context
4. **USE Write tool** to create tech.md with comprehensive technology stack analysis
   - **CRITICAL**: In the "Build and Test Commands" section, document ACTUAL commands found in the project
   - Do not use placeholder text like "[e.g., npm test]" - use the real commands from package.json scripts or build files
5. **USE Write tool** to create structure.md with detailed project organization
6. **USE Read tool** to verify all three files exist and contain expected content:
   - ${project_path}/.spec/steering/product.md
   - ${project_path}/.spec/steering/tech.md
   - ${project_path}/.spec/steering/structure.md

## SUCCESS CRITERIA:
✅ Three separate markdown files PHYSICALLY CREATED on filesystem (not just reported)
✅ Files verified to exist using Read tool
✅ Each file follows content structure exactly
✅ All content derived from actual codebase analysis
✅ Files ready for use with generate-tasks tool

⚠️ FINAL REMINDER: You MUST use Write tool to create the files. Do not just say they were created.

These files should be automatically included in every AI interaction.`;

    return {
      content: [{
        type: "text",
        text: prompt
      }]
    };
  }
);

Spec MCP Server

Generate Codebase Analysis Documents

Instructions

Input Schema

Implementation Reference

Tool Definition Quality

Other Tools

Latest Blog Posts

MCP directory API