# DokaAI MCP Service POC

Unified TypeScript service with:

- local stdio MCP server for Codex / Claude Desktop
- Vercel-ready HTTP MCP endpoint
- REST APIs backed by the same in-memory business data
- Phase 1 production structure for auth, routes, logging, errors, computed metrics, and evals

## Setup

```bash
npm install
npm run build
```

## Local MCP

Run the stdio MCP server:

```bash
npm start
```

Codex / Claude Desktop can still use:

```json
{
  "command": "node",
  "args": ["/Users/ayushsrivastava0609/Doka-AI/mcp-server-poc/dist/index.js"]
}
```

## Vercel Deployment

Deploy this folder as the Vercel project root:

```text
/Users/ayushsrivastava0609/Doka-AI/mcp-server-poc
```

Hosted endpoints:

- `GET /health`
- `GET /api/users`
- `GET /api/orders`
- `GET /api/users/:userId/orders`
- `GET /api/users/:userId/business-profile`
- `GET /api/business/summary`
- `POST /mcp`
- `GET /mcp`
- `DELETE /mcp`

### Authentication

For hosted connector authentication, the service exposes a POC OAuth flow:

- `/.well-known/oauth-protected-resource/mcp`
- `/.well-known/oauth-authorization-server`
- `/oauth/register`
- `/oauth/authorize`
- `/oauth/token`

When ChatGPT or Claude connects to `/mcp` without a token, the server returns `401` with a `WWW-Authenticate` header pointing to the OAuth protected-resource metadata. The connector client can then start the OAuth flow.

Set this environment variable in Vercel:

```text
OAUTH_SIGNING_SECRET=your-long-random-signing-secret
```

During OAuth authorization, the demo page asks for:

```text
DokaAI Username
DokaAI Password
```

Default mock login:

```text
username: dokaai_demo_user
password: dokaai_demo_password
```

Override it in Vercel with:

```text
MOCK_DOKAAI_USERNAME=your-demo-username
MOCK_DOKAAI_PASSWORD=your-demo-password
```

For this POC, a successful login creates a short-lived signed OAuth token. For production, replace this with a real user/session system.

You can also set this legacy static token for private API testing:

```text
MCP_AUTH_TOKEN=your-long-random-token
```

`/health`, `/api/health`, OAuth metadata, and OAuth endpoints stay public. Everything else requires either an OAuth bearer token or:

```http
Authorization: Bearer your-long-random-token
```

or:

```http
x-api-key: your-long-random-token
```

Example:

```bash
curl https://your-app.vercel.app/api/users \
  -H "Authorization: Bearer your-long-random-token"
```

## MCP Tools

- `get_indian_users`: Fetch all Indian test users from the backend API.
- `get_orders`: Fetch all business orders.
- `get_user_orders`: Fetch orders for one user, such as `usr_001`.
- `get_user_business_profile`: Fetch one user with subscription, orders, invoices, payments, refunds, computed metrics, risk signals, data limitations, and evidence guidance.
- `get_business_summary`: Fetch aggregate business metrics, risk counts, summary signals, data limitations, and evidence guidance.

The AI client can handle filtering, lookup, grouping, summaries, and cross-dataset reasoning from the returned data.

For better answer accuracy, important calculations are returned by the backend instead of being left to the model:

```text
daysSinceLastLogin
daysSinceLastOrder
daysUntilRenewal
failedPaymentCount
overdueInvoiceCount
riskOrderCount
financialRisk
engagementRisk
renewalRisk
overallCustomerHealth
```

Every major MCP response also includes:

```text
evidenceGuide
dataLimitations
```

## Phase 1 Structure

The code is split by responsibility:

```text
src/auth      OAuth-shaped auth and token helpers
src/config    runtime constants
src/http      request/response utilities
src/logging   structured JSON logger
src/mcp       MCP tools, prompts, evidence, server setup
src/routes    hosted MCP and REST route handlers
src/services  mock data, business metrics, data limitations
src/vercel.ts thin deployment entrypoint
```

See:

```text
docs/phase-1-production.md
docs/evals.md
docs/usability.md
```

## MCP Prompts

Prompts are reusable workflows the client can run.

- `business_summary_report`: Guides the AI to produce a simple business report with overview, revenue snapshot, risk signals, patterns, recommended actions, and evidence used.
- `customer_segmentation_report`: Guides the AI to analyze users by location, plan, profession, support, and billing signals.
- `orders_analysis_report`: Guides the AI to analyze revenue, product categories, payments, fulfillment, sales channel, and order risks.
- `user_orders_report`: Guides the AI to analyze orders for one user. Requires `userId`.
- `customer_health_report`: Guides the AI to analyze one customer using profile, subscription, orders, invoices, payments, refunds, and metrics. Requires `userId`.