{"id":33319668,"url":"https://github.com/auth0-samples/auth0-task-vantage","last_synced_at":"2026-02-03T21:33:10.340Z","repository":{"id":318928135,"uuid":"1075824685","full_name":"auth0-samples/auth0-task-vantage","owner":"auth0-samples","description":"Sample app showcasing Auth0 integration across multiple interfaces (MCP, REST API, AI agents, web app)","archived":false,"fork":false,"pushed_at":"2025-11-03T18:45:24.000Z","size":220,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-27T09:39:34.173Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/auth0-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T03:29:29.000Z","updated_at":"2025-11-03T18:45:28.000Z","dependencies_parsed_at":"2025-10-17T08:13:16.491Z","dependency_job_id":"d167ece3-3b28-4a56-959e-26718bc80672","html_url":"https://github.com/auth0-samples/auth0-task-vantage","commit_stats":null,"previous_names":["auth0-samples/auth0-task-vantage"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/auth0-samples/auth0-task-vantage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-task-vantage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-task-vantage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-task-vantage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-task-vantage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auth0-samples","download_url":"https://codeload.github.com/auth0-samples/auth0-task-vantage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-task-vantage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29058387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T20:13:53.544Z","status":"ssl_error","status_checked_at":"2026-02-03T20:13:40.507Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-11-19T21:02:52.068Z","updated_at":"2026-02-03T21:33:10.323Z","avatar_url":"https://github.com/auth0-samples.png","language":"HTML","funding_links":[],"categories":["Projects Using Auth0"],"sub_categories":[],"readme":"# Task Vantage Demo\n\n![Task Vantage Logo](src/agent/public/logo.png)\n\nTask Vantage Demo is a reference implementation showcasing a modern task management platform exposed through multiple interfaces:\n\n- 🚀 **REST API** - Built with [Hono](https://hono.dev/) and secured with Auth0 JWT validation\n- 🔌 **MCP Server** - Model Context Protocol server using [Hono](https://hono.dev/) + [mcp-handler](https://www.npmjs.com/package/mcp-handler) with Custom Token Exchange\n- 🤖 **Agent Service** - AI agent with web-based chat interface using [LlamaIndex](https://github.com/jerryjliu/llama_index) and OpenAI\n- 📱 **Web Application** - Modern web interface for direct project and task management\n\n**User Access Points:**\n- 🖥️ **Claude Desktop** → MCP Server (AI assistant integration)\n- 🌐 **Web Browser** → Agent Service (AI chat interface)\n- 🌐 **Web Browser** → Web Application (traditional task management UI)\n\n\u003e **Learn more**: See [docs/ABOUT.md](./docs/ABOUT.md) for the product vision and background.\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [docs/LOGGING.md](docs/LOGGING.md) | Verbose logging system for debugging authentication flows |\n| [docs/VERCEL.md](docs/VERCEL.md) | Complete deployment guide for Vercel serverless functions |\n| [docs/ABOUT.md](./docs/ABOUT.md) | Product vision and Task Vantage overview |\n\n## 🏗️ Project Structure\n\n```\nsrc/\n├── 🚀 api/          # REST API (Hono + Auth0)\n├── 🔌 mcp/          # MCP Server (Hono + mcp-handler + CTE)\n├── 🤖 agent/        # Agent Service (Hono + LlamaIndex + OpenAI)\n├── 📱 webapp/       # Web Application (Hono + Auth0 OAuth2)\n└── 🛠️ utils/        # Shared utilities (logging, etc.)\n\nvercel/              # Deployment configurations\n├── api/            # API service deployment\n├── mcp/            # MCP service deployment\n├── agent/          # Agent service deployment\n└── webapp/         # Web app deployment\n```  \n\n## ⚡ Quick Start\n\n### Requirements\n- **Node.js 22+**\n- **npm** (or compatible package manager)\n- **Auth0 account** (for authentication)\n- **OpenAI API key** (for AI agent functionality)  \n\n### Installation\n\n1. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n2. **Configure environment:**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your Auth0 and OpenAI credentials\n   ```\n\n3. **Start all services:**\n   ```bash\n   npm run dev:all\n   ```\n\n## Available Scripts\n\n### Development\n\n```bash\n# Run individual services\nnpm run dev:api        # Start REST API (port 8787)\nnpm run dev:mcp        # Start MCP server (port 8080)\nnpm run dev:agent      # Start Agent service (port 3000)\nnpm run dev:webapp     # Start Web App (port 3001)\n\n# Development with file watching\nnpm run dev:agent:watch   # Auto-restart agent on file changes\nnpm run dev:webapp:watch  # Auto-restart webapp on file changes\n\n# Run all services in parallel\nnpm run dev:all        # Starts all 4 services + opens browser tabs\nnpm start              # Alias for dev:all\n\n# Open services in browser\nnpm run open:agent     # Opens http://localhost:3000\nnpm run open:webapp    # Opens http://localhost:3001\n```\n\n### Deployment (Vercel)\n\n```bash\n# Bootstrap Vercel projects (first time setup)\nnpm run bootstrap:all     # Link all 4 Vercel projects\nnpm run bootstrap:api     # Link task-vantage-api project\nnpm run bootstrap:mcp     # Link task-vantage-mcp project\nnpm run bootstrap:agent   # Link task-vantage-agent project\nnpm run bootstrap:webapp  # Link task-vantage-webapp project\n\n# Deploy services\nnpm run deploy:all        # Deploy all services sequentially\nnpm run deploy:parallel   # Deploy all services in parallel\nnpm run deploy:api        # Deploy API service only\nnpm run deploy:mcp        # Deploy MCP service only\nnpm run deploy:agent      # Deploy Agent service only\nnpm run deploy:webapp     # Deploy Web App service only\n```\n\n### Monitoring\n\n```bash\n# View deployment logs\nnpm run logs:all          # View logs for all services\nnpm run logs:api          # View API service logs\nnpm run logs:mcp          # View MCP service logs\nnpm run logs:agent        # View Agent service logs\nnpm run logs:webapp       # View Web App service logs\n\n# Open deployed services in browser\nnpm run open:deployed:all     # Open all service dashboards\nnpm run open:deployed:api     # Open API service dashboard\nnpm run open:deployed:mcp     # Open MCP service dashboard\nnpm run open:deployed:agent   # Open Agent service dashboard\nnpm run open:deployed:webapp  # Open Web App service dashboard\n```\n\n\u003e **See [VERCEL.md](docs/VERCEL.md) for detailed deployment instructions.**\n\n### Service URLs (Local Development)\n\n| Service | URL | Purpose |\n|---------|-----|----------|\n| 🚀 **API** | http://localhost:8787 | REST API endpoints |\n| 🔌 **MCP** | http://localhost:8080/mcp | MCP server endpoint (Claude Desktop) |\n| 🤖 **Agent** | http://localhost:3000 | AI chat interface (Web Browser) |\n| 📱 **Web App** | http://localhost:3001 | Task management interface (Web Browser) |\n\n### Key Routes\n\n- **Agent Chat Interface**: http://localhost:3000/chat/app (AI chat via web browser)\n- **Web App Dashboard**: http://localhost:3001/app (Task management interface)\n- **API Health**: http://localhost:8787/health\n- **MCP Health**: http://localhost:8080/health\n\n## 🔐 Authentication Flow\n\nTask Vantage uses **Auth0** for authentication with different flows per service:\n\n| Service | Auth Method | Token Type |\n|---------|------------|------------|\n| **REST API** | JWT validation | Bearer `access_token` |\n| **MCP Server** | Custom Token Exchange (CTE) | Bearer → API token |\n| **Agent Service** | OAuth2 sessions | Session + Bearer tokens |\n| **Web App** | OAuth2 Authorization Code | Session + Access tokens |\n\n\u003e **Details**: See sequence diagram below for complete authentication flow.\n\n## 🔧 Environment Configuration\n\n**Quick setup:**\n```bash\ncp .env.example .env\n# Edit .env with your credentials\n```\n\n### Service-Specific Configuration\n\nEach service has its own configuration documented in its README:\n\n| Service | Configuration Guide |\n|---------|---------------------|\n| 🚀 **API Service** | [src/api/README.md](src/api/README.md) |\n| 🔌 **MCP Service** | [src/mcp/README.md](src/mcp/README.md) |\n| 🤖 **Agent Service** | [src/agent/README.md](src/agent/README.md) |\n| 📱 **Web App Service** | [src/webapp/README.md](src/webapp/README.md) |\n\n### Global Configuration\n\nAll services use these shared Auth0 settings:\n\n* `AUTH0_DOMAIN` - Your Auth0 domain (e.g., your-domain.auth0.com)\n* `LOG_VERBOSE` - Enable verbose logging for debugging (default: true)\n\n\u003e **Note**: REDIS_URL is automatically provided by Vercel for deployed services. Only configure locally if using local Redis.\n\n## 🏛️ System Architecture\n\n### High-Level Overview\n\nThe diagram shows how all Task Vantage services work together:\n\n```mermaid\nflowchart TB\n%% User interactions\n    User([\"End User\"])\n    Claude([\"Claude Desktop\u003cbr/\u003ewith MCP\"])\n    Browser([\"Web Browser\"])\n\n%% Services (can run locally or on Vercel)\n    subgraph Services[\"Task Vantage Services\"]\n        direction TB\n\n        WebApp[\"📱 Task Vantage Web\u003cbr/\u003e(Hono + Auth0 + Session)\"]:::webapp\n        Agent[\"🤖 Task Vantage Agent\u003cbr/\u003e(LlamaIndex + OpenAI)\"]:::agent\n        MCP[\"🔌 Task Vantage MCP\u003cbr/\u003e(Hono + mcp-handler + CTE)\"]:::mcp\n        API[\"🚀 Task Vantage API\u003cbr/\u003e(Hono + JWT validation)\"]:::api\n\n        Store[\"💾 In-memory Store\u003cbr/\u003e(Projects, Tasks, Tags, Comments)\"]:::store\n    end\n\n%% External services\n    subgraph External[\"External Services\"]\n        Auth0[\"🔐 Auth0\u003cbr/\u003e(Identity Provider)\"]:::auth\n        OpenAI[\"🧠 OpenAI\u003cbr/\u003e(LLM Provider)\"]:::openai\n    end\n\n%% User flows\n    User -.-\u003e Browser\n    User -.-\u003e Claude\n    Browser --\u003e WebApp\n    Browser --\u003e Agent\n    Claude --\u003e MCP\n\n%% Service interactions\n    WebApp --\u003e API\n    Agent --\u003e MCP\n    MCP --\u003e API\n    API --\u003e Store\n    Agent --\u003e OpenAI\n\n%% Authentication flows\n    WebApp --\u003e Auth0\n    Agent --\u003e Auth0\n    MCP --\u003e Auth0\n    API --\u003e Auth0\n\n%% styles\n    classDef webapp fill:#FFF2E6,stroke:#FF8C00,color:#8B4513,stroke-width:2px\n    classDef agent fill:#EAF2F8,stroke:#5DADE2,color:#1B4F72,stroke-width:2px\n    classDef mcp fill:#F5EEF8,stroke:#BB8FCE,color:#4A235A,stroke-width:2px\n    classDef api fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:2px\n    classDef store fill:#D5F5E3,stroke:#27AE60,color:#145A32,stroke-width:2px\n    classDef auth fill:#FADBD8,stroke:#E74C3C,color:#641E16,stroke-width:2px\n    classDef openai fill:#E8F5E8,stroke:#28A745,color:#155724,stroke-width:2px\n```\n\n### Unified Hono Architecture\n\n**Key Benefits:**\n- ✨ **Consistent Framework**: All services use [Hono](https://hono.dev/) for maximum code reuse and maintainability\n- 🚀 **Vercel Optimized**: Native serverless function support with zero configuration\n- 🔄 **DRY Deployment**: Same codebase structure across local development and production\n- 🔐 **Unified Auth Patterns**: Consistent Auth0 integration across all services\n\nThis diagram shows the specific frameworks and technologies used in each service:\n\n```mermaid\nflowchart TB\n    subgraph \"🏗️ Technology Stack\"\n        direction TB\n\n        subgraph WebApp [\"📱 Task Vantage Web\"]\n            WA1[\"Hono Framework\"]\n            WA2[\"@auth0/auth0-hono\"]\n            WA3[\"OAuth2 Authorization Code\"]\n        end\n\n        subgraph Agent [\"🤖 Task Vantage Agent\"]\n            AG1[\"Hono Framework\"]\n            AG2[\"@auth0/auth0-hono\"]\n            AG3[\"LlamaIndex + @llamaindex/openai\"]\n            AG4[\"Session Management\"]\n        end\n\n        subgraph MCP [\"🔌 Task Vantage MCP\"]\n            MC1[\"Hono Framework\"]\n            MC2[\"mcp-handler\"]\n            MC3[\"@auth0/auth0-api-js\"]\n            MC4[\"Custom Token Exchange\"]\n        end\n\n        subgraph API [\"🚀 Task Vantage API\"]\n            AP1[\"Hono Framework\"]\n            AP2[\"@auth0/auth0-api-js\"]\n            AP3[\"JWT Validation\"]\n            AP4[\"In-memory Store\"]\n        end\n\n        subgraph External [\"🌐 External Services\"]\n            EX1[\"Auth0 Identity Provider\"]\n            EX2[\"OpenAI LLM API\"]\n        end\n    end\n\n    %% Framework relationships\n    WebApp --\u003e API\n    Agent --\u003e MCP\n    MCP --\u003e API\n\n    %% Auth flows\n    WebApp --\u003e External\n    Agent --\u003e External\n    MCP --\u003e External\n    API --\u003e External\n\n    %% Agent AI integration\n    Agent --\u003e EX2\n\n    %% Styling\n    classDef webapp fill:#FFF2E6,stroke:#FF8C00,color:#8B4513,stroke-width:2px\n    classDef agent fill:#EAF2F8,stroke:#5DADE2,color:#1B4F72,stroke-width:2px\n    classDef mcp fill:#F5EEF8,stroke:#BB8FCE,color:#4A235A,stroke-width:2px\n    classDef api fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:2px\n    classDef external fill:#FADBD8,stroke:#E74C3C,color:#641E16,stroke-width:2px\n\n    class WebApp,WA1,WA2,WA3 webapp\n    class Agent,AG1,AG2,AG3,AG4 agent\n    class MCP,MC1,MC2,MC3,MC4 mcp\n    class API,AP1,AP2,AP3,AP4 api\n    class External,EX1,EX2 external\n```\n\n## 🔄 Request Flow\n\nThis sequence shows how Claude Desktop creates a task via MCP:\n\n```mermaid\n%%{init: { \"sequence\": { \"mirrorActors\": false }}}%%\nsequenceDiagram\n    actor User as End User\n    participant Claude as Claude Desktop\n    participant MCP as Task Vantage MCP\u003cbr/\u003e(Hono + mcp-handler + CTE)\n    participant Auth0 as Auth0\u003cbr/\u003e(Identity Provider)\n    participant API as Task Vantage API\u003cbr/\u003e(Hono)\n    participant Store as In-memory Store\n\n    Note over User,Store: MCP Tool Invocation Flow\n\n    User -\u003e\u003e Claude: \"Create a new project called 'Demo'\"\n    Claude -\u003e\u003e MCP: create_project({name: \"Demo\"})\n\n    Note over MCP,Auth0: Custom Token Exchange (CTE)\n    MCP -\u003e\u003e Auth0: Exchange MCP token for API token\n    Auth0 --\u003e\u003e MCP: API access token\n\n    Note over MCP,API: Authenticated API Call\n    MCP -\u003e\u003e API: POST /projects with Bearer token\n    API -\u003e\u003e Auth0: Validate JWT token\n    Auth0 --\u003e\u003e API: Token claims (sub, scope, etc.)\n\n    API -\u003e\u003e Store: Create project in memory\n    Store --\u003e\u003e API: Project created\n    API --\u003e\u003e MCP: {\"id\": \"proj_123\", \"name\": \"Demo\"}\n    MCP --\u003e\u003e Claude: Tool result: Project created\n    Claude --\u003e\u003e User: \"I've created the 'Demo' project for you.\"\n\n    Note over User,Store: Alternative Flows\n\n    rect rgb(255, 248, 220)\n        Note over User,WebApp: Web App Flow\n        User -\u003e\u003e WebApp: Login \u0026 create project\n        WebApp -\u003e\u003e Auth0: OAuth2 Authorization Code flow\n        Auth0 --\u003e\u003e WebApp: Access token\n        WebApp -\u003e\u003e API: Create project with token\n    end\n\n    rect rgb(240, 248, 255)\n        Note over User,Agent: Agent Chat Flow\n        User -\u003e\u003e Agent: Chat with AI agent\n        Agent -\u003e\u003e Auth0: Session authentication\n        Agent -\u003e\u003e MCP: Call MCP tools\n        MCP -\u003e\u003e API: Forward to API\n    end\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0-samples%2Fauth0-task-vantage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauth0-samples%2Fauth0-task-vantage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0-samples%2Fauth0-task-vantage/lists"}