3gpp-mcp-server/docs/installation.md

MCP Server for querying 3GPP telecom protocol specifications

# Installation Guide

## System Requirements

### Minimum Requirements
- **Operating System**: Linux, macOS, Windows 10/11, or Windows WSL2
- **Node.js**: Version 18.0.0 or higher
- **Memory**: 2GB RAM minimum, 4GB recommended
- **Storage**: 1GB for server code, additional space for TSpec-LLM dataset (13.5GB optional)
- **Network**: Internet connection for dataset download (optional)

### Recommended Requirements
- **Node.js**: Version 20.0.0 or higher
- **Memory**: 8GB RAM for large dataset operations
- **Storage**: 20GB free space (includes dataset and indices)
- **CPU**: Multi-core processor for better performance

### Dependencies
- **Git**: For cloning repositories and dataset management
- **npm**: Node.js package manager (included with Node.js)
- **Git LFS**: For large file handling (dataset download only)

## Installation Methods

### Method 1: Quick Installation (Recommended)

**Step 1: Clone the Repository**
```bash
git clone https://github.com/your-org/3gpp-mcp-server.git
cd 3gpp-mcp-server
```

**Step 2: Install Dependencies**
```bash
npm install
```

**Step 3: Build the Project**
```bash
npm run build
```

**Step 4: Verify Installation**
```bash
npm start
```
The server should start and display: `3GPP MCP Server running on stdio`

### Method 2: Development Installation

**Step 1: Prerequisites Check**
```bash
# Verify Node.js version
node --version  # Should be 18.0.0+

# Verify npm version
npm --version   # Should be 8.0.0+
```

**Step 2: Clone and Setup**
```bash
git clone https://github.com/your-org/3gpp-mcp-server.git
cd 3gpp-mcp-server

# Install all dependencies including dev dependencies
npm install --include=dev

# Build TypeScript
npm run build

# Run in development mode
npm run dev
```

**Step 3: Development Environment Setup**
```bash
# Install global TypeScript (optional)
npm install -g typescript

# Install development tools
npm install -g ts-node nodemon

# Run with hot reload
npm run dev
```

### Method 3: Docker Installation

**Step 1: Create Dockerfile**
```dockerfile
FROM node:20-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm ci --only=production

# Copy source code
COPY . .

# Build application
RUN npm run build

# Expose port (if needed)
EXPOSE 3000

# Start server
CMD ["npm", "start"]
```

**Step 2: Build and Run Container**
```bash
# Build Docker image
docker build -t 3gpp-mcp-server .

# Run container
docker run -it 3gpp-mcp-server
```

## Dataset Setup (Optional)

The server works with mock data by default. For full functionality, install the TSpec-LLM dataset.

### Prerequisites for Dataset Download
```bash
# Install Git LFS
# On Ubuntu/Debian:
sudo apt install git-lfs

# On macOS:
brew install git-lfs

# On Windows:
# Download from: https://git-lfs.github.io/

# Initialize Git LFS
git lfs install
```

### Download TSpec-LLM Dataset
```bash
# Clone the dataset (this will take time - 13.5GB)
cd data
git clone https://huggingface.co/datasets/rasoul-nikbakht/TSpec-LLM

# Verify download
ls -la TSpec-LLM/
```

### Alternative: Partial Dataset Download
For testing or limited storage scenarios:
```bash
# Download only specific releases
git clone --depth 1 https://huggingface.co/datasets/rasoul-nikbakht/TSpec-LLM
cd TSpec-LLM

# Remove unwanted releases to save space
rm -rf Rel-8 Rel-9 Rel-10  # Keep only recent releases
```

## Configuration

### Basic Configuration

Create a configuration file (optional):
```bash
# Copy default configuration
cp config/default.json config/local.json

# Edit configuration
nano config/local.json
```

**Configuration Options**:
```json
{
  "server": {
    "name": "3gpp-mcp-server",
    "version": "1.0.0",
    "maxConcurrentQueries": 10
  },
  "data": {
    "tspecPath": "./data/TSpec-LLM",
    "enableMockData": true,
    "cacheEnabled": true,
    "cacheSize": 1000
  },
  "search": {
    "maxResults": 50,
    "defaultLimit": 10,
    "enableSemanticSearch": false
  },
  "logging": {
    "level": "info",
    "file": "logs/server.log"
  }
}
```

### Environment Variables

Create `.env` file for environment-specific settings:
```bash
# Create environment file
cat > .env << EOF
NODE_ENV=production
TSPEC_DATASET_PATH=/path/to/TSpec-LLM
MAX_CONCURRENT_QUERIES=10
ENABLE_SEMANTIC_SEARCH=false
LOG_LEVEL=info
EOF
```

**Available Environment Variables**:
- `NODE_ENV`: Environment (development/production)
- `TSPEC_DATASET_PATH`: Path to TSpec-LLM dataset
- `MAX_CONCURRENT_QUERIES`: Maximum concurrent search operations
- `ENABLE_SEMANTIC_SEARCH`: Enable vector embeddings (requires ChromaDB)
- `LOG_LEVEL`: Logging level (error/warn/info/debug)
- `CACHE_SIZE`: Number of cached search results
- `ENABLE_MOCK_DATA`: Use mock data when dataset unavailable

## Claude Desktop Integration

### Step 1: Locate Claude Desktop Configuration

**macOS**:
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows**:
```bash
%APPDATA%\Claude\claude_desktop_config.json
```

**Linux**:
```bash
~/.config/Claude/claude_desktop_config.json
```

### Step 2: Add Server Configuration

Edit the Claude Desktop configuration file:
```json
{
  "mcpServers": {
    "3gpp-server": {
      "command": "node",
      "args": ["/path/to/3gpp-mcp-server/dist/index.js"],
      "cwd": "/path/to/3gpp-mcp-server",
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### Step 3: Restart Claude Desktop

Close and reopen Claude Desktop. The 3GPP server should appear in the available tools.

### Step 4: Verify Integration

In Claude Desktop, try asking:
```
Can you search for 5G NAS authentication procedures?
```

Claude should use the 3GPP server to provide relevant specifications.

## Verification & Testing

### Basic Functionality Test
```bash
# Test server startup
npm start &
SERVER_PID=$!

# Wait for startup
sleep 2

# Kill test server
kill $SERVER_PID

echo "Server startup test: PASSED"
```

### Mock Data Test
```bash
# Test with mock data
NODE_ENV=test npm test
```

### Dataset Integration Test
```bash
# Test with actual dataset (if available)
TSPEC_DATASET_PATH=./data/TSpec-LLM npm test
```

### MCP Protocol Test
```bash
# Install MCP test client
npm install -g @modelcontextprotocol/cli

# Test server protocol compliance
mcp-client test stdio "node dist/index.js"
```

## Troubleshooting

### Common Installation Issues

**Issue**: Node.js version too old
```bash
# Solution: Update Node.js
# Using nvm (recommended):
nvm install 20
nvm use 20

# Or download from: https://nodejs.org/
```

**Issue**: TypeScript compilation errors
```bash
# Solution: Clear cache and rebuild
npm run clean
rm -rf node_modules package-lock.json
npm install
npm run build
```

**Issue**: Permission denied errors
```bash
# Solution: Fix permissions
sudo chown -R $(whoami) ~/.npm
chmod -R 755 .
```

### Dataset Download Issues

**Issue**: Git LFS not working
```bash
# Solution: Reinstall and configure Git LFS
git lfs install --force
git lfs pull
```

**Issue**: Disk space insufficient
```bash
# Solution: Partial dataset download
cd data/TSpec-LLM
git lfs ls-files | grep "Rel-1[89]" | git lfs pull -I -
```

**Issue**: Slow dataset download
```bash
# Solution: Use alternative mirrors or partial download
git clone --depth 1 --single-branch https://huggingface.co/datasets/rasoul-nikbakht/TSpec-LLM
```

### Runtime Issues

**Issue**: Server crashes with "ENOENT" error
```bash
# Solution: Verify file paths in configuration
ls -la data/TSpec-LLM/  # Check dataset path
ls -la dist/index.js    # Check build output
```

**Issue**: High memory usage
```bash
# Solution: Limit concurrent operations
export MAX_CONCURRENT_QUERIES=5
npm start
```

**Issue**: Slow search responses
```bash
# Solution: Enable caching
export CACHE_SIZE=2000
export ENABLE_MOCK_DATA=true  # For testing
npm start
```

### Claude Desktop Integration Issues

**Issue**: Server not appearing in Claude Desktop
```bash
# Solution: Check configuration file syntax
cat ~/.config/Claude/claude_desktop_config.json | jq .
```

**Issue**: Server fails to start from Claude Desktop
```bash
# Solution: Test absolute paths
node /full/path/to/3gpp-mcp-server/dist/index.js
```

## Performance Optimization

### Memory Optimization
```bash
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"
npm start
```

### Search Performance
```json
{
  "search": {
    "cacheEnabled": true,
    "cacheSize": 5000,
    "indexingEnabled": true,
    "maxConcurrentSearches": 5
  }
}
```

### Storage Optimization
```bash
# Compress logs
gzip logs/*.log

# Clean old cache files
find cache/ -name "*.cache" -mtime +7 -delete
```

## Security Considerations

### File Permissions
```bash
# Secure configuration files
chmod 600 config/local.json
chmod 600 .env

# Secure dataset directory
chmod -R 755 data/
```

### Network Security
```bash
# The server uses STDIO by default (no network exposure)
# For network deployment, consider:
# - HTTPS only
# - Authentication
# - Rate limiting
```

## Maintenance

### Regular Updates
```bash
# Update dependencies
npm update

# Rebuild after updates
npm run build

# Test after updates
npm test
```

### Log Rotation
```bash
# Setup log rotation (Linux/macOS)
sudo tee /etc/logrotate.d/3gpp-mcp-server << EOF
/path/to/3gpp-mcp-server/logs/*.log {
    daily
    rotate 30
    compress
    missingok
    notifempty
    create 644 $(whoami) $(whoami)
}
EOF
```

### Dataset Updates
```bash
# Update TSpec-LLM dataset
cd data/TSpec-LLM
git pull origin main

# Restart server to reload data
pm2 restart 3gpp-mcp-server  # If using PM2
```

This installation guide provides comprehensive steps for setting up the 3GPP MCP Server in various environments and configurations.