|
| 1 | +# Agent Guidelines — mcp-redtrack |
| 2 | + |
| 3 | +## Project structure |
| 4 | + |
| 5 | +``` |
| 6 | +src/ |
| 7 | +├── index.ts # Entry point (stdio transport) |
| 8 | +├── server.ts # McpServer creation + tool registration |
| 9 | +├── config/ |
| 10 | +│ └── env.ts # Zod-validated environment config |
| 11 | +├── services/ |
| 12 | +│ ├── redtrack-api.ts # REST client with retry logic |
| 13 | +│ └── format.ts # Table/CSV/date formatters |
| 14 | +├── tools/ |
| 15 | +│ ├── index.ts # registerAllTools barrel |
| 16 | +│ ├── campaigns.ts # Campaign tools (3) |
| 17 | +│ ├── logs.ts # Click & conversion log tools (2) |
| 18 | +│ ├── reports.ts # Aggregated report tool (1) |
| 19 | +│ └── entities.ts # Offers, sources, networks, landings, settings (7) |
| 20 | +└── utils/ |
| 21 | + └── logger.ts # stderr logger |
| 22 | +``` |
| 23 | + |
| 24 | +## Authentication |
| 25 | + |
| 26 | +All RedTrack API calls use `api_key` as a query parameter. The key is read from |
| 27 | +`REDTRACK_API_KEY` env var or `.env` file. No OAuth or token refresh needed. |
| 28 | + |
| 29 | +## API conventions |
| 30 | + |
| 31 | +- Base URL: `https://api.redtrack.io` |
| 32 | +- All GET endpoints accept query parameters |
| 33 | +- Pagination: `page` + `per` params |
| 34 | +- Date filtering: `date_from` + `date_to` (YYYY-MM-DD) |
| 35 | +- Status values: 1=active, 2=paused, 3=deleted |
| 36 | +- Comma-separated IDs for multi-filter (e.g. `ids=1,2,3`) |
| 37 | + |
| 38 | +## Report grouping dimensions |
| 39 | + |
| 40 | +campaign, offer, source, landing, network, country, region, city, |
| 41 | +os, browser, device, device_brand, connection_type, isp, |
| 42 | +date, hour, day_of_week, sub1-sub20, |
| 43 | +rt_source, rt_medium, rt_campaign, rt_adgroup, rt_ad, rt_placement, rt_keyword |
| 44 | + |
| 45 | +## Tool registration pattern |
| 46 | + |
| 47 | +```typescript |
| 48 | +export function registerXTools(server: McpServer): void { |
| 49 | + server.tool("tool_name", "description", { ...zodSchema }, async (args) => { |
| 50 | + const data = await apiCall(args); |
| 51 | + return { content: [{ type: "text", text: formatResult(data) }] }; |
| 52 | + }); |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +## Best practices |
| 57 | + |
| 58 | +- Always return `{ content: [{ type: "text", text }] }` |
| 59 | +- Default date ranges to last 7 days for log queries |
| 60 | +- Use `formatTable()` for list responses, `JSON.stringify` for single items |
| 61 | +- Log to stderr only (stdout is MCP protocol) |
| 62 | +- Handle API errors by throwing (MCP SDK surfaces them to the client) |
0 commit comments