411 lines
12 KiB
Markdown
411 lines
12 KiB
Markdown
# 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 |
|