|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Task Vantage Demo is a microservices-based task management platform demonstrating Auth0 integration patterns across 4 services: |
| 8 | + |
| 9 | +- **API Service** (`src/api/`) - Hono REST API with Auth0 JWT validation |
| 10 | +- **MCP Service** (`src/mcp/`) - Hono server with mcp-handler + Custom Token Exchange (CTE) |
| 11 | +- **Agent Service** (`src/agent/`) - LlamaIndex agent with OpenAI integration |
| 12 | +- **Web App Service** (`src/webapp/`) - Frontend with Auth0 OAuth2 flow |
| 13 | + |
| 14 | +**Unified Architecture Benefits:** |
| 15 | +- All services use Hono framework for consistency and code reuse |
| 16 | +- Same deployment pattern for local development and Vercel serverless |
| 17 | +- Unified Auth0 integration patterns across all services |
| 18 | +- DRY (Don't Repeat Yourself) principle applied throughout |
| 19 | + |
| 20 | +Each service runs independently and communicates via HTTP APIs with bearer token authentication. |
| 21 | + |
| 22 | +## Development Commands |
| 23 | + |
| 24 | +### Local Development |
| 25 | +```bash |
| 26 | +# Start all services in parallel (opens browser tabs) |
| 27 | +npm run dev:all |
| 28 | + |
| 29 | +# Start individual services |
| 30 | +npm run dev:api # Port 8787 |
| 31 | +npm run dev:mcp # Port 8080 |
| 32 | +npm run dev:agent # Port 3000 |
| 33 | +npm run dev:webapp # Port 3001 |
| 34 | + |
| 35 | +# Development with file watching |
| 36 | +npm run dev:agent:watch |
| 37 | +npm run dev:webapp:watch |
| 38 | +``` |
| 39 | + |
| 40 | +### Vercel Deployment |
| 41 | +```bash |
| 42 | +# One-time setup (links projects) |
| 43 | +npm run bootstrap:all |
| 44 | + |
| 45 | +# Deploy all services |
| 46 | +npm run deploy:all # Sequential (safer) |
| 47 | +npm run deploy:parallel # Parallel (faster) |
| 48 | + |
| 49 | +# Deploy individual services |
| 50 | +npm run deploy:api |
| 51 | +npm run deploy:mcp |
| 52 | +npm run deploy:agent |
| 53 | +npm run deploy:webapp |
| 54 | + |
| 55 | +# Monitor deployments |
| 56 | +npm run logs:all |
| 57 | +npm run logs:api |
| 58 | +npm run logs:mcp |
| 59 | +npm run logs:agent |
| 60 | +npm run logs:webapp |
| 61 | +``` |
| 62 | + |
| 63 | +## Architecture Patterns |
| 64 | + |
| 65 | +### Service Communication Flow |
| 66 | +``` |
| 67 | +Claude Desktop → MCP Server → API Service → In-Memory Store |
| 68 | +Web Browser → Web App → API Service → In-Memory Store |
| 69 | +Agent UI → Agent Service → MCP Server → API Service → In-Memory Store |
| 70 | +``` |
| 71 | + |
| 72 | +### Authentication Architecture |
| 73 | +- **API Service**: Validates JWT tokens from Auth0 using `@auth0/auth0-api-js` |
| 74 | +- **MCP Service**: Uses Custom Token Exchange (CTE) to convert MCP tokens → API tokens |
| 75 | +- **Agent Service**: Uses Auth0 sessions for `/chat/*` routes, forwards tokens to MCP |
| 76 | +- **Web App**: Uses OAuth2 Authorization Code flow, extracts access tokens for API calls |
| 77 | + |
| 78 | +### Data Models |
| 79 | +The API uses an in-memory store (`src/api/app.js`) with two main entities: |
| 80 | +- **Projects**: `{ id, orgId, name, description, createdAt }` |
| 81 | +- **Tasks**: `{ id, orgId, projectId, title, description, ownerId, dueAt, status, tags, comments, createdAt, updatedAt, createdBy }` |
| 82 | + |
| 83 | +## Key Implementation Details |
| 84 | + |
| 85 | +### Environment Configuration |
| 86 | +- Each service has its own `env.js` file with environment variable handling |
| 87 | +- Auth0 integration requires: `AUTH0_DOMAIN`, client credentials, and audience |
| 88 | +- Services detect missing config and fall back to "no auth" mode for development |
| 89 | + |
| 90 | +### MCP Tools Implementation |
| 91 | +The MCP server (`src/mcp/app.js`) exposes 9 tools: |
| 92 | +- `tv_create_project`, `tv_list_projects` |
| 93 | +- `tv_create_task`, `tv_get_task`, `tv_list_tasks` |
| 94 | +- `tv_update_task_status`, `tv_assign_task`, `tv_comment_task`, `tv_tag_task` |
| 95 | +- `tv_due_soon` |
| 96 | + |
| 97 | +All tools use Zod schemas for validation and forward requests to the API service. |
| 98 | + |
| 99 | +### Custom Token Exchange (CTE) |
| 100 | +The MCP service implements Auth0 CTE in `src/mcp/client.js`: |
| 101 | +1. Caches exchanged tokens with 30-second clock skew |
| 102 | +2. Falls back to forwarding original tokens if CTE fails |
| 103 | +3. Extracts scopes from JWT payload for response metadata |
| 104 | + |
| 105 | +### Logging System |
| 106 | +Centralized logging in `src/utils/logger.js`: |
| 107 | +- Global toggle: `LOG_VERBOSE=true` |
| 108 | +- Per-component: `LOG_MCP_SERVER=true`, `LOG_API_SERVER=true`, etc. |
| 109 | +- Sanitized token logging (first character only) |
| 110 | +- Sequential request IDs for cross-service tracing |
| 111 | + |
| 112 | +### Vercel Deployment Strategy |
| 113 | + |
| 114 | +**Deployment Process** (see [VERCEL.md](docs/VERCEL.md) for complete details): |
| 115 | + |
| 116 | +1. **Copy Phase**: `cp -r src vercel/[service]/` + `cp package*.json vercel/[service]/` |
| 117 | +2. **Link Phase**: `vercel link --project task-vantage-[service] --yes` |
| 118 | +3. **Deploy Phase**: `vercel --prod --yes` |
| 119 | + |
| 120 | +**Key Points**: |
| 121 | +- Each service gets the **complete** `src/` codebase (not just its own directory) |
| 122 | +- Serverless entry points in `vercel/[service]/api/index.js` import from `../src/[service]/app.js` |
| 123 | +- **Unified**: MCP now uses `mcp-handler` for both local development and Vercel deployment |
| 124 | +- Environment variables must use **deployed URLs** (not localhost) |
| 125 | +- All 4 services deploy to separate Vercel projects with individual domains |
| 126 | + |
| 127 | +## Development Guidelines |
| 128 | + |
| 129 | +### Adding New API Endpoints |
| 130 | +1. Add route to `src/api/app.js` with scope checking using `requireScope()` |
| 131 | +2. Update MCP tools in `src/mcp/app.js` if needed |
| 132 | +3. Add corresponding Web App proxy routes in `src/webapp/app.js` |
| 133 | + |
| 134 | +### Authentication Debugging |
| 135 | +- Enable verbose logging: `LOG_VERBOSE=true npm run dev:all` |
| 136 | +- Check token flows in logs (tokens are sanitized) |
| 137 | +- Verify scope requirements match between services |
| 138 | +- Test both authenticated and "no auth" modes |
| 139 | + |
| 140 | +### Environment Variables |
| 141 | +- Always update `.env.example` when adding new variables |
| 142 | +- Document in `README.md` environment section |
| 143 | +- Handle missing variables gracefully (service detection patterns) |
| 144 | +- **Critical for Vercel**: Use deployed URLs in `*_BASE_URL` variables: |
| 145 | + ```bash |
| 146 | + # Local development |
| 147 | + API_BASE_URL=http://localhost:8787 |
| 148 | + MCP_BASE_URL=http://localhost:8080 |
| 149 | + |
| 150 | + # Production deployment |
| 151 | + API_BASE_URL=https://api.taskvantage.example.com |
| 152 | + MCP_BASE_URL=https://mcp.taskvantage.example.com |
| 153 | + ``` |
| 154 | + |
| 155 | +### Testing Authentication Flows |
| 156 | +- **MCP**: Use Claude Desktop with MCP configuration |
| 157 | +- **Agent**: Visit `/chat/app` for authenticated routes, `/` for public |
| 158 | +- **Web App**: Visit `/app` for authenticated routes, `/` for public |
| 159 | +- **API**: Test with `curl` using bearer tokens |
| 160 | + |
| 161 | +## Service Dependencies |
| 162 | + |
| 163 | +### Runtime Dependencies |
| 164 | +- API: Hono, @auth0/auth0-api-js |
| 165 | +- MCP: Hono, mcp-handler, @auth0/auth0-api-js |
| 166 | +- Agent: LlamaIndex, @llamaindex/openai, @auth0/auth0-hono |
| 167 | +- Web App: Hono, @auth0/auth0-hono |
| 168 | + |
| 169 | +### Shared Utilities |
| 170 | +- `src/utils/logger.js` - Centralized logging system |
| 171 | +- Each service has its own `env.js` for environment handling |
| 172 | +- Common auth patterns across services (scope checking, token forwarding) |
| 173 | + |
| 174 | +## Troubleshooting Common Issues |
| 175 | + |
| 176 | +### Auth0 Configuration |
| 177 | +- Verify callback URLs match service base URLs |
| 178 | +- Check audience matches between MCP and API services |
| 179 | +- Ensure client credentials are for correct applications |
| 180 | +- Test token exchange configuration separately |
| 181 | + |
| 182 | +### Service Communication |
| 183 | +- **Local**: Services communicate via localhost URLs |
| 184 | +- **Vercel**: Services communicate via public Vercel URLs (see [VERCEL.md](docs/VERCEL.md#deployment-specific-variables)) |
| 185 | +- Update `*_BASE_URL` environment variables for each deployment target |
| 186 | +- Check CORS if cross-origin issues occur |
| 187 | +- Verify network connectivity between Vercel functions |
| 188 | +- Use logging to trace request flows across services |
| 189 | + |
| 190 | +### Vercel-Specific Issues |
| 191 | +- **File copying**: All deployment scripts copy the entire `src/` directory to each service |
| 192 | +- **Entry points**: Each service has a wrapper in `vercel/[service]/api/index.js` |
| 193 | +- **Unified deployment**: MCP uses the same Hono + mcp-handler pattern for both local and Vercel |
| 194 | +- **Bootstrap required**: Run `npm run bootstrap:all` after cloning to link projects |
| 195 | +- **Environment sync**: Vercel environment variables are separate from local `.env` |
| 196 | + |
| 197 | +### Development Environment |
| 198 | +- Services must run on documented ports for cross-references |
| 199 | +- Use `npm run dev:all` to ensure proper startup order |
| 200 | +- Check that all required environment variables are set |
| 201 | +- Test both local and deployed configurations |
0 commit comments