# 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).

```json
{
  "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.

```json
{
  "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

```bash
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

```bash
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

```typescript
// 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

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

### Tools

| Tool    | Purpose               |
| ------- | --------------------- |
| `query` | Execute read-only SQL |

### Usage Example

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```bash
# 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 |