InitRepo MCP Server

🚨 REQUIRES InitRepo Documentation 🚨

This MCP server ONLY works with InitRepo documentation. It is specifically designed to complement and enhance the InitRepo method of handling context for software projects.

Overview

The InitRepo MCP Server transforms InitRepo documentation into actionable AI development intelligence. It provides 28+ sophisticated analysis tools that understand:

• InitRepo ID System: T-001, E-001, US-001, F-001, etc.
• Cross-Reference Relationships: Epic → Feature → User Story → Task connections
• InitRepo Documentation Structure: Business analysis, PRD, technical architecture, user stories, UX design
• InitRepo Methodology: Context-aware development planning and implementation

⚠️ CRITICAL REQUIREMENT

This tool REQUIRES properly formatted InitRepo documentation to function. It will not work with generic markdown files or other documentation formats.

Key Features

• 🔍 Intelligent Document Analysis: Automatically parses and indexes project documentation
• 🔗 Cross-Reference Mapping: Tracks relationships between epics, user stories, tasks, and features
• 📊 Progress Tracking: Monitor epic completion status and task dependencies
• 🎯 Context-Aware Queries: Retrieve precise context for any project element
• ⚡ Just-in-Time Processing: Efficient lazy-loading of project analysis
• 🛠️ CLI Integration: Seamless integration with initrepo-cli for enhanced tooling

Prerequisites

🚨 MANDATORY: InitRepo Documentation

This tool ONLY works with InitRepo documentation. You must have a complete InitRepo project with:

Required InitRepo Files:

📁 Your Project Structure:
├── README.md (optional in root)
├── docs/
│   ├── business_analysis.md       ← REQUIRED
│   ├── prd.md                     ← REQUIRED
│   ├── technical_architecture.md  ← REQUIRED
│   ├── user_stories.md           ← REQUIRED
│   ├── ux_ui_design.md           ← REQUIRED
│   └── [other files]

InitRepo ID System:

Your documentation must use the InitRepo ID system:

• T-001, T-002: Tasks
• E-001, E-002: Epics
• US-001, US-002: User Stories
• F-001, F-002: Features
• S-001, S-002: Sections/Architecture

How to Get InitRepo Documentation:

1. Create a project at initrepo.com
2. Fill out the questionnaire describing your project
3. Generate documentation with the InitRepo AI
4. Export the documentation to your local project

Additional Dependencies

1. Node.js & TypeScript

   • Node.js 18+ (required)
   • TypeScript support

2. MCP-Compatible Client

   • Claude Desktop
   • VS Code with MCP extension
   • Cursor IDE
   • Any MCP-compatible AI assistant

Installation

Option 1: NPM Package (Recommended)

# Install globally (recommended)
npm install -g initrepo-mcp

# Then run the server
initrepo-mcp

Option 2: From Source

# Clone the repository
git clone https://github.com/initrepo/mcp.git
cd mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the MCP server
npm run start:mcp

Option 3: Docker

# Build Docker image
docker build -t initrepo-mcp .

# Run container
docker run -p 3000:3000 initrepo-mcp

What This Tool Does With InitRepo Documentation

🎯 Without InitRepo Documentation:

• ❌ Server will start but most tools will return empty results
• ❌ No intelligent analysis of project structure
• ❌ Limited functionality - basic file operations only
• ❌ No cross-reference understanding
• ❌ No dependency mapping

✅ With InitRepo Documentation:

• 🧠 Intelligent Requirements Analysis - Identifies missing user stories, incomplete acceptance criteria
• 📊 Smart Implementation Guidance - Context-aware briefs with testing strategies
• ⚡ Advanced Task Management - Critical path analysis, dependency mapping, parallel development
• 🛠️ Technical Intelligence - Technology stack analysis, feasibility assessment
• 🔍 Quality Assurance - Documentation validation, cross-reference integrity
• 📈 Project Optimization - Timeline estimation, resource planning, risk assessment

Documentation Structure

The MCP server automatically detects and analyzes InitRepo documentation in these locations:

project-root/
├── business_analysis.md     # Business strategy & market analysis
├── prd.md                   # Product Requirements Document  
├── technical_architecture.md # Technical specifications
├── user_stories.md          # User stories and epics
├── uxuidesign.md           # UX/UI design specifications
├── README.md               # Development roadmap and tasks
└── packages/mcp-server/    # MCP server implementation

ID System Format

Documents must use the InitRepo ID system:

• Tasks: T-001, T-002, etc.
• Epics: E-001, E-002, etc.
• User Stories: US-001, US-002, etc.
• Features: F-001, F-002, etc.
• Sections: S-001, S-002, etc.
• UI Components: UI-001, UI-002, etc.

Available Tools

Basic Document Access

• getProjectInfo - Retrieve specific documents or sections
• getTechStack - Get project technology stack summary
• getContextById - Fetch context for any project ID

Advanced Analysis

• getEpicProgress - Calculate completion status for epics
• analyzeDependencies - Map upstream/downstream dependencies
• generateImplementationBrief - Create comprehensive implementation guides

CLI Integration

• getProjectStructure - Generate visual project structure
• taskManager - Manage project tasks and checklists

Enhanced Context & Relationship Analysis

• analyzeDependencies - Analyzes all dependencies and relationships for any ID
• getRelationshipMap - Creates comprehensive relationship maps with multi-level connections
• suggestImplementationOrder - Suggests optimal implementation order based on dependencies
• findRelatedTasks - Finds all tasks related to a given ID through various relationships
• getContextWithDependencies - Enhanced version of getContextById with all related context

Smart Implementation Support

• generateSmartImplementationBrief - Generates comprehensive implementation briefs with testing strategies and edge cases
• generateProjectHealthReport - Comprehensive project health analysis with recommendations

Documentation Quality Assurance

• validateDocumentationCompleteness - Comprehensive validation of documentation quality and completeness
• findOrphanedReferences - Finds IDs that are referenced but don't exist
• validateIdConsistency - Validates ID format consistency and checks for duplicates
• checkDocumentationGaps - Identifies missing information and gaps in documentation sections
• validateCrossReferences - Validates the integrity and completeness of cross-references

Advanced Task Dependency Management

• analyzeTaskDependencies - Comprehensive analysis of task dependencies, critical paths, and parallel development opportunities
• generateTaskDependencyVisualization - Creates visual Mermaid diagrams of task dependencies with status indicators
• generateTaskSchedule - Provides intelligent task scheduling recommendations with phases and timelines
• identifyNextCriticalTasks - Identifies the most important tasks to work on next based on dependencies and impact

Technical Decision & Feasibility Analysis

• extractTechnicalDecisions - Extracts and analyzes key technical decisions, technology stack, and architecture patterns
• generateTechnicalSummary - Creates concise technical overviews with key technologies and complexity assessment
• analyzeInfrastructureRequirements - Identifies infrastructure, hosting, security, and compliance requirements
• assessTechnicalFeasibility - Assesses overall technical feasibility based on technology choices and requirements

Missing Requirements Detection

• identifyMissingRequirements - Comprehensive analysis to identify missing user stories, incomplete acceptance criteria, security gaps, and other requirements issues
• analyzeRequirementsCompleteness - Detailed breakdown of requirements completeness across different categories
• suggestMissingUserStories - Analyzes features and suggests user stories that might be missing
• identifyUncoveredUseCases - Identifies important use cases that might not be covered by existing user stories

Development Tools

• debug_getProjectMap - Inspect internal project mapping (debug only)

Usage

⚠️ IMPORTANT: Place this MCP server in the root directory of your InitRepo project (or any directory containing InitRepo documentation). The server will automatically discover and analyze your documentation.

🚀 Quick Start with InitRepo Project:

# 1. Navigate to your InitRepo project
cd /path/to/your/initrepo-project

# 2. Install and run the MCP server
npm install -g initrepo-mcp
initrepo-mcp

# 3. Configure your AI assistant (Claude Desktop, VS Code, etc.)
# 4. Ask intelligent questions about your project!

📋 Example Queries:

"Analyze my project requirements and identify any gaps"
"Show me the critical path for implementation"
"What are the main technical risks in my architecture?"
"Generate an implementation brief for T-001"
"Validate my documentation completeness"

🎯 InitRepo-Specific Intelligence:

The server understands InitRepo methodology and can:

• Map epic-to-task relationships using InitRepo ID system
• Analyze acceptance criteria completeness
• Identify missing user stories for features
• Track task dependencies and blocking items
• Assess technical feasibility of your stack choices
• Provide implementation guidance tailored to InitRepo structure

Usage Examples

Basic Context Retrieval

{
  "method": "tools/call",
  "params": {
    "name": "getContextById",
    "arguments": {"id": "T-001"}
  }
}

Epic Progress Tracking

{
  "method": "tools/call", 
  "params": {
    "name": "getEpicProgress",
    "arguments": {"epicId": "E-001"}
  }
}

Dependency Analysis

{
  "method": "tools/call",
  "params": {
    "name": "analyzeDependencies",
    "arguments": {"id": "T-015"}
  }
}

Smart Implementation Brief

{
  "method": "tools/call",
  "params": {
    "name": "generateSmartImplementationBrief",
    "arguments": {
      "id": "T-001",
      "includeTestingStrategy": true,
      "includeEdgeCases": true,
      "format": "markdown"
    }
  }
}

Project Health Assessment

{
  "method": "tools/call",
  "params": {
    "name": "generateProjectHealthReport",
    "arguments": {
      "includeRecommendations": true,
      "focusOn": "all"
    }
  }
}

Relationship Mapping

{
  "method": "tools/call",
  "params": {
    "name": "getRelationshipMap",
    "arguments": {
      "id": "F-001",
      "depth": 2
    }
  }
}

Documentation Validation

{
  "method": "tools/call",
  "params": {
    "name": "validateDocumentationCompleteness",
    "arguments": {
      "includeRecommendations": true
    }
  }
}

Find Orphaned References

{
  "method": "tools/call",
  "params": {
    "name": "findOrphanedReferences",
    "arguments": {
      "severityFilter": "high"
    }
  }
}

Check Documentation Gaps

{
  "method": "tools/call",
  "params": {
    "name": "checkDocumentationGaps",
    "arguments": {
      "focusSection": "business_analysis.md"
    }
  }
}

Validate Cross-References

{
  "method": "tools/call",
  "params": {
    "name": "validateCrossReferences",
    "arguments": {}
  }
}

Task Dependency Analysis

{
  "method": "tools/call",
  "params": {
    "name": "analyzeTaskDependencies",
    "arguments": {
      "taskIds": ["T-001", "T-002", "T-003"]
    }
  }
}

Task Dependency Visualization

{
  "method": "tools/call",
  "params": {
    "name": "generateTaskDependencyVisualization",
    "arguments": {}
  }
}

Task Scheduling

{
  "method": "tools/call",
  "params": {
    "name": "generateTaskSchedule",
    "arguments": {
      "taskIds": ["T-001", "T-002", "T-003", "T-004", "T-005"]
    }
  }
}

Next Critical Tasks

{
  "method": "tools/call",
  "params": {
    "name": "identifyNextCriticalTasks",
    "arguments": {
      "limit": 3
    }
  }
}

Technical Decision Extraction

{
  "method": "tools/call",
  "params": {
    "name": "extractTechnicalDecisions",
    "arguments": {}
  }
}

Technical Summary

{
  "method": "tools/call",
  "params": {
    "name": "generateTechnicalSummary",
    "arguments": {}
  }
}

Infrastructure Requirements

{
  "method": "tools/call",
  "params": {
    "name": "analyzeInfrastructureRequirements",
    "arguments": {}
  }
}

Technical Feasibility Assessment

{
  "method": "tools/call",
  "params": {
    "name": "assessTechnicalFeasibility",
    "arguments": {}
  }
}

Missing Requirements Analysis

{
  "method": "tools/call",
  "params": {
    "name": "identifyMissingRequirements",
    "arguments": {}
  }
}

Requirements Completeness Check

{
  "method": "tools/call",
  "params": {
    "name": "analyzeRequirementsCompleteness",
    "arguments": {
      "focusArea": "userStories"
    }
  }
}

Missing User Stories Suggestions

{
  "method": "tools/call",
  "params": {
    "name": "suggestMissingUserStories",
    "arguments": {
      "featureId": "F-001"
    }
  }
}

Uncovered Use Cases

{
  "method": "tools/call",
  "params": {
    "name": "identifyUncoveredUseCases",
    "arguments": {}
  }
}

Configuration

Development Commands

# Build the TypeScript project
npm run build

# Start the MCP server
npm run start:mcp

# Development with hot-reload
npm run build && npm run start:mcp

Environment Setup

The server automatically detects your project structure and documentation files. Ensure your project follows the InitRepo documentation standards for optimal functionality.

Architecture

Core Components

• ProjectAnalysisEngine: Parses documentation and builds ID relationship maps
• Context Retrieval System: Extracts precise context blocks by ID
• Dependency Analyzer: Maps relationships between project elements
• Progress Tracker: Calculates completion metrics for epics and tasks

Performance Features

• Just-in-Time Initialization: Analysis engine loads only when needed
• Intelligent Caching: Parsed data cached for subsequent requests
• Efficient Parsing: Line-by-line analysis with hierarchy awareness

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "initrepo-mcp": {
      "command": "node",
      "args": ["path/to/initrepo-mcp/dist/packages/mcp-server/src/index.js"],
      "cwd": "/path/to/your/project"
    }
  }
}

Troubleshooting

Common Issues

1. "Could not find item with ID" errors

   • Ensure your documentation follows InitRepo ID format
   • Check that referenced IDs exist in your documents
   • Verify files are in the project root directory

2. InitRepo CLI tools not working

   • Install initrepo-cli globally: npm install -g initrepo-cli
   • Ensure CLI is in your system PATH
   • Check project compatibility with CLI version

3. Empty project map

   • Verify documentation files exist and contain proper IDs
   • Check file permissions and accessibility
   • Review console output for parsing errors

Debug Mode

Use the debug tool to inspect internal state:

{
  "method": "tools/call",
  "params": {
    "name": "debug_getProjectMap",
    "arguments": {}
  }
}

Requirements

• InitRepo Documentation Suite: Complete structured documentation from initrepo.com
• InitRepo CLI: For enhanced project structure and task management features
• Proper ID System: All documents must use InitRepo ID formatting standards
• Node.js 16+: Runtime environment
• TypeScript: For development and building

Support

For issues and questions:

• Review the troubleshooting section above
• Check that all prerequisites are installed
• Ensure your project follows InitRepo documentation standards
• Verify MCP client configuration

License

This project is dual-licensed:

• AGPL-3.0 (default) - Free for open source and internal use
• Commercial License - Available for proprietary/commercial use

See LICENSE for complete licensing information and LICENSE-AGPL for AGPL-3.0 terms.

Need a commercial license? Contact us at [email protected]

Powered by the InitRepo ecosystem - Transform your project documentation into intelligent, queryable knowledge for AI agents.

This MCP server is designed specifically for projects using the InitRepo documentation methodology and tooling suite. For best results, generate your project documentation using the complete InitRepo workflow from initrepo.com.