# Agentic Shopping MCP

Production-ready **MCP (Model Context Protocol) server** that exposes commerce tools, plus a **secure HTTP bridge** that Cequence can place in front of for **OAuth, scoping, and observability**. Includes a simple **Next.js demo UI**.

> Hackathon focus: “Build the Infrastructure for Autonomous Software”.  
> Transform apps into **AI-ready, agent-accessible services** using a **Cequence AI Gateway** with **OAuth (Descope)** and **MCP**.

---

## 🧱 What’s in here

- **MCP Server** (`src/server.ts` → `dist/server.js`)  
  Tools:
  - `commerce:ping`, `commerce:echo`
  - `commerce:search` (local mock catalog)
  - `commerce:details`, `commerce:reviews`
  - `commerce:budget_top` (Budget Constraint AI)
  - `commerce:sustainability` (approx CO₂ calc)

- **HTTP Bridge** (`src/http_bridge.ts`)  
  Exposes `POST /mcp/tools/call` → spawns MCP server over stdio → calls tool.  
  - Auth: Dev Bearer token **or** JWT (HS256/RS256).  
  - Emits JSON logs w/ `requestId` → gateway-friendly.

- **Web Demo** (`/web`, Next.js 15 + Tailwind)  
  - Budget Constraint AI form  
  - Sustainability badge

---

## 🗂️ Repo Structure (key paths)

.
├─ data/
│  ├─ catalog.sample.json
│  └─ reviews.sample.json
├─ dist/                 # built server files (gitignored)
├─ scripts/
│  └─ test_client.ts     # MCP stdio test
├─ src/
│  ├─ app/api/commerce/route.ts   # Web API -> MCP server
│  ├─ http_bridge.ts              # HTTP Bridge -> MCP server
│  ├─ providers/amazon.ts         # sample provider (file-based)
│  └─ server.ts                   # MCP server (tools)
└─ web/
├─ src/app/page.tsx            # UI
└─ (Next.js project)

---

## ⚙️ Prerequisites

- Node.js 20+
- npm
- (Optional) curl + jq for testing

---

## 🚀 Quick Start (Local)

```bash
# clone & install
git clone https://github.com/rochitl72/mcp-den.git
cd mcp-den
npm install

1) Build MCP Server

npm run build

2) Test MCP via stdio client

npm run test:client
# Expect:
# TOOLS: [ 'commerce' ]
# PING: pong
# ECHO: echo: hello mcp
# SEARCH/DETAILS/REVIEWS/BUDGET_TOP outputs...

3) Run the HTTP Bridge (Cequence-facing)

# DEV token mode
DEV_TOKEN=dev123 npm run bridge
# -> MCP HTTP bridge listening on http://localhost:8787

Call bridge with curl:

curl -s http://localhost:8787/mcp/tools/call \
  -H "authorization: Bearer dev123" \
  -H "content-type: application/json" \
  -d '{"name":"commerce","arguments":{"action":"budget_top","query":"phone","budgetMaxINR":15000,"featurePref":"camera","topK":3,"filters":{"minRating":3.5}}}' | jq .

4) Run the Web Demo

cd web
npm install
npm run dev
# http://localhost:3000


⸻

🔐 Auth Options (Bridge)

Set one of the following:
	•	Dev token (easy)

export DEV_TOKEN=dev123
npm run bridge


	•	JWT HS256

export JWT_MODE=hs256
export JWT_SECRET='<your-hs256-shared-secret>'
npm run bridge


	•	JWT RS256 (OIDC/Descope public key)

export JWT_MODE=rs256
export JWT_PUBLIC_KEY_B64="$(base64 -i public.pem)"
npm run bridge



Scopes checked (simple demo):
mcp:commerce:<action> or mcp:commerce:* when calling /mcp/tools/call.

⸻

🧪 HTTP Bridge API
	•	POST /mcp/tools/call
Headers:
	•	Authorization: Bearer <token>
	•	Content-Type: application/json
Body:

{ "name": "commerce", "arguments": { "action": "ping" } }

Response:

{ "ok": true, "requestId": "uuid", "tool": "commerce", "action": "ping", "data": "..." }


	•	GET /healthz → { "ok": true }

⸻

🌐 Hooking up Cequence AI Gateway
	•	Point Cequence upstream to the HTTP bridge (http://your-host:8787).
	•	Enforce:
	•	OAuth/JWT validation (issuer = Descope)
	•	Scopes → mcp:commerce:budget_top, etc.
	•	Rate limit / mTLS / logging
	•	Propagate headers: Authorization and x-request-id (or set at gateway)
	•	Observe logs: bridge prints JSON lines with requestId, user, action, duration.

⸻

🧩 Using from Agent Clients
	•	Claude Desktop / Crew / LangChain can use:
	•	stdio: point to dist/server.js
	•	HTTP: call the bridge endpoint from your agent runtime (Gateway in front for auth)

(You can also run the bridge in the same container as the MCP server.)

⸻

🛠️ Scripts

# package.json (root)
{
  "scripts": {
    "build": "tsc -p tsconfig.server.json",
    "dev": "tsx src/server.ts",
    "test:client": "tsx scripts/test_client.ts",
    "bridge": "tsx src/http_bridge.ts"
  }
}

Web project scripts (in /web):

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}


⸻

🔧 Environment

Create .env in repo root if needed:

# Bridge
DEV_TOKEN=dev123
# or JWT_MODE=hs256
# JWT_SECRET=your-secret
# or JWT_MODE=rs256
# JWT_PUBLIC_KEY_B64=base64-of-public-pem

# (Optional) values MCP server may read
X_USER=
X_REQUEST_ID=


⸻

🧰 Troubleshooting
	•	Timeouts from test client
Ensure only one MCP server registers tools; restart terminal if stray processes existed.
	•	ENOENT on catalog JSON
We resolve the data/ path relative to providers/amazon.ts—run npm run build again after editing.
	•	Next.js/Tailwind errors
Ensure web installed dev deps and Tailwind config is correct (postcss.config.js, tailwind.config.ts).
	•	401 from bridge
Provide Authorization: Bearer <DEV_TOKEN or JWT>.

⸻

📦 Deploy
	•	Bridge + MCP: Docker or Render/Fly. Expose port 8787.
	•	Web: Deploy /web to Vercel/Netlify.
	•	Configure Cequence to sit in front of the bridge with your OIDC (Descope).

(A Dockerfile + Fly/Render configs can be added on request.)

⸻

📜 License

MIT (or your choice)
MD

If you also want a quick **`.env.example`** for the repo:

```bash
cat > .env.example <<'ENV'
# One of the following auth modes for the HTTP bridge:

# Dev token mode (easy for local)
DEV_TOKEN=dev123

# JWT HS256 mode
# JWT_MODE=hs256
# JWT_SECRET=replace-with-shared-secret

# JWT RS256 mode
# JWT_MODE=rs256
# JWT_PUBLIC_KEY_B64=base64-of-your-public-pem
ENV

Commit & push:

git add README.md .env.example
git commit -m "Add README and env example"
git push