Skip to main content

​
Troubleshooting & Support

​
Common Issues

Connection Problems: MCP Server Not Detected: 
# Verify installation
npm list -g initrepo-mcp

# Check if command is available
which initrepo-mcp

# Restart your IDE/editor
# For VS Code: Reload Window (Ctrl/Cmd + Shift + P)
Authentication Issues:
  • Expired Tokens: Re-authenticate through the provided interface
  • Invalid Credentials: Verify your InitRepo account credentials
  • Permission Errors: Check your access level for the project
  • Network Issues: Ensure stable internet connection for HTTP transport
Documentation Structure Issues: “No InitRepo documentation found” Error:
  • Critical: This server ONLY works with InitRepo-generated documentation
  • Solution: Visit initrepo.com to generate proper documentation
  • Verification: Check that files are in /docs folder and contain InitRepo IDs
Missing Context Errors: 
# Check documentation structure
ls -la docs/

# Verify ID format
grep -r "T-001" docs/

# Validate documentation completeness
initrepo-mcp validate-docs

​
Diagnostic Tools

Built-in Diagnostics: 
# Health check
curl https://mcp.initrepo.com/health

# Server status
initrepo-mcp status

# Configuration validation
initrepo-mcp validate-config
Debug Mode: 
{
  "method": "tools/call",
  "params": {
    "name": "debug_getProjectMap",
    "arguments": {}
  }
}
Performance Monitoring:
  • Response Times: Monitor query response times
  • Memory Usage: Track server resource consumption
  • Error Rates: Monitor failure rates and patterns
  • Usage Analytics: Analyze tool usage patterns

​
Advanced Troubleshooting

Symptoms: Slow response times, high memory usage, timeoutsSolutions:
# Check system resources
top -p $(pgrep -f initrepo-mcp)

# Restart server with debug mode
initrepo-mcp --debug --verbose

# Clear cache and restart
initrepo-mcp clear-cache
initrepo-mcp restart
Performance Optimization:
  • Increase memory allocation: NODE_OPTIONS="--max-old-space-size=4096"
  • Enable caching: Set environment variable INITREPO_CACHE_ENABLED=true
  • Reduce analysis depth for large projects
Context Generation Problems:
# Test basic context retrieval
initrepo-mcp query "getContext T-001"

# Check documentation format
initrepo-mcp validate-format docs/

# Regenerate context cache
initrepo-mcp rebuild-context-cache
Progress Tracking Issues:
# Reset progress tracking
initrepo-mcp reset-progress

# Validate progress data
initrepo-mcp validate-progress

# Sync with latest documentation
initrepo-mcp sync-progress
IDE Connection Issues:
  • Verify configuration syntax in IDE settings
  • Check firewall and network connectivity
  • Ensure compatible IDE version
  • Validate API endpoint URLs
Terminal Integration Issues:
# Test terminal client
initrepo-mcp-client --version

# Check configuration file
cat ~/.initrepo/config.json

# Test basic connectivity
initrepo-mcp-client ping

​
Configuration Troubleshooting

Environment Variables: 
# Required environment variables
export INITREPO_API_KEY="your-api-key"
export INITREPO_PROJECT_ID="your-project-id"
export INITREPO_DOCS_PATH="./docs"

# Optional performance tuning
export INITREPO_CACHE_SIZE="2GB"
export INITREPO_MAX_CONCURRENCY="10"
export INITREPO_TIMEOUT="60000"
Configuration File Issues: 
// Check .initrepo/config.json
{
  "api": {
    "endpoint": "https://api.initrepo.com",
    "timeout": 30000
  },
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "1GB"
  },
  "logging": {
    "level": "info",
    "file": "/var/log/initrepo-mcp.log"
  }
}

​
Network and Connectivity

Firewall Configuration: 
# Allow MCP server ports
sudo ufw allow 3000/tcp
sudo ufw allow 8080/tcp

# Test connectivity
curl -v https://mcp.initrepo.com/health
telnet mcp.initrepo.com 443
Proxy Configuration: 
# Set proxy environment variables
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.local"

# Test proxy connectivity
curl --proxy $HTTP_PROXY https://mcp.initrepo.com/health

​
Getting Help

Self-Service Resources:
  • Documentation: Comprehensive guides and API references at docs.initrepo.com
  • Community Forums: Peer support and knowledge sharing
  • Video Tutorials: Step-by-step setup and usage guides
  • FAQ Database: Common questions and solutions
Professional Support:
  • Priority Support: 24/7 technical assistance for enterprise customers
  • Custom Integrations: Bespoke development and integration services
  • Training Programs: Team onboarding and advanced usage training
  • Consulting Services: Architecture review and optimization guidance

​
Support Contact Information

For Technical Issues: Response Times:
  • Community Support: 24-48 hours
  • Priority Support: 4-8 hours
  • Enterprise Support: 1-2 hours
  • Critical Issues: 30 minutes

​
Diagnostic Information Collection

System Information: 
# Collect system details
uname -a
node --version
npm --version

# MCP server version
initrepo-mcp --version

# Environment details
env | grep -i initrepo
Log Files: 
# Server logs
tail -f /var/log/initrepo-mcp.log

# IDE integration logs
# Check IDE logs for MCP-related errors

# Network logs
tcpdump -i any port 3000 or port 8080

​
Preventive Maintenance

Regular Health Checks: 
# Daily health check script
#!/bin/bash
# Check server status
curl -f https://mcp.initrepo.com/health

# Validate configuration
initrepo-mcp validate-config

# Check disk space
df -h | grep -E "(Avail|Use%)"

# Monitor memory usage
ps aux | grep initrepo-mcp | grep -v grep
Automated Monitoring:
  • Set up log rotation for MCP server logs
  • Monitor server response times
  • Track error rates and patterns
  • Regular backup of configuration files
Last Updated: December 2024 Version: 1.0.0