> ## Documentation Index
> Fetch the complete documentation index at: https://docs.initrepo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Troubleshooting Guide

> Comprehensive troubleshooting guide for InitRepo MCP Server issues, common problems, and solutions

## Troubleshooting & Support

### Common Issues

**Connection Problems:**

**MCP Server Not Detected:**

```bash theme={null}
# 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](https://www.initrepo.com) to generate proper documentation
* **Verification**: Check that files are in `/docs` folder and contain InitRepo IDs

**Missing Context Errors:**

```bash theme={null}
# 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:**

```bash theme={null}
# Health check
curl https://mcp.initrepo.com/health

# Server status
initrepo-mcp status

# Configuration validation
initrepo-mcp validate-config
```

**Debug Mode:**

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Server Performance Issues">
    **Symptoms:** Slow response times, high memory usage, timeouts

    **Solutions:**

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="Tool-Specific Issues">
    **Context Generation Problems:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    # Reset progress tracking
    initrepo-mcp reset-progress

    # Validate progress data
    initrepo-mcp validate-progress

    # Sync with latest documentation
    initrepo-mcp sync-progress
    ```
  </Accordion>

  <Accordion title="Integration Problems">
    **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:**

    ```bash theme={null}
    # Test terminal client
    initrepo-mcp-client --version

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

    # Test basic connectivity
    initrepo-mcp-client ping
    ```
  </Accordion>
</AccordionGroup>

### Configuration Troubleshooting

**Environment Variables:**

```bash theme={null}
# 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:**

```json theme={null}
// 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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](https://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:**

* **Email**: [support@initrepo.com](mailto:support@initrepo.com)
* **Community Discord**: [discord.gg/qxWpbhbe93](https://discord.gg/qxWpbhbe93)
* **Enterprise Support**: [enterprise@initrepo.com](mailto:enterprise@initrepo.com)

**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:**

```bash theme={null}
# Collect system details
uname -a
node --version
npm --version

# MCP server version
initrepo-mcp --version

# Environment details
env | grep -i initrepo
```

**Log Files:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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