{"id":48406849,"url":"https://github.com/murphye/agentic-mcp-gateway-demo","last_synced_at":"2026-04-06T03:38:40.239Z","repository":{"id":337752770,"uuid":"1146125269","full_name":"murphye/agentic-mcp-gateway-demo","owner":"murphye","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-14T00:50:09.000Z","size":7182,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T03:38:30.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/murphye.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-30T16:51:25.000Z","updated_at":"2026-02-11T22:43:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/murphye/agentic-mcp-gateway-demo","commit_stats":null,"previous_names":["murphye/agentic-mcp-gateway-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/murphye/agentic-mcp-gateway-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murphye%2Fagentic-mcp-gateway-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murphye%2Fagentic-mcp-gateway-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murphye%2Fagentic-mcp-gateway-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murphye%2Fagentic-mcp-gateway-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/murphye","download_url":"https://codeload.github.com/murphye/agentic-mcp-gateway-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murphye%2Fagentic-mcp-gateway-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31458838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2026-04-06T03:38:39.654Z","updated_at":"2026-04-06T03:38:40.232Z","avatar_url":"https://github.com/murphye.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Enterprise Agentic App with MCP Gateway (*Pear Co*)\n\n## High-Level Overview\n\nThe demo is based on *Pear Co*, an Apple-like ficitious company with a product line including laptops and smartphones. *Pear Co* needed to improve their customer support, and decided to implement an agent to provide an improved customer and experience and faster time to resolution.\n\nThis demo implements an agentic application within an existing enterprise architecture, and aims to show a realistic solution that focuses on agentic best practices, API-first implementation, RBAC security, and providing significant business value using an agent. \n\nAn additional focus for the demo is to leverage MCP and an agent (API) gateway to provide comprehensive tools derived from existing REST APIs, and control access to those tools using RBAC (based on user roles). For example, a *Pear Co* employee would have access to a different set of MCP tools than a customer would.\n\nThe demo is comprised of:\n\n* *Pear Genius*: An agentic application to handle customer support inquiries with personalized support and faster time to resolution. Also, a *Pear Genius* chatbot is integrateed into *Pear Store*\n\n* *Pear Store*: An Apple.com-like website containing an online store and customer support pages\n\n* *Pear Services*: Ten API services supporting *Pear Co*'s enterprise architecture, including backend API support for *Pear Store* and *Pear Genius* (via MCP)\n\n* *Pear Auth*: Authentication and Authorization for *Pear Co.* customers and employees; implemented using [**Keycloak**](https://www.keycloak.org)\n\n* *Pear Gateway*: a dual-purpose API/agent gateway (REST and MCP) that is used by *Pear Store* and *Pear Genius*, and integrates with *Pear Auth*; implemented using [**agentgateway**](https://agentgateway.dev)\n\n## Architecture\n\n```\n┌────────────────────────────────────────────────────────────────────────┐\n│  Frontend (pear-store)                                                 │\n│  Next.js + Zustand + SSE streaming                      Port 3001      │\n└───────────────────────────────────┬────────────────────────────────────┘\n                                    │  HTTP + SSE (Chat API)\n                                    ▼\n┌────────────────────────────────────────────────────────────────────────┐\n│  API Gateway (AgentGateway as a dual-purpose proxy)     Port 3000      │\n│  /api/chat                                                             │\n└───────────────────────────────────┬────────────────────────────────────┘\n                                    │  HTTP + SSE (Chat API)\n                                    ▼\n┌────────────────────────────────────────────────────────────────────────┐\n│  Agent Server (pear-genius)                                            │\n│  FastAPI + LangGraph + Claude LLM                       Port 8000      │\n│                                                                        │\n│  ┌──────────────────────────────────────────────────────────────┐      │\n│  │  LangGraph State Machine                                     │      │\n│  │                                                              │      │\n│  │  agent ──→ should_continue ──→ approval_gate ──→ tools ──→ agent    │\n│  │    │                              │                          |      │\n│  │    └──→ END                       └──→ interrupt() ──→ resume       │\n│  └──────────────────────────────────────────────────────────────┘      │\n│                              │                                         │\n│                              │ MCP (streamable-HTTP)                   │\n│                              ▼                                         │\n└────────────────────────────────────────────────────────────────────────┘\n                                    │\n                                    ▼\n┌────────────────────────────────────────────────────────────────────────┐\n│  AgentGateway (MCP → REST proxy)                         Port 3000     │\n│  Reads OpenAPI specs → Exposes as MCP tools                            │\n│  POST /mcp (streamable-HTTP transport)                                 │\n└───────────────────────────────────┬────────────────────────────────────┘\n                                    │  REST API calls\n                                    ▼\n┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐\n│  order-  │ product- │customer- │shipping  │product-  │physical- │\n│  mgmt    │ support  │ accounts │          │ catalog  │ stores   │\n│  :8081   │  :8083   │  :8084   │  :8082   │  :8085   │  :8087   │\n└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘\n        Express/Node.js microservices (OpenAPI-first)\n```\n\n## Screenshots and Examples\n\n### Pear Store Screenshots\n\n\u003cimg src=\"images/shop.png\" width=\"800\"\u003e\n\n\u003cimg src=\"images/bag.png\" width=\"800\"\u003e\n\n\u003cimg src=\"images/support.png\" width=\"800\"\u003e\n\n## Pear Genius Examples\n\n\u003e **Note:** This is an interim version that is CLI-only. A web-based version is coming soon!\n\n```\nStarting Pear Genius...\n============================================================\n  Pear Genius - Customer Support Agent\n============================================================\n\nAuthenticated as: John Smith (plus member)\n\nPear Genius: Hello John Smith! I'm Pear Genius, your personal support assistant. I can help you with orders, returns, warranty questions, troubleshooting, and more. How can I assist you today?\n\nYou: where is my order?\n\n  Tools used: getOrder\n\nPear Genius: Here's the status of your recent orders:\n\n## Order #PEAR-2024-123456 (ORD-2024-001) ✅ **DELIVERED**\n- **Items**: PearPhone 16 Pro (Space Black, 256GB) + Clear Case\n- **Status**: Delivered on January 17th at 2:30 PM\n- **Delivery**: Left at front door as requested\n- **Tracking**: FedEx #1234567890123456\n\n## Order #PEAR-2024-123458 (ORD-2024-003) 🚚 **IN TRANSIT**\n- **Items**: PearPods Pro 2 (White) - Gift order with \"Happy Birthday!\" message\n- **Status**: Currently in transit from Phoenix, AZ\n- **Expected Delivery**: January 23rd\n- **Tracking**: UPS #1Z999AA10123456784\n- **Latest Update**: In transit to destination (Phoenix, AZ - Jan 21, 6:00 PM)\n\nYour PearPhone order has already been delivered, and your PearPods Pro 2 should arrive by January 23rd. You can track the PearPods shipment using the UPS tracking number above.\n\nIs there anything specific about either order you'd like me to help you with?\n```\n\n```\nYou: My PearPhone screen is cracked. Is it covered under warranty?\n\n  Tools used: getOrder, checkReturnEligibility, createReturn, runDiagnostics\n\nPear Genius: **Regarding warranty coverage for your cracked screen:**\n\nUnfortunately, **physical damage like cracked screens is typically NOT covered** under Pear's Limited Warranty. The warranty covers:\n- Manufacturing defects\n- Hardware failures not caused by damage\n- Software issues\n\nHowever, the diagnostics show that while your display functions are working normally, there are some issues with your camera and speaker/microphone that might be related to the physical damage.\n\n## Your Repair Options:\n\n1. **Out-of-warranty screen replacement**\n   - Estimated cost: $279-$329 for PearPhone 16 Pro\n   - Performed by certified technicians\n   - Genuine Pear parts with 90-day repair warranty\n\n2. **PearCare+ Coverage (if you have it)**\n   - If you purchased PearCare+, screen damage is covered for just $29 deductible\n   - Would you like me to check if you have PearCare+ on this device?\n\n3. **Comprehensive repair**\n   - Given the camera and audio issues detected, you might want a full assessment\n   - These additional issues could potentially be warranty-covered if they're not damage-related\n\n## Next Steps:\n1. **Schedule a Genius Grove appointment** for an in-person assessment\n2. **Get an exact repair quote** - they can assess if the camera/audio issues are related to the screen damage\n3. **Back up your device** before any service\n\nWould you like me to help you find your nearest Genius Grove location or check if you have PearCare+ coverage on this device?\n```\n\n## Technical Overview\n\n\u003e **Note:** Most of the code for this demo was generated using Claude Code.\n\n### *Pear Genius* Implementation\n\n* Impemented agents are **Supervisor**, **Order**, **Warranty**, and **Troubleshoot** (see Agents.md for more information)\n* Agentic features implemented using LangChain and LangGraph\n* All LangChain tools are implemented using MCP clients (see *Pear Gateway*'s `agentgateway` and `langchain-mcp-adapters`)\n* Implemented in Python with `uv` package management\n\n### *Pear Services* Implementation\n\n* 10 REST API microservice implementations (located under `pear-services`)\n* Each service has it's own OpenAPI specification (located at `server/api/openapi.yaml`)\n* **OpenAPI Generator** was used to generate Node.js JavaScript Express REST microservice stub code\n* **Claude Code** was used to generate the OpenAPI specs, document the OpenAPI specs, finish the implementation of the microservices, and generate sample data\n\n\u003e **Important:** The *Pear Services* OpenAPI specs are completely documented to be understandable by an LLM for the purpose of making tool calls, as the REST APIs are translated into MCP Tools. This is important, as there may be many tools available to the LLM, and proper documentation is important for correct tool usage.\n\n### *Pear Store* Implementation\n\n* A full-featured online store implemented using Next.js and TypeScript\n* `@hey-api/openapi-ts` was used to generate REST client implementations from *Pear Services* OpenAPI specifications\n* Product and customer support pages\n* Integrated chatbot to communicate with *Pear Genius*\n* Integrated authentication with *Pear Auth*\n\n### *Pear Auth* Implementation\n\n* Authentication (AuthN) for *Pear Co.* customers and employees\n* Authorization (AuthZ) based on user roles to control access to APIs and MCP Tools\n* Implemented using [**Keycloak**](https://www.keycloak.org)\n\n### *Pear Gateway* Implementation\n\n* Implemented using [**agentgateway**](https://agentgateway.dev)\n* Dual-purpose MCP and REST API gateway that is used by *Pear Store* and *Pear Genius*\n* Integrates with *Pear Auth* for AuthZ\n* MCP tools are created by **agentgateway** from the *Pear Services* OpenAPI specifications\n* *Pear Auth* is used to provide authentication and authorization for MCP Tools and REST APIs\n\n## Running the Demo\n\nThis demo can be run locally from the terminal and has been tested on Mac. It requires the presence of `node` and `python3` Tested using `node`. v25.2.0 and `python3` 3.14.2, but it may work with lower versions.\n\n### 1. Run *Pear Auth* (Keycloak)\n\nFor running Keycloak, `docker` or `podman` is required.\n\n```shell\ndocker TODO\n```\n\n### 2. Run *Pear Services* (`npm`/Node)\n\nAll ten Node services can be built and run concurrently from a top-level `npm` command, rather than having to do it individually. See `pear-services/package.json`. \n\n```shell\ncd pear-services\nnpm install\nnpm run start-services\n```\n\nThe services will now be running on ports 8080 to 8090.\n\n**Control+C** to stop the services from running.\n\n### 3. Run *Pear Gateway* (`agentgateway`)\n\n```shell\ncurl -sL https://agentgateway.dev/install | bash\nagentgateway -f agentgateway.yaml\n```\n\n`agentgateway` will now be running on port 3000.\n\n### 4. Run *Pear Store* (`npm`/Next.js)\n\n```shell\ncd pear-store\nnpm install\nnpm run dev\n```\n\n**Control+C** to stop Next.js from running.\n\n### 5. Run *Pear Genius* (Python)\n\n[Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) first, such as running `brew install uv`.\n\n#### Configure `.env`\n\n```shell\ncp .env.example .env\n```\n\nEdit .env and add your `ANTHROPIC_API_KEY`.\n\n#### Setup Python `venv`\n\n```shell\ncd pear-genius\nuv venv\nuv pip install -e .\n```\n\n#### Interactive CLI\n\n```shell\nuv run pear-genius\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmurphye%2Fagentic-mcp-gateway-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmurphye%2Fagentic-mcp-gateway-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmurphye%2Fagentic-mcp-gateway-demo/lists"}