flyer-crawler.projectium.com/README.vscode.md

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

{
  "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):

{
  "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):

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

Configuration (Claude Code):

{
  "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):

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

Configuration (Claude Code):

{
  "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):

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

Configuration (Claude Code):

{
  "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):

{
  "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):

{
  "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:

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

   pip install uvx
   

Testing MCP Servers

Test Podman Connection

podman ps
# Should list running containers

Test Gitea API Access

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

Test Database Container

podman exec flyer-crawler-postgres psql -U postgres -d flyer_crawler_dev -c "SELECT version();"
# Should return PostgreSQL version

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:

   podman machine list
   

2. Ensure Podman Desktop is running
3. Verify Docker socket is accessible:

   podman ps
   

Gitea MCP Connection Issues

1. Verify token has correct permissions
2. Check network connectivity to Gitea server:

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

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

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

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

3. Add to Claude Code (settings.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
• Gitea API Documentation
• Podman Desktop
• Claude Code Documentation

Maintenance

Regular Tasks

• Monthly: Rotate Gitea access tokens
• Weekly: Update MCP server packages:

  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:

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

   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:

• 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