# VS Code Configuration for Flyer Crawler Project

This document describes the VS Code setup for this project, including MCP (Model Context Protocol) server configurations for both Gemini Code and Claude Code.

## Overview

This project uses VS Code with AI coding assistants (Gemini Code and Claude Code) that connect to various MCP servers for enhanced capabilities like container management, repository access, and file system operations.

## MCP Server Architecture

MCP (Model Context Protocol) allows AI assistants to interact with external tools and services. Both Gemini Code and Claude Code are configured to use the same set of MCP servers.

### Configuration Files

- **Gemini Code**: `%APPDATA%\Code\User\mcp.json`
- **Claude Code**: `%USERPROFILE%\.claude\settings.json`

## Configured MCP Servers

### 1. Gitea MCP Servers

Access to multiple Gitea instances for repository management, code search, issue tracking, and CI/CD workflows.

#### Gitea Projectium (Primary)

- **Host**: `https://gitea.projectium.com`
- **Purpose**: Main production Gitea server
- **Capabilities**:
  - Repository browsing and code search
  - Issue and PR management
  - CI/CD workflow access
  - Repository cloning and management

#### Gitea Torbonium

- **Host**: `https://gitea.torbonium.com`
- **Purpose**: Development/testing Gitea instance
- **Capabilities**: Same as Gitea Projectium

#### Gitea LAN

- **Host**: `https://gitea.torbolan.com`
- **Purpose**: Local network Gitea instance
- **Status**: Disabled (requires token configuration)

**Executable Location**: `d:\gitea-mcp\gitea-mcp.exe`

**Configuration Example** (Gemini Code - mcp.json):

```json
{
  "servers": {
    "gitea-projectium": {
      "command": "d:\\gitea-mcp\\gitea-mcp.exe",
      "args": ["run", "-t", "stdio"],
      "env": {
        "GITEA_HOST": "https://gitea.projectium.com",
        "GITEA_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
```

**Configuration Example** (Claude Code - settings.json):

```json
{
  "mcpServers": {
    "gitea-projectium": {
      "command": "d:\\gitea-mcp\\gitea-mcp.exe",
      "args": ["run", "-t", "stdio"],
      "env": {
        "GITEA_HOST": "https://gitea.projectium.com",
        "GITEA_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
```

### 2. Podman/Docker MCP Server

Manages local containers via Podman Desktop (using Docker-compatible API).

- **Purpose**: Container lifecycle management
- **Socket**: `npipe:////./pipe/docker_engine` (Windows named pipe)
- **Capabilities**:
  - List, start, stop containers
  - Execute commands in containers
  - View container logs
  - Inspect container status and configuration

**Current Containers** (for this project):

- `flyer-crawler-postgres` - PostgreSQL 15 + PostGIS on port 5432
- `flyer-crawler-redis` - Redis on port 6379

**Configuration** (Gemini Code - mcp.json):

```json
{
  "servers": {
    "podman": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-docker"],
      "env": {
        "DOCKER_HOST": "npipe:////./pipe/docker_engine"
      }
    }
  }
}
```

**Configuration** (Claude Code):

```json
{
  "mcpServers": {
    "podman": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-docker"],
      "env": {
        "DOCKER_HOST": "npipe:////./pipe/docker_engine"
      }
    }
  }
}
```

### 3. Filesystem MCP Server

Direct file system access to the project directory.

- **Purpose**: Read and write files in the project
- **Scope**: `D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com`
- **Capabilities**:
  - Read file contents
  - Write/edit files
  - List directory contents
  - Search files

**Configuration** (Gemini Code - mcp.json):

```json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "D:\\gitea\\flyer-crawler.projectium.com\\flyer-crawler.projectium.com"
      ]
    }
  }
}
```

**Configuration** (Claude Code):

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "D:\\gitea\\flyer-crawler.projectium.com\\flyer-crawler.projectium.com"
      ]
    }
  }
}
```

### 4. Fetch MCP Server

Web request capabilities for documentation lookups and API testing.

- **Purpose**: Make HTTP requests
- **Capabilities**:
  - Fetch web pages and APIs
  - Download documentation
  - Test endpoints

**Configuration** (Gemini Code - mcp.json):

```json
{
  "servers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}
```

**Configuration** (Claude Code):

```json
{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}
```

### 5. Chrome DevTools MCP Server (Optional)

Browser automation and debugging capabilities.

- **Purpose**: Automated browser testing
- **Status**: Disabled by default
- **Capabilities**:
  - Browser automation
  - Screenshot capture
  - DOM inspection
  - Network monitoring

**Configuration** (when enabled):

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--headless",
        "false",
        "--isolated",
        "false",
        "--channel",
        "stable"
      ]
    }
  }
}
```

### 6. Markitdown MCP Server (Optional)

Document conversion capabilities.

- **Purpose**: Convert various document formats to Markdown
- **Status**: Disabled by default
- **Requires**: Python with `uvx` installed
- **Capabilities**:
  - Convert PDFs to Markdown
  - Convert Word documents
  - Convert other document formats

**Configuration** (when enabled):

```json
{
  "mcpServers": {
    "markitdown": {
      "command": "uvx",
      "args": ["markitdown-mcp==0.0.1a4"]
    }
  }
}
```

## Prerequisites

### For Podman MCP

1. **Podman Desktop** installed and running
2. Podman machine initialized and started:
   ```powershell
   podman machine init
   podman machine start
   ```

### For Gitea MCP

1. **Gitea MCP executable** at `d:\gitea-mcp\gitea-mcp.exe`
2. **Gitea Access Tokens** with appropriate permissions:
   - `repo` - Full repository access
   - `write:user` - User profile access
   - `read:organization` - Organization access

### For Chrome DevTools MCP

1. **Chrome browser** installed (stable channel)
2. **Node.js 18+** for npx execution

### For Markitdown MCP

1. **Python 3.8+** installed
2. **uvx** (universal virtualenv executor):
   ```powershell
   pip install uvx
   ```

## Testing MCP Servers

### Test Podman Connection

```powershell
podman ps
# Should list running containers
```

### Test Gitea API Access

```powershell
curl -H "Authorization: token YOUR_TOKEN" https://gitea.projectium.com/api/v1/user
# Should return your user information
```

### Test Database Container

```powershell
podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT version();"
# Should return PostgreSQL version
### Claude Code Extension Auto-Update Issues

#### Problem: Version 2.1.15 Crashes on CPUs Without AVX Support

Claude Code version 2.1.15 introduced a regression that causes crashes on CPUs that do not support AVX (Advanced Vector Extensions) instructions. The error manifests as:

```

Illegal instruction (core dumped)

```

or similar AVX-related illegal instruction errors when the extension tries to start.

**Affected**: CPUs without AVX support (typically older processors or certain VMs)
**Working Version**: 2.1.11 (and earlier)
**Broken Version**: 2.1.15+

#### Solution: Disable Auto-Updates for Claude Code Extension

The VS Code right-click menu option "Disable Auto Update" for extensions may be greyed out and non-functional. Use the settings.json workaround instead.

**Step 1: Open VS Code Settings JSON**

Press `Ctrl+Shift+P` and type "Preferences: Open User Settings (JSON)" or manually edit:

```

C:\Users\<username>\AppData\Roaming\Code\User\settings.json

````

**Step 2: Add the Extension to Ignore List**

Add the following setting to your `settings.json`:

```json
{
  "extensions.ignoreAutoUpdate": ["anthropic.claude-code"]
}
````

If you already have other settings, add it within the existing JSON object:

```json
{
  "editor.fontSize": 14,
  "extensions.ignoreAutoUpdate": ["anthropic.claude-code"],
  "other.settings": "value"
}
```

**Step 3: Downgrade to Working Version**

If you're already on 2.1.15, you need to downgrade:

1. Open the Extensions view (`Ctrl+Shift+X`)
2. Find "Claude Code" in the list
3. Click the gear icon next to the extension
4. Select "Install Another Version..."
5. Choose version **2.1.11** from the list
6. Wait for installation to complete
7. Reload VS Code when prompted

**Step 4: Verify Configuration**

To verify the setting is working:

1. Open VS Code Settings JSON and confirm `extensions.ignoreAutoUpdate` includes `anthropic.claude-code`
2. Check the Extensions view - Claude Code should show version 2.1.11
3. VS Code should no longer prompt to update Claude Code automatically

#### Updating Later When Bug is Fixed

Once Anthropic releases a fixed version:

1. **Remove the ignore setting** from `settings.json`:

   ```json
   // Remove or comment out:
   // "extensions.ignoreAutoUpdate": ["anthropic.claude-code"]
   ```

2. **Manually update** the extension:
   - Open Extensions view (`Ctrl+Shift+X`)
   - Find Claude Code
   - Click "Update" or use the gear menu to install a specific version

3. **Or re-enable auto-updates** by removing the extension from the ignore list, then:
   - Reload VS Code
   - The extension will update automatically

#### Alternative: Pin to Specific Version

If you prefer to pin to a specific version rather than just disabling auto-updates:

```json
{
  "extensions.autoUpdate": "onlyEnabledExtensions",
  "extensions.ignoreAutoUpdate": ["anthropic.claude-code"]
}
```

This allows other extensions to update automatically while keeping Claude Code locked.

#### Checking Current Extension Version

To verify which version is installed:

1. Open Extensions view (`Ctrl+Shift+X`)
2. Find "Claude Code" by Anthropic
3. The version number appears below the extension name
4. Or click on the extension to see full details including version history

````

## Security Notes

### Token Management

- **Never commit tokens** to version control
- Store tokens in environment variables or secure password managers
- Rotate tokens periodically
- Use minimal required permissions

### Access Tokens in Configuration Files

The configuration files (`mcp.json` and `settings.json`) contain sensitive access tokens. These files should:

- Be added to `.gitignore`
- Have restricted file permissions
- Be backed up securely
- Be updated when tokens are rotated

### Current Security Setup

- `%APPDATA%\Code\User\mcp.json` - Gitea tokens embedded
- `%USERPROFILE%\.claude\settings.json` - Gitea tokens embedded
- Both files are in user-specific directories with appropriate Windows ACLs

## Troubleshooting

### Podman MCP Not Working

1. Check Podman machine status:
   ```powershell
   podman machine list
````

2. Ensure Podman Desktop is running
3. Verify Docker socket is accessible:
   ```powershell
   podman ps
   ```

### Gitea MCP Connection Issues

1. Verify token has correct permissions
2. Check network connectivity to Gitea server:
   ```powershell
   curl https://gitea.projectium.com/api/v1/version
   ```
3. Ensure `gitea-mcp.exe` is not blocked by antivirus/firewall

### VS Code Extension Issues

1. **Reload Window**: Press `Ctrl+Shift+P` → "Developer: Reload Window"
2. **Check Extension Logs**: View → Output → Select extension from dropdown
3. **Verify JSON Syntax**: Ensure both config files have valid JSON

### MCP Server Not Loading

1. Check config file syntax with JSON validator
2. Verify executable paths are correct (use forward slashes or escaped backslashes)
3. Ensure required dependencies are installed (Node.js, Python, etc.)
4. Check VS Code developer console for errors: Help → Toggle Developer Tools

## Adding New MCP Servers

To add a new MCP server to both Gemini Code and Claude Code:

1. **Install the MCP server** (if it's an npm package):

   ```powershell
   npm install -g @modelcontextprotocol/server-YOUR-SERVER
   ```

2. **Add to Gemini Code** (`mcp.json`):

   ```json
   {
     "servers": {
       "your-server-name": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-YOUR-SERVER"],
         "env": {}
       }
     }
   }
   ```

3. **Add to Claude Code** (`settings.json`):

   ```json
   {
     "mcpServers": {
       "your-server-name": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-YOUR-SERVER"],
         "env": {}
       }
     }
   }
   ```

4. **Reload VS Code**

## Current Project Integration

### ADR Implementation Status

- **ADR-0002**: Transaction Management ✅ Enforced
- **ADR-0003**: Input Validation ✅ Enforced with URL validation

### Database Setup

- PostgreSQL 15 + PostGIS running in container
- 63 tables created
- URL constraints active:
  - `flyers_image_url_check` enforces `^https?://.*`
  - `flyers_icon_url_check` enforces `^https?://.*`

### Development Workflow

1. Start containers: `podman start flyer-crawler-postgres flyer-crawler-redis`
2. Use MCP servers to manage development environment
3. AI assistants can:
   - Manage containers via Podman MCP
   - Access repository via Gitea MCP
   - Edit files via Filesystem MCP
   - Fetch documentation via Fetch MCP

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Gitea API Documentation](https://docs.gitea.com/api/1.22/)
- [Podman Desktop](https://podman-desktop.io/)
- [Claude Code Documentation](https://docs.anthropic.com/claude-code)

## Maintenance

### Regular Tasks

- **Monthly**: Rotate Gitea access tokens
- **Weekly**: Update MCP server packages:
  ```powershell
  npm update -g @modelcontextprotocol/server-*
  ```
- **As Needed**: Update Gitea MCP executable when new version is released

### Backup Configuration

Recommended to backup these files regularly:

- `%APPDATA%\Code\User\mcp.json`
- `%USERPROFILE%\.claude\settings.json`

## Gitea Workflows and CI/CD

This project uses Gitea Actions for continuous integration and deployment. The workflows are located in `.gitea/workflows/`.

### Available Workflows

#### Automated Workflows

**deploy-to-test.yml** - Automated deployment to test environment

- **Trigger**: Automatically on every push to `main` branch
- **Runner**: `projectium.com` (self-hosted)
- **Process**:
  1. Version bump (patch) with `[skip ci]` tag
  2. TypeScript type-check and linting
  3. Run unit tests + integration tests + E2E tests
  4. Generate merged coverage report
  5. Build React frontend for test environment
  6. Deploy to `flyer-crawler-test.projectium.com`
  7. Restart PM2 processes for test environment
  8. Update database schema hash
- **Coverage Report**: https://flyer-crawler-test.projectium.com/coverage
- **Environment Variables**: Uses test database and Redis credentials

#### Manual Workflows

**deploy-to-prod.yml** - Manual deployment to production

- **Trigger**: Manual via workflow_dispatch
- **Confirmation Required**: Must type "deploy-to-prod"
- **Process**:
  1. Version bump (minor) for production release
  2. Check database schema hash (fails if mismatch)
  3. Build React frontend for production
  4. Deploy to `flyer-crawler.projectium.com`
  5. Restart PM2 processes (with version check)
  6. Update production database schema hash
- **Optional**: Force PM2 reload even if version matches

**manual-db-backup.yml** - Database backup workflow

- Creates timestamped backup of production database
- Stored in `/var/backups/postgres/`

**manual-db-restore.yml** - Database restore workflow

- Restores production database from backup file
- Requires confirmation and backup filename

**manual-db-reset-test.yml** - Reset test database

- Drops and recreates test database schema
- Used for testing schema migrations

**manual-db-reset-prod.yml** - Reset production database

- **DANGER**: Drops and recreates production database
- Requires multiple confirmations

**manual-deploy-major.yml** - Major version deployment

- Similar to deploy-to-prod but bumps major version
- For breaking changes or major releases

### Accessing Workflows via Gitea MCP

With the Gitea MCP server configured, AI assistants can:

- View workflow files
- Monitor workflow runs
- Check deployment status
- Review CI/CD logs
- Trigger manual workflows (via API)

**Example MCP Operations**:

```bash
# Via Gitea MCP, you can:
# - List recent workflow runs
# - View workflow logs
# - Check deployment status
# - Review test results
# - Monitor coverage reports
```

### Key Environment Variables for CI/CD

The workflows use these Gitea repository secrets:

**Database**:

- `DB_HOST` - PostgreSQL host
- `DB_USER` - Database user
- `DB_PASSWORD` - Database password
- `DB_DATABASE_PROD` - Production database name
- `DB_DATABASE_TEST` - Test database name

**Redis**:

- `REDIS_PASSWORD_PROD` - Production Redis password
- `REDIS_PASSWORD_TEST` - Test Redis password

**API Keys**:

- `VITE_GOOGLE_GENAI_API_KEY` - Production Gemini API key
- `VITE_GOOGLE_GENAI_API_KEY_TEST` - Test Gemini API key
- `GOOGLE_MAPS_API_KEY` - Google Maps Geocoding API key

**Authentication**:

- `JWT_SECRET` - JWT signing secret

### Schema Migration Process

The workflows use a schema hash comparison system:

1. **Hash Calculation**: SHA-256 hash of `sql/master_schema_rollup.sql`
2. **Storage**: Hashes stored in `public.schema_info` table
3. **Comparison**: On each deployment, current hash vs deployed hash
4. **Protection**: Deployment fails if schemas don't match

**Manual Migration Steps** (when schema changes):

1. Update `sql/master_schema_rollup.sql`
2. Run manual migration workflow or:
   ```bash
   psql -U <user> -d <database> -f sql/master_schema_rollup.sql
   ```
3. Deploy will update hash automatically

### PM2 Process Management

The workflows manage three PM2 processes per environment:

**Production** (`ecosystem.config.cjs --env production`):

- `flyer-crawler-api` - Express API server
- `flyer-crawler-worker` - Background job worker
- `flyer-crawler-analytics-worker` - Analytics processor

**Test** (`ecosystem.config.cjs --env test`):

- `flyer-crawler-api-test` - Test Express API server
- `flyer-crawler-worker-test` - Test background worker
- `flyer-crawler-analytics-worker-test` - Test analytics worker

**Process Cleanup**:

- **2026-01-22**: Added Claude Code extension auto-update troubleshooting
  - Documented AVX CPU crash bug in version 2.1.15
  - Added workaround using `extensions.ignoreAutoUpdate` setting
  - Included instructions for downgrading and re-enabling updates
- Workflows automatically delete errored/stopped processes
- Version comparison prevents unnecessary reloads
- Force reload option available for production

### Monitoring Deployment via MCP

Using Gitea MCP, you can monitor deployments in real-time:

1. **Check Workflow Status**:
   - View running workflows
   - See step-by-step progress
   - Read deployment logs

2. **PM2 Process Monitoring**:
   - Workflows output PM2 status after deployment
   - View process IDs, memory usage, uptime
   - Check recent logs (last 20 lines)

3. **Coverage Reports**:
   - Automatically published to test environment
   - HTML reports with detailed breakdown
   - Merged coverage from unit + integration + E2E + server

### Development Workflow Integration

**Local Development** → **Push to main** → **Auto-deploy to test** → **Manual deploy to prod**

1. Develop locally with Podman containers
2. Commit and push to `main` branch
3. Gitea Actions automatically:
   - Runs all tests
   - Generates coverage
   - Deploys to test environment
4. Review test deployment at https://flyer-crawler-test.projectium.com
5. Manually trigger production deployment when ready

### Using MCP for Deployment Tasks

With the configured MCP servers, you can:

**Via Gitea MCP**:

- Trigger manual workflows
- View deployment history
- Monitor test results
- Access workflow logs

**Via Podman MCP**:

- Inspect container logs (for local testing)
- Manage local database containers
- Test migrations locally

**Via Filesystem MCP**:

- Review workflow files
- Edit deployment scripts
- Update ecosystem config

## Version History

- **2026-01-07**: Initial MCP configuration for Gemini Code and Claude Code
  - Added Gitea MCP servers (projectium, torbonium, lan)
  - Added Podman MCP server
  - Added Filesystem, Fetch MCP servers
  - Configured Chrome DevTools and Markitdown (disabled by default)
  - Documented Gitea workflows and CI/CD pipeline