torbo/flyer-crawler.projectium.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4f06698dfd5e00a80c1c8dfd42bfac49a2371b3c
flyer-crawler.projectium.com/docs/SUBAGENT-INTEGRATIONS-REFERENCE.md

12 KiB
Raw Blame History

Integrations Subagent Reference

MCP Servers Overview

Server Purpose URL Tools Prefix
bugsink Production error tracking https://bugsink.projectium.com mcp__bugsink__*
localerrors Dev container errors http://127.0.0.1:8000 mcp__localerrors__*
devdb Dev PostgreSQL postgresql://postgres:postgres@127.0.0.1:5432/flyer_crawler_dev mcp__devdb__*
gitea-projectium Gitea API gitea.projectium.com mcp__gitea-projectium__*
gitea-torbonium Gitea API gitea.torbonium.com mcp__gitea-torbonium__*
podman Container management - mcp__podman__*
filesystem File system access - mcp__filesystem__*
memory Knowledge graph - mcp__memory__*
redis Cache management localhost:6379 mcp__redis__*

MCP Server Configuration

Global Config: ~/.claude/settings.json

Used for production/remote servers (HTTPS works fine).

{
  "mcpServers": {
    "bugsink": {
      "command": "node",
      "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
      "env": {
        "BUGSINK_URL": "https://bugsink.projectium.com",
        "BUGSINK_TOKEN": "<40-char-hex-token>"
      }
    }
  }
}

Project Config: .mcp.json

CRITICAL: Use project-level .mcp.json for localhost servers. Global config has issues loading localhost stdio MCP servers.

{
  "mcpServers": {
    "localerrors": {
      "command": "d:\\nodejs\\node.exe",
      "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
      "env": {
        "BUGSINK_URL": "http://127.0.0.1:8000",
        "BUGSINK_TOKEN": "<40-char-hex-token>"
      }
    },
    "devdb": {
      "command": "D:\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:postgres@127.0.0.1:5432/flyer_crawler_dev"
      ]
    }
  }
}

Bugsink Integration

API Token Generation

Bugsink 2.0.11 has NO UI for API tokens. Use Django management command.

Dev Container

MSYS_NO_PATHCONV=1 podman exec -e DATABASE_URL=postgresql://bugsink:bugsink_dev_password@postgres:5432/bugsink -e SECRET_KEY=dev-bugsink-secret-key-minimum-50-characters-for-security flyer-crawler-dev sh -c 'cd /opt/bugsink/conf && DJANGO_SETTINGS_MODULE=bugsink_conf PYTHONPATH=/opt/bugsink/conf:/opt/bugsink/lib/python3.10/site-packages /opt/bugsink/bin/python -m django create_auth_token'

Production

ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"

Bugsink MCP Tools

Tool Purpose
test_connection Verify connection
list_projects List all projects
list_issues List issues by project
get_issue Issue details
list_events Events for an issue
get_event Event details
get_stacktrace Formatted stacktrace

Usage Example

// Test connection
mcp__bugsink__test_connection();

// List production issues
mcp__bugsink__list_issues({ project_id: 1, status: 'unresolved', limit: 10 });

// Get stacktrace
mcp__bugsink__get_stacktrace({ event_id: 'uuid-here' });

PostgreSQL MCP Integration

Setup

# Uses @modelcontextprotocol/server-postgres package
# Connection string in .mcp.json

Tools

Tool Purpose
query Execute read-only SQL

Usage Example

mcp__devdb__query({ sql: 'SELECT * FROM public.users LIMIT 5' });
mcp__devdb__query({ sql: 'SELECT COUNT(*) FROM public.flyers' });

Gitea MCP Integration

Common Tools

Tool Purpose
get_my_user_info Current user info
list_my_repos List repositories
get_issue_by_index Issue details
list_repo_issues Repository issues
create_issue Create new issue
create_pull_request Create PR
list_repo_pull_requests List PRs
get_file_content Read file
list_repo_commits Commit history

Usage Example

// List issues
mcp__gitea -
  projectium__list_repo_issues({
    owner: 'james',
    repo: 'flyer-crawler',
    state: 'open',
  });

// Create issue
mcp__gitea -
  projectium__create_issue({
    owner: 'james',
    repo: 'flyer-crawler',
    title: 'Bug: Description',
    body: 'Details here',
  });

// Get file content
mcp__gitea -
  projectium__get_file_content({
    owner: 'james',
    repo: 'flyer-crawler',
    ref: 'main',
    filePath: 'CLAUDE.md',
  });

Redis MCP Integration

Tools

Tool Purpose
get Get key value
set Set key value
delete Delete key(s)
list List keys by pattern

Usage Example

// List cache keys
mcp__redis__list({ pattern: 'flyer:*' });

// Get cached value
mcp__redis__get({ key: 'flyer:123' });

// Set with expiration
mcp__redis__set({ key: 'test:key', value: 'data', expireSeconds: 3600 });

// Delete key
mcp__redis__delete({ key: 'test:key' });

Podman MCP Integration

Tools

Tool Purpose
container_list List containers
container_logs View logs
container_inspect Container details
container_stop Stop container
container_remove Remove container
container_run Run container
image_list List images
image_pull Pull image

Usage Example

// List running containers
mcp__podman__container_list();

// View container logs
mcp__podman__container_logs({ name: 'flyer-crawler-dev' });

// Inspect container
mcp__podman__container_inspect({ name: 'flyer-crawler-dev' });

Memory MCP (Knowledge Graph)

Tools

Tool Purpose
read_graph Read entire graph
search_nodes Search by query
open_nodes Get specific nodes
create_entities Create entities
create_relations Create relationships
add_observations Add observations
delete_entities Delete entities

Usage Example

// Search for context
mcp__memory__search_nodes({ query: 'flyer-crawler' });

// Read full graph
mcp__memory__read_graph();

// Create entity
mcp__memory__create_entities({
  entities: [
    {
      name: 'FlyCrawler',
      entityType: 'Project',
      observations: ['Uses PostgreSQL', 'Express backend'],
    },
  ],
});

Filesystem MCP

Tools

Tool Purpose
read_text_file Read file contents
write_file Write file
edit_file Edit file
list_directory List directory
directory_tree Tree view
search_files Find files by pattern

Usage Example

// Read file
mcp__filesystem__read_text_file({ path: 'd:\\gitea\\project\\README.md' });

// List directory
mcp__filesystem__list_directory({ path: 'd:\\gitea\\project\\src' });

// Search for files
mcp__filesystem__search_files({
  path: 'd:\\gitea\\project',
  pattern: '**/*.test.ts',
});

Troubleshooting MCP Servers

Server Not Loading

  1. Check server name - Avoid shared prefixes (e.g., bugsink and bugsink-dev)
  2. Use project-level .mcp.json for localhost servers
  3. Restart Claude Code after config changes

Test Connection Manually

# Bugsink
set BUGSINK_URL=http://localhost:8000
set BUGSINK_TOKEN=<token>
node d:\gitea\bugsink-mcp\dist\index.js

# PostgreSQL
npx -y @modelcontextprotocol/server-postgres "postgresql://postgres:postgres@127.0.0.1:5432/flyer_crawler_dev"

Check Claude Debug Logs

C:\Users\<username>\.claude\debug\*.txt

Look for "Starting connection" messages - missing server = never started.

External API Integrations

Gemini AI (Flyer Extraction)

Config Location
API Key VITE_GOOGLE_GENAI_API_KEY / GEMINI_API_KEY
Service src/services/flyerAiProcessor.server.ts
Client @google/genai package

Google OAuth

Config Location
Client ID GOOGLE_CLIENT_ID
Client Secret GOOGLE_CLIENT_SECRET
Service src/config/passport.ts

GitHub OAuth

Config Location
Client ID GH_CLIENT_ID / GITHUB_CLIENT_ID
Client Secret GH_CLIENT_SECRET / GITHUB_CLIENT_SECRET
Service src/config/passport.ts

Google Maps (Geocoding)

Config Location
API Key GOOGLE_MAPS_API_KEY
Service src/services/googleGeocodingService.server.ts

Nominatim (Fallback Geocoding)

Config Location
URL https://nominatim.openstreetmap.org
Service src/services/nominatimGeocodingService.server.ts

Sentry (Error Tracking)

Config Location
DSN SENTRY_DSN (server), VITE_SENTRY_DSN (client)
Auth Token SENTRY_AUTH_TOKEN (source map upload)
Server Service src/services/sentry.server.ts
Client Service src/services/sentry.client.ts

SMTP (Email)

Config Location
Host SMTP_HOST
Port SMTP_PORT
Credentials SMTP_USER, SMTP_PASS
Service src/services/emailService.server.ts

Related Documentation

Document Purpose
BUGSINK-MCP-TROUBLESHOOTING.md MCP server issues
POSTGRES-MCP-SETUP.md PostgreSQL MCP setup
DEV-CONTAINER-BUGSINK.md Local Bugsink setup
BUGSINK-SYNC.md Bugsink synchronization
Reference in New Issue View Git Blame Copy Permalink