Spec MCP Server

Instructions

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 }] }; } );