diff options
Diffstat (limited to 'AI_AGENT_SETUP.md')
| -rw-r--r-- | AI_AGENT_SETUP.md | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/AI_AGENT_SETUP.md b/AI_AGENT_SETUP.md new file mode 100644 index 0000000..acf2da4 --- /dev/null +++ b/AI_AGENT_SETUP.md @@ -0,0 +1,276 @@ +# AI Agent Access Setup Guide + +## Quick Start + +### 1. Generate API Key +```bash +# Generate a secure 64-character API key +openssl rand -hex 32 +``` + +Example output: `a1b2c3d4e5f6...` + +### 2. Add to Environment +Add to your `.env` file: +```bash +AI_AGENT_API_KEY=a1b2c3d4e5f6... +``` + +### 3. Start the Dashboard +```bash +go run cmd/dashboard/main.go +``` + +You should see: +``` +AI agent access enabled at /api/claude/snapshot +Starting server on http://localhost:8080 +``` + +### 4. Test the Endpoint +```bash +curl -H "Authorization: Bearer a1b2c3d4e5f6..." \ + http://localhost:8080/api/claude/snapshot | jq . +``` + +## Usage from Claude.ai + +### Method 1: Direct WebFetch +When conversing with Claude, share: + +**URL:** `http://localhost:8080/api/claude/snapshot` +**Token:** `a1b2c3d4e5f6...` (share separately, not in chat history) + +Claude can then fetch your dashboard: +``` +User: "What tasks do I have today?" + +Claude: [Calls WebFetch with Authorization header] +Claude: "You have 3 tasks due today: +1. Review PRs (Work, Priority 4) +2. Buy groceries (Personal, Priority 1) +3. Call dentist (Health, Priority 2)" +``` + +### Method 2: MCP Server (Advanced) +If you have Claude Desktop with MCP support: + +Add to your MCP config: +```json +{ + "mcpServers": { + "personal-dashboard": { + "command": "curl", + "args": [ + "-H", + "Authorization: Bearer YOUR_TOKEN_HERE", + "-s", + "http://localhost:8080/api/claude/snapshot" + ] + } + } +} +``` + +## Response Format + +### Successful Response (200 OK) +```json +{ + "generated_at": "2026-01-09T15:30:00Z", + "tasks": { + "today": [ + { + "id": "task_123", + "content": "Review PRs", + "priority": 4, + "due": "2026-01-09T17:00:00Z", + "project": "Work", + "completed": false + } + ], + "overdue": [], + "next_7_days": [] + }, + "meals": { + "today": { + "date": "2026-01-09", + "breakfast": "Oatmeal with protein powder", + "lunch": "Chicken salad", + "dinner": "Salmon with veggies" + }, + "next_7_days": [] + }, + "notes": { + "recent": [ + { + "title": "Sprint planning notes", + "modified": "2026-01-09T10:15:00Z", + "preview": "Discussed Q1 goals and team capacity...", + "path": "work/sprint-planning.md" + } + ] + }, + "trello_boards": [ + { + "id": "board_123", + "name": "Work Projects", + "cards": [ + { + "id": "card_456", + "name": "Complete project proposal", + "list": "In Progress", + "due": "2026-01-15T00:00:00Z", + "url": "https://trello.com/c/card456" + } + ] + } + ] +} +``` + +### Error Response (401 Unauthorized) +```json +{ + "error": "unauthorized", + "message": "Invalid or missing token" +} +``` + +## Security Best Practices + +### ✅ Do +- Generate a long, random key (32+ bytes) +- Store key in `.env` file (gitignored) +- Use HTTPS in production +- Rotate key periodically (change in `.env`) +- Share token with Claude separately from URL + +### ❌ Don't +- Commit API key to git +- Share key in chat history +- Use simple/guessable keys +- Expose over HTTP in production +- Include key in URL query parameters + +## Data Limits + +The endpoint is optimized for AI consumption: + +- **Tasks**: Today + overdue + next 7 days only +- **Notes**: 10 most recent, 150 char preview each +- **Meals**: Today + next 7 days +- **Trello**: All boards and cards +- **Total Response**: < 100KB (typically 10-50KB) + +## Caching + +- Responses are cached for 5 minutes +- Same cache as web dashboard +- Reduces load on external APIs (Todoist, Trello, etc.) + +## Troubleshooting + +### "Invalid or missing token" +- Check `Authorization: Bearer` prefix is included +- Verify token matches `.env` file exactly +- No extra spaces or newlines in token + +### "AI agent access not configured" +- Ensure `AI_AGENT_API_KEY` is set in `.env` +- Restart the server after changing `.env` + +### Empty response sections +- Trello/Todoist/PlanToEat APIs may be down +- Check dashboard web UI to see if data loads there +- Review server logs for API errors + +## Production Deployment + +### With Caddy (Automatic HTTPS) +```caddyfile +dashboard.yourdomain.com { + reverse_proxy localhost:8080 +} +``` + +### With nginx +```nginx +server { + listen 443 ssl http2; + server_name dashboard.yourdomain.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } +} +``` + +Then share with Claude: +- **URL**: `https://dashboard.yourdomain.com/api/claude/snapshot` +- **Token**: (your API key) + +## Example Claude Conversations + +### Check Today's Tasks +``` +User: "What do I need to do today?" + +Claude: [Fetches /api/claude/snapshot] + +Claude: "Here's what you have for today: + +Tasks: +- Review PRs (Work, Priority 4, due 5pm) +- Buy groceries (Personal, Priority 1) + +Meals: +- Breakfast: Oatmeal +- Lunch: Chicken salad +- Dinner: Salmon with veggies" +``` + +### Check Overdue Items +``` +User: "Do I have anything overdue?" + +Claude: [Fetches snapshot] + +Claude: "You have 2 overdue tasks: +1. Submit expense report (Work, was due Jan 5) +2. Schedule dentist appointment (Health, was due Jan 7)" +``` + +### Review Recent Notes +``` +User: "What notes have I created recently?" + +Claude: [Fetches snapshot] + +Claude: "Your 3 most recent notes: +1. Sprint planning notes (modified today at 10:15am) +2. Customer feedback summary (modified Jan 8) +3. Architecture decision record (modified Jan 6)" +``` + +## Rate Limiting (Future) + +Currently no rate limiting. For production use, consider adding: +- 100 requests/hour per token +- Implement using middleware +- Return 429 status when exceeded + +## Next Steps + +1. ✅ Generate API key +2. ✅ Add to .env +3. ✅ Test with curl +4. ✅ Share URL + token with Claude +5. ✅ Start conversing! + +Enjoy your AI-powered personal dashboard! 🚀 |