# 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