Copilot for Retail

A multi-agent AI copilot for the retail industry, built on the Microsoft 365 Agents Toolkit. The system uses a manager-coordinates-specialists (Magentic) orchestration pattern where a single orchestrator agent routes requests to 6 domain-specialist agents, each backed by domain-specific MCP (Model Context Protocol) servers connected to Dynamics 365 Commerce / Finance & Operations.

Summary: 1 orchestrator + 6 specialist agents, 7 plugins, 9 MCP servers, ~40 commands, ~50 skills.

Architecture

                         ┌──────────────────────────────────┐
                         │     Microsoft 365 / Teams         │
                         │     (User Interaction Layer)      │
                         └──────────────┬───────────────────┘
                                        │
                         ┌──────────────▼───────────────────┐
                         │   RETAIL COPILOT ORCHESTRATOR     │
                         │   (Custom Engine Agent)           │
                         └──┬───┬───┬───┬───┬───┬───────────┘
                            │   │   │   │   │   │
           ┌────────────────┘   │   │   │   │   └──────────────┐
           ▼        ▼           ▼   ▼   ▼              ▼
  ┌─────────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐
  │Merchandising│ │  Store   │ │ Customer   │ │ Supply   │ │ Pricing &  │ │Workforce │
  │& Inventory  │ │Operations│ │ Engagement │ │ Chain    │ │ Analytics  │ │Management│
  │(Declarative)│ │(Declare.)│ │(Custom Eng)│ │(Declare.)│ │(Custom Eng)│ │(Declare.)│
  └──────┬──────┘ └────┬─────┘ └─────┬──────┘ └────┬─────┘ └─────┬──────┘ └────┬─────┘
         │              │             │              │             │              │
  ┌──────▼──────────────▼─────────────▼──────────────▼─────────────▼──────────────▼─────┐
  │                              MCP SERVER LAYER                                        │
  │  mcp-erp-pos │ mcp-product-catalog │ mcp-crm-loyalty │ mcp-wms-oms                  │
  │  mcp-market-intel │ mcp-workforce │ mcp-m365-graph │ mcp-commerce │ mcp-external-data│
  └──────────────────────────────────────────────────────────────────────────────────────┘

Orchestration patterns:

Magentic (primary): Orchestrator classifies intent, dispatches to one or more specialists concurrently, and synthesizes their responses. Used for cross-domain queries like "Prepare for Black Friday" (triggers Merchandising + Pricing + Workforce).
Handoff (secondary): For deep, multi-turn conversations the orchestrator hands off context to a single specialist agent for the duration of the conversation thread.

Agents

1. Retail Copilot Orchestrator

Property	Value
Type	Custom Engine Agent
Package	`@copilot-retail/orchestrator`
Path	`agents/orchestrator/`
Plugin	`plugin-core-retail`
Runtime	Express + Teams AI SDK

Purpose: The single customer-facing entry point in Microsoft Teams. Receives all user messages, classifies intent using keyword matching (upgradable to LLM-based classification), routes to the appropriate specialist agent(s), and synthesizes multi-agent responses into a single coherent reply.

Key Components:

Component	File	Responsibility
Agent Router	`src/agents/agentRouter.ts`	Intent classification via keyword map across 7 retail domains; concurrent dispatch to multiple agents; confidence scoring
Response Composer	`src/agents/responseComposer.ts`	Merges responses from multiple specialist agents into a unified reply
Role Adapter	`src/middleware/roleAdapter.ts`	Detects user role (Store Manager vs HQ/Buyer) from AAD profile; filters available commands and agent routing priorities
Command Handler	`src/handlers/commandHandler.ts`	Processes slash commands: `/retail-help`, `/switch-domain`, `/escalate`, `/summarize-session`, `/retail-kpi`

Communicates with: All 6 specialist agents via HTTP (configurable endpoints per environment). Directly accesses mcp-m365-graph and mcp-erp-pos for user profile lookups and top-level KPI data.

2. Merchandising & Inventory Agent

Property	Value
Type	Declarative Agent
Path	`agents/merchandising-agent/`
Plugin	`plugin-merchandising`
Config	`declarativeAgent.json`

Purpose: Manages all inventory and merchandising concerns — stock level queries, demand forecasting, assortment planning, catalog enrichment, and reorder recommendations. Uses Copilot's built-in orchestration to select the right MCP tools based on the query.

Commands (6):

Command	Description
`/inventory-check`	Check stock levels by SKU, store, or warehouse
`/demand-forecast`	Generate demand forecast for a product/category over a time horizon
`/reorder-suggest`	Get automated reorder suggestions based on velocity, lead time, safety stock
`/catalog-enrich`	AI-enrich product catalog entries with generated attributes and tags
`/assortment-plan`	Create or review assortment plans by store cluster
`/stockout-risk`	Identify products at risk of stockout within a configurable window

Skills (8): Inventory analysis, demand forecasting, assortment optimization, catalog enrichment, reorder logic, seasonal planning, ABC analysis, planogram guidance

MCP Servers: mcp-erp-pos, mcp-product-catalog, mcp-wms-oms

3. Store Operations Agent

Property	Value
Type	Declarative Agent
Path	`agents/store-ops-agent/`
Plugin	`plugin-store-ops`
Config	`declarativeAgent.json`

Purpose: Supports store managers with policy lookups, compliance checks, daily task management, loss prevention alerts, and store-level KPI monitoring. Pulls policies from SharePoint via Graph and operational data from ERP.

Commands (6):

Command	Description
`/policy-lookup`	Search store operating policies and procedures
`/compliance-check`	Run compliance audit check against store standards
`/daily-ops`	Generate daily operations briefing (sales, tasks, alerts)
`/loss-alert`	View current loss prevention alerts and shrinkage data
`/store-kpi`	Display store performance KPI dashboard
`/task-assign`	Create and assign tasks to store team members

Skills (7): Policy retrieval, compliance audit, loss prevention, store performance, daily operations, task management, incident reporting

MCP Servers: mcp-erp-pos, mcp-m365-graph, mcp-workforce

4. Customer Engagement Agent

Property	Value
Type	Custom Engine Agent
Package	`@copilot-retail/customer-engagement-agent`
Path	`agents/customer-engagement-agent/`
Plugin	`plugin-customer`
Runtime	Express + Teams AI SDK

Purpose: Handles personalized product recommendations, loyalty program management, customer service ticket triage, and omnichannel journey analysis. Requires a Custom Engine due to its recommendation engine (collaborative filtering, content-based matching) and churn prediction model.

Key Components:

Component	File	Responsibility
Recommendation Engine	`src/engines/recommendationEngine.ts`	Collaborative filtering, content-based recommendations, outfit/bundle building
Churn Predictor	`src/engines/churnPredictor.ts`	Customer churn risk scoring based on recency, frequency, monetary value
Command Handler	`src/handlers/commandHandler.ts`	Handles 7 slash commands

Commands (7):

Command	Description
`/customer-lookup`	Look up customer profile by name, email, loyalty ID, or phone
`/recommend`	Generate personalized product recommendations for a customer
`/loyalty-status`	Check loyalty tier, points balance, rewards, and tier progress
`/ticket-create`	Create a customer service ticket with category and priority
`/journey-view`	Visualize customer's omnichannel journey (touchpoints over time)
`/personalize`	Generate personalized offers or communications for a customer
`/segment-analyze`	Analyze a customer segment's behavior, value, and trends

Skills (9): Customer profiling, product recommendations, outfit/bundle building, loyalty management, sentiment analysis, ticket triage, journey mapping, churn prediction, cross-sell/upsell

MCP Servers: mcp-crm-loyalty, mcp-product-catalog, mcp-commerce, mcp-external-data

5. Supply Chain Agent

Property	Value
Type	Declarative Agent
Path	`agents/supply-chain-agent/`
Plugin	`plugin-supply-chain`
Config	`declarativeAgent.json`

Purpose: Tracks orders through the fulfillment pipeline, evaluates vendor performance, identifies supply chain risks, and recommends inventory rebalancing across warehouses and stores.

Commands (5):

Command	Description
`/track-order`	Track an order through the fulfillment pipeline by order ID
`/vendor-scorecard`	Generate vendor performance scorecard (on-time rate, quality, cost)
`/fulfillment-status`	View fulfillment pipeline status by warehouse or store
`/supply-risk`	Assess supply chain risk factors (lead time, vendor, logistics)
`/rebalance-suggest`	Suggest inventory transfers between locations to optimize distribution

Skills (6): Order tracking, vendor evaluation, fulfillment optimization, supply risk assessment, logistics planning, lead time analysis

MCP Servers: mcp-wms-oms, mcp-erp-pos, mcp-external-data

6. Pricing & Analytics Agent

Property	Value
Type	Custom Engine Agent
Package	`@copilot-retail/pricing-analytics-agent`
Path	`agents/pricing-analytics-agent/`
Plugin	`plugin-pricing`
Runtime	Express + Teams AI SDK

Purpose: Handles dynamic pricing decisions, competitor price monitoring, margin optimization, promotional impact analysis, and sales dashboards. Requires a Custom Engine for its pricing engine (elasticity calculations, markdown optimization algorithms) and analytics engine.

Key Components:

Component	File	Responsibility
Pricing Engine	`src/engines/pricingEngine.ts`	Price elasticity calculation, markdown optimization, competitor-based pricing rules
Analytics Engine	`src/engines/analyticsEngine.ts`	Sales analytics, margin calculations, trend detection, anomaly identification
Command Handler	`src/handlers/commandHandler.ts`	Handles 6 slash commands

Commands (6):

Command	Description
`/price-check`	Look up current, historical, and competitor prices for a product
`/competitor-analysis`	Compare pricing and positioning against competitors
`/margin-report`	Generate margin analysis by product, category, or store
`/promo-impact`	Analyze the impact of a promotion on sales, margin, and cannibalization
`/sales-dashboard`	Generate a sales performance dashboard for a given period
`/price-recommend`	Get AI-generated pricing recommendations based on elasticity and competition

Skills (7): Price elasticity, competitor monitoring, margin optimization, promotional analysis, sales trends, dynamic pricing, markdown optimization

MCP Servers: mcp-erp-pos, mcp-market-intel, mcp-commerce

7. Workforce Management Agent

Property	Value
Type	Declarative Agent
Path	`agents/workforce-agent/`
Plugin	`plugin-workforce`
Config	`declarativeAgent.json`

Purpose: Manages staff scheduling, labor cost forecasting, skills gap identification, shift coverage analysis, and training recommendations.

Commands (5):

Command	Description
`/schedule-view`	View staff schedules by store, department, or employee
`/labor-forecast`	Forecast labor needs based on projected sales and traffic
`/skills-match`	Find employees matching required skills for a role or task
`/shift-coverage`	Analyze shift coverage gaps and suggest fills
`/training-suggest`	Recommend training programs based on skills gaps and career paths

Skills (6): Schedule optimization, labor forecasting, skills gap analysis, shift planning, training paths, overtime management

MCP Servers: mcp-workforce, mcp-m365-graph

Agent Communication Matrix

This matrix shows how each agent communicates: who it talks to, via what protocol, and for what purpose.

Agent-to-Agent Communication

The orchestrator is the sole coordinator. Specialist agents do not communicate directly with each other — all inter-agent communication flows through the orchestrator.

Source	Target	Protocol	Direction	Purpose
Orchestrator	Merchandising	HTTP REST	Request/Response	Inventory queries, demand forecasts, assortment plans
Orchestrator	Store Ops	HTTP REST	Request/Response	Policy lookups, compliance checks, daily ops briefings
Orchestrator	Customer Engagement	HTTP REST	Request/Response	Customer lookups, recommendations, loyalty queries
Orchestrator	Supply Chain	HTTP REST	Request/Response	Order tracking, vendor scorecards, fulfillment status
Orchestrator	Pricing & Analytics	HTTP REST	Request/Response	Price checks, competitor analysis, margin reports
Orchestrator	Workforce	HTTP REST	Request/Response	Schedule views, labor forecasts, skills matching
Teams / M365	Orchestrator	Bot Framework	Bidirectional	User messages in, bot responses out

Cross-Domain Query Flow

When a user asks a cross-domain question (e.g., "Prepare for Black Friday"), the orchestrator dispatches to multiple agents concurrently and synthesizes their responses:

User: "Prepare for Black Friday"
  │
  ▼
Orchestrator (classifyIntent → routes to 3 domains)
  ├──► Merchandising Agent  →  "Stock up on top sellers, review seasonal assortment"
  ├──► Pricing Agent         →  "Competitor price benchmarks, promo calendar review"
  └──► Workforce Agent       →  "Increase staffing 40%, schedule training by Oct 15"
  │
  ▼
Orchestrator (composeResponse → unified reply)
  │
  ▼
User receives synthesized action plan

Agent-to-MCP Server Communication

Agent	mcp-erp-pos	mcp-product-catalog	mcp-crm-loyalty	mcp-wms-oms	mcp-market-intel	mcp-workforce	mcp-m365-graph	mcp-commerce	mcp-external-data
Orchestrator	X						X
Merchandising	X	X		X
Store Ops	X					X	X
Customer Engagement		X	X					X	X
Supply Chain	X			X					X
Pricing & Analytics	X				X			X
Workforce						X	X

Communication Summary

Agent	Agents It Talks To	MCP Servers	Total Connections
Orchestrator	6 (all specialists)	2	8
Merchandising	0 (receives from Orchestrator)	3	3
Store Ops	0	3	3
Customer Engagement	0	4	4
Supply Chain	0	3	3
Pricing & Analytics	0	3	3
Workforce	0	2	2

MCP Servers & Data Sources

MCP Server Inventory

#	Server	Port	Status	Backend System	Purpose
1	`mcp-erp-pos`	3001	Implemented	Dynamics 365 Commerce / F&O	Sales data, transaction history, financial summaries, store performance, product sales
2	`mcp-product-catalog`	3002	Implemented	Dynamics 365 Commerce	Product search, details, attributes, variants, AI-enriched attributes, similarity
3	`mcp-wms-oms`	3004	Implemented	Dynamics 365 Supply Chain Mgmt	Inventory levels, order status, fulfillment pipeline, shipment tracking, backorders
4	`mcp-crm-loyalty`	3003	Stub (Phase 2)	Dynamics 365 Customer Insights	Customer profiles, loyalty status, purchase history, segments, campaign performance
5	`mcp-m365-graph`	3007	Stub (Phase 2)	Microsoft Graph API	Email search, calendar events, Teams messages, file search, org directory
6	`mcp-workforce`	3006	Stub (Phase 2)	Dynamics 365 Human Resources	Staff schedules, labor analytics, performance metrics, attendance, staffing forecasts
7	`mcp-commerce`	3008	Stub (Phase 2)	Dynamics 365 Commerce (Online)	Storefront config, active promotions, pricing rules, channel analytics, cart abandonment
8	`mcp-market-intel`	3005	Stub (Phase 3)	Third-party APIs	Competitive pricing, market trends, market share, consumer sentiment, category benchmarks
9	`mcp-external-data`	3009	Stub (Phase 3)	Third-party APIs	Weather forecasts, demographic data, economic indicators, social trends, foot traffic

Tool Inventory by MCP Server

mcp-erp-pos (5 tools) — Implemented

Tool	Description	Key Parameters
`get_sales_data`	Sales summary by store, date range, channel	`storeId`, `startDate`, `endDate`, `channel`
`get_transaction_history`	Individual transaction records	`storeId`, `terminalId`, `startDate`, `endDate`, `transactionType`, `limit`
`get_financial_summary`	P&L summary by period	`storeId`, `period`, `fiscalYear`
`get_store_performance`	Store KPIs (revenue, conversion, shrinkage, etc.)	`storeId`, `startDate`, `endDate`, `metrics[]`
`get_product_sales`	Product-level sales breakdown	`productId`, `categoryId`, `storeId`, `startDate`, `endDate`, `topN`

mcp-product-catalog (5 tools) — Implemented

Tool	Description	Key Parameters
`search_products`	Full-text product search with filters	`query`, `categoryId`, `minPrice`, `maxPrice`, `sortBy`, `limit`
`get_product_details`	Complete product record with variants and media	`productId`, `includeVariants`, `includeMedia`
`get_product_attributes`	Product attribute values by group	`productId`, `attributeGroupId`
`get_similar_products`	Find products similar by attributes/category	`productId`, `maxResults`, `strategy`
`enrich_product_attributes`	AI-generated attribute enrichment	`productId`, `enrichmentType`

mcp-wms-oms (5 tools) — Implemented

Tool	Description	Key Parameters
`get_inventory_levels`	On-hand, reserved, available, reorder point by location	`productId`, `storeId`, `warehouseId`, `belowReorderPoint`
`get_order_status`	Full order details with line items and shipments	`orderId`
`get_fulfillment_status`	Fulfillment pipeline (pick/pack/ship)	`storeId`, `warehouseId`, `status`, `startDate`, `endDate`
`get_shipment_tracking`	Carrier tracking with event history	`shipmentId`, `orderId`, `trackingNumber`
`get_backorder_list`	Items on backorder with expected arrival dates	`storeId`, `warehouseId`, `categoryId`, `sortBy`

mcp-crm-loyalty (5 tools) — Planned

Tool	Description
`get_customer_profile`	Customer demographics, preferences, lifetime value
`get_loyalty_status`	Loyalty tier, points balance, rewards history
`get_purchase_history`	Customer purchase history across channels
`get_customer_segments`	Segment membership and behavioral attributes
`get_campaign_performance`	Marketing campaign results by segment

mcp-m365-graph (5 tools) — Planned

Tool	Description
`search_emails`	Search Outlook emails by keyword, sender, date
`get_calendar_events`	Get calendar events for scheduling context
`search_teams_messages`	Search Teams channel and chat messages
`search_files`	Search SharePoint/OneDrive files (policies, SOPs)
`get_org_people`	Organizational directory and people search

mcp-workforce (5 tools) — Planned

Tool	Description
`get_staff_schedule`	Employee schedules by store, department, date range
`get_labor_analytics`	Labor hours, cost, productivity metrics
`get_staff_performance`	Employee performance ratings and metrics
`get_attendance_summary`	Attendance, tardiness, absence patterns
`get_staffing_forecast`	Projected staffing needs based on demand

mcp-commerce (5 tools) — Planned

Tool	Description
`get_storefront_config`	E-commerce storefront configuration
`get_active_promotions`	Currently active online/in-store promotions
`get_pricing_rules`	Pricing rules, trade agreements, price groups
`get_channel_analytics`	Online channel KPIs (traffic, conversion, AOV)
`get_cart_abandonment`	Cart abandonment rates and recovery data

mcp-market-intel (5 tools) — Planned

Tool	Description
`get_competitive_pricing`	Competitor product prices and positioning
`get_market_trends`	Category and market trend analysis
`get_market_share`	Market share estimates by category/brand
`get_consumer_sentiment`	Consumer sentiment from reviews and social media
`get_category_benchmarks`	Industry benchmark KPIs by retail category

mcp-external-data (5 tools) — Planned

Tool	Description
`get_weather_forecast`	Weather forecasts for store locations (demand impact)
`get_demographic_data`	Trade area demographics for store planning
`get_economic_indicators`	CPI, unemployment, consumer confidence indices
`get_social_trends`	Social media trend data for demand signals
`get_foot_traffic_data`	Foot traffic patterns by location and time

Authentication & Credentials

Every MCP server uses a connector adapter pattern to authenticate with its backend system. The table below details each data source, the authentication method required, and the credentials needed.

Authentication Matrix

Data Source	MCP Server(s)	Auth Method	Auth Flow	Required Credentials	Token Endpoint
Dynamics 365 Commerce / F&O	`mcp-erp-pos`, `mcp-product-catalog`, `mcp-wms-oms`, `mcp-crm-loyalty`, `mcp-workforce`, `mcp-commerce`	OAuth 2.0 Client Credentials	Service-to-service (no user interaction)	`D365_TENANT_ID`, `D365_CLIENT_ID`, `D365_CLIENT_SECRET`, `D365_ENVIRONMENT`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`
Dynamics 365 Customer Insights	`mcp-crm-loyalty`	OAuth 2.0 Client Credentials	Service-to-service	Same AAD app registration as above (shared tenant)	Same as above
Microsoft Graph API	`mcp-m365-graph`	OAuth 2.0 Authorization Code + Delegated	On-behalf-of (OBO) flow — acts as the signed-in user	`GRAPH_TENANT_ID`, `GRAPH_CLIENT_ID`, `GRAPH_CLIENT_SECRET` + user's access token	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`
Weather API	`mcp-external-data`	API Key	Key in request header	`WEATHER_API_KEY`	N/A
Demographics / Foot Traffic Provider	`mcp-external-data`	API Key	Key in request header	`DEMOGRAPHICS_API_KEY`	N/A
Economic Data (e.g., FRED)	`mcp-external-data`	API Key	Key in query parameter	`ECONOMIC_DATA_API_KEY`	N/A
Social Trends Provider	`mcp-external-data`	API Key	Key in request header	`SOCIAL_TRENDS_API_KEY`	N/A
Competitive Pricing Provider	`mcp-market-intel`	OAuth 2.0 Client Credentials or API Key	Varies by provider	`MARKET_INTEL_API_KEY` or `MARKET_INTEL_CLIENT_ID` + `MARKET_INTEL_CLIENT_SECRET`	Provider-specific
Teams Bot Framework	`orchestrator`	Bot Framework Auth	AAD app registration for bot identity	`BOT_ID`, `BOT_PASSWORD`	Microsoft Bot Framework token service

Authentication Details

Dynamics 365 (OAuth 2.0 Client Credentials)

All 6 Dynamics 365-backed MCP servers share the same authentication pattern:

Azure AD App Registration — Register an application in Azure AD with the following API permissions:
- Dynamics CRM > user_impersonation (for D365 Commerce / F&O)
- Dynamics 365 Business Central > Financials.ReadWrite.All (if using BC)

Client Credentials Flow — Token request:

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={clientId}
&client_secret={clientSecret}
&scope=https://{environment}.operations.dynamics.com/.default

Token caching — All connectors implement ensureAuthenticated() which caches the token and refreshes when expiresOn is reached.
OData 4.0 — All D365 API calls use OData v4.0 with Bearer token in the Authorization header.

Environment variables required:

D365_TENANT_ID=<Azure AD tenant GUID>
D365_CLIENT_ID=<App registration client ID>
D365_CLIENT_SECRET=<App registration client secret>
D365_ENVIRONMENT=<D365 environment name, e.g., "contoso-prod">

Microsoft Graph (OAuth 2.0 On-Behalf-Of)

The mcp-m365-graph server uses delegated permissions to act as the signed-in user:

Azure AD App Registration — API permissions:
- Microsoft Graph > Mail.Read
- Microsoft Graph > Calendars.Read
- Microsoft Graph > ChannelMessage.Read.All
- Microsoft Graph > Files.Read.All
- Microsoft Graph > People.Read

On-Behalf-Of Flow — The bot receives the user's access token and exchanges it for a Graph token:

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id={clientId}
&client_secret={clientSecret}
&assertion={userAccessToken}
&scope=https://graph.microsoft.com/.default
&requested_token_use=on_behalf_of

Environment variables required:

GRAPH_TENANT_ID=<Azure AD tenant GUID>
GRAPH_CLIENT_ID=<Graph app client ID>
GRAPH_CLIENT_SECRET=<Graph app client secret>

External APIs (API Key)

Third-party data providers (mcp-external-data, mcp-market-intel) use simple API key authentication:

WEATHER_API_KEY=<API key for weather provider>
DEMOGRAPHICS_API_KEY=<API key for demographics provider>
ECONOMIC_DATA_API_KEY=<API key for economic data provider (e.g., FRED)>
SOCIAL_TRENDS_API_KEY=<API key for social trends provider>
MARKET_INTEL_API_KEY=<API key for competitive intelligence provider>

Bot Framework

The orchestrator bot authenticates with Microsoft Bot Framework:

BOT_ID=<Azure AD app ID for the bot>
BOT_PASSWORD=<Azure AD app secret for the bot>

Credential Storage

All credentials are stored in Azure Key Vault and injected as environment variables at runtime:

Local development: .env file (git-ignored)
Azure deployment: Key Vault references in App Service / Container Apps configuration
CI/CD: Pipeline secrets mapped from Key Vault

Role-Based Access

The orchestrator's role adapter middleware detects the user's role from their Azure AD profile and adapts the experience:

Capability	Store Manager	HQ / Buyer
`/inventory-check`	X	X
`/demand-forecast`		X
`/reorder-suggest`		X
`/catalog-enrich`		X
`/assortment-plan`		X
`/stockout-risk`	X	X
`/policy-lookup`	X
`/compliance-check`	X
`/daily-ops`	X
`/loss-alert`	X
`/store-kpi`	X	X
`/task-assign`	X
`/customer-lookup`	X	X
`/recommend`	X	X
`/loyalty-status`	X	X
`/ticket-create`	X
`/journey-view`		X
`/personalize`		X
`/segment-analyze`		X
`/track-order`	X	X
`/vendor-scorecard`		X
`/fulfillment-status`	X	X
`/supply-risk`		X
`/rebalance-suggest`		X
`/price-check`	X	X
`/competitor-analysis`		X
`/margin-report`		X
`/promo-impact`		X
`/sales-dashboard`	X	X
`/price-recommend`		X
`/schedule-view`	X	X
`/labor-forecast`		X
`/skills-match`	X
`/shift-coverage`	X
`/training-suggest`	X	X

Agent routing priority by role:

Store Manager: Store Ops > Workforce > Merchandising > Customer Engagement > Supply Chain > Pricing
HQ / Buyer: Pricing > Merchandising > Supply Chain > Customer Engagement > Store Ops > Workforce

Project Structure

CopilotRetail/
├── package.json                     # Monorepo root (npm workspaces)
├── turbo.json                       # Build orchestration
├── tsconfig.base.json               # Shared TypeScript config
├── CopilotRetail.md                 # Full solution plan
│
├── packages/
│   ├── shared-types/                # @copilot-retail/shared-types
│   │   └── src/                     # Product, Store, Customer, Order, Inventory, Workforce, Pricing, Common types
│   └── shared-utils/                # @copilot-retail/shared-utils
│       └── src/                     # KPI calculators, formatters
│
├── plugins/                         # Plugin definitions
│   ├── plugin-core-retail/          # 5 commands, 7 skills
│   ├── plugin-merchandising/        # 6 commands, 8 skills
│   ├── plugin-store-ops/            # 6 commands, 7 skills
│   ├── plugin-customer/             # 7 commands, 9 skills
│   ├── plugin-supply-chain/         # 5 commands, 6 skills
│   ├── plugin-pricing/              # 6 commands, 7 skills
│   └── plugin-workforce/            # 5 commands, 6 skills
│
├── agents/                          # Agent implementations
│   ├── orchestrator/                # Custom Engine — intent routing, multi-agent dispatch
│   ├── merchandising-agent/         # Declarative
│   ├── store-ops-agent/             # Declarative
│   ├── customer-engagement-agent/   # Custom Engine — recommendation + churn engines
│   ├── supply-chain-agent/          # Declarative
│   ├── pricing-analytics-agent/     # Custom Engine — pricing + analytics engines
│   └── workforce-agent/             # Declarative
│
├── mcp-servers/                     # MCP Server implementations
│   ├── mcp-erp-pos/                 # Dynamics 365 Commerce — sales, transactions, financials
│   ├── mcp-product-catalog/         # Dynamics 365 Commerce — product catalog
│   ├── mcp-wms-oms/                 # Dynamics 365 SCM — inventory, orders, fulfillment
│   ├── mcp-crm-loyalty/             # Dynamics 365 Customer Insights (stub)
│   ├── mcp-market-intel/            # Third-party market data (stub)
│   ├── mcp-workforce/               # Dynamics 365 HR (stub)
│   ├── mcp-m365-graph/              # Microsoft Graph API (stub)
│   ├── mcp-commerce/                # Dynamics 365 Commerce online (stub)
│   └── mcp-external-data/           # Third-party external data (stub)
│
├── infra/                           # Infrastructure as Code
│   ├── bicep/                       # Azure Bicep templates
│   └── pipelines/                   # CI/CD pipelines
│
├── tests/
│   ├── integration/                 # Orchestrator routing, MCP connectivity
│   └── e2e/                         # Full scenario tests
│
└── docs/                            # Architecture and deployment docs

Getting Started

Prerequisites

Node.js 20+
npm 10+
Azure subscription with Dynamics 365 Commerce / F&O
Azure AD app registrations (bot + D365 + Graph)
Microsoft 365 developer tenant (for Teams testing)
Teams Toolkit extension for VS Code (recommended)

Setup

# Clone and install
git clone <repo-url>
cd CopilotRetail
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials (see Authentication section)

# Build all packages
npm run build

# Run tests
npm run test

# Start development (all agents + MCP servers)
npm run dev

Environment Variables

Create a .env file in the project root:

# Bot Framework
BOT_ID=
BOT_PASSWORD=

# Dynamics 365
D365_TENANT_ID=
D365_CLIENT_ID=
D365_CLIENT_SECRET=
D365_ENVIRONMENT=

# Microsoft Graph
GRAPH_TENANT_ID=
GRAPH_CLIENT_ID=
GRAPH_CLIENT_SECRET=

# External APIs
WEATHER_API_KEY=
DEMOGRAPHICS_API_KEY=
ECONOMIC_DATA_API_KEY=
SOCIAL_TRENDS_API_KEY=
MARKET_INTEL_API_KEY=

# Agent endpoints (defaults to localhost for dev)
MERCHANDISING_AGENT_URL=http://localhost:3001
STORE_OPS_AGENT_URL=http://localhost:3002
SUPPLY_CHAIN_AGENT_URL=http://localhost:3003
WORKFORCE_AGENT_URL=http://localhost:3004
CUSTOMER_ENGAGEMENT_AGENT_URL=http://localhost:3005
PRICING_ANALYTICS_AGENT_URL=http://localhost:3006

Implementation Phases

Phase	Weeks	Agents	MCP Servers	Milestone
1 — Foundation	1-6	Orchestrator, Merchandising	mcp-erp-pos, mcp-product-catalog, mcp-wms-oms	Single-domain E2E in Teams
2 — Expand	7-14	+ Store Ops, Customer Engagement, Supply Chain	+ mcp-crm-loyalty, mcp-m365-graph, mcp-workforce, mcp-commerce	5 agents, cross-domain queries
3 — Advanced	15-20	+ Pricing & Analytics, Workforce	+ mcp-market-intel, mcp-external-data	All 7 agents + 9 MCP servers
4 — Polish	21-26	Performance, security, monitoring	Caching, audit, DLP	Production launch

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.claude		.claude
agents		agents
docs		docs
infra		infra
install		install
mcp-servers		mcp-servers
packages		packages
plugins		plugins
tests		tests
.gitignore		.gitignore
AgentMatrix.md		AgentMatrix.md
README.md		README.md
package.json		package.json
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Copilot for Retail

Table of Contents

Architecture

Agents

1. Retail Copilot Orchestrator

2. Merchandising & Inventory Agent

3. Store Operations Agent

4. Customer Engagement Agent

5. Supply Chain Agent

6. Pricing & Analytics Agent

7. Workforce Management Agent

Agent Communication Matrix

Agent-to-Agent Communication

Cross-Domain Query Flow

Agent-to-MCP Server Communication

Communication Summary

MCP Servers & Data Sources

MCP Server Inventory

Tool Inventory by MCP Server

mcp-erp-pos (5 tools) — Implemented

mcp-product-catalog (5 tools) — Implemented

mcp-wms-oms (5 tools) — Implemented

mcp-crm-loyalty (5 tools) — Planned

mcp-m365-graph (5 tools) — Planned

mcp-workforce (5 tools) — Planned

mcp-commerce (5 tools) — Planned

mcp-market-intel (5 tools) — Planned

mcp-external-data (5 tools) — Planned

Authentication & Credentials

Authentication Matrix

Authentication Details

Dynamics 365 (OAuth 2.0 Client Credentials)

Microsoft Graph (OAuth 2.0 On-Behalf-Of)

External APIs (API Key)

Bot Framework

Credential Storage

Role-Based Access

Project Structure

Getting Started

Prerequisites

Setup

Environment Variables

Implementation Phases

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages