# HelpingAgent

A learning project demonstrating how to connect a **Microsoft 365 Declarative Agent** to a **remote Model Context Protocol (MCP) server** secured with **Microsoft Entra ID OAuth authentication**.

---

## Overview

**HelpingAgent** is a Microsoft 365 Copilot Declarative Agent that helps users manage car repair records. Instead of calling a traditional REST API directly, the agent communicates with a **remote MCP server** over **Streamable HTTP**. Every tool invocation is protected using **OAuth 2.0** with **Microsoft Entra ID**, ensuring that only authenticated users can access repair data.

The project uses **Azure Table Storage** (emulated locally using **Azurite**) as the backend datastore and demonstrates an end-to-end implementation of:

- Microsoft 365 Declarative Agents
- Model Context Protocol (MCP)
- OAuth authentication with Microsoft Entra ID
- Azure Table Storage
- Microsoft 365 Agents Toolkit

---

## Features

### Declarative Agent

- List repair records
- View repair details
- Create new repairs
- Update existing repairs
- Filter repairs by assigned technician

### Remote MCP Server

- Built using **FastMCP**
- Uses **Streamable HTTP** transport
- Exposes repair operations as MCP tools
- Communicates securely with Microsoft 365 Copilot

### OAuth Authentication

- Microsoft Entra ID issued Bearer (JWT) tokens
- JWKS-based signature verification
- Validation of:
  - Issuer
  - Audience
  - Required scopes

### Data Storage

- Azure Table Storage
- Local development using Azurite

---

## Architecture

```text
                Microsoft 365 Copilot
              (Declarative Agent)

                       │
                       │
      OAuth Protected MCP Tool Calls
         (Bearer JWT Access Token)
                       │
                       ▼

          MCP Server (FastMCP)
        Streamable HTTP Transport
        src/mcp_server.py

      • JWT Signature Validation
      • Issuer Validation
      • Audience Validation
      • Scope Validation

                       │
                       ▼

          Azure Table Storage
           Repairs Table
      (Azurite for Local Development)
```

---

## Repository Structure

| Path | Description |
|------|-------------|
| `src/mcp_server.py` | MCP server implementation containing repair tools and OAuth token validation. |
| `src/init_data.py` | Seeds Azure Table Storage with sample repair records. |
| `src/repairsData.json` | Sample repair data used during initialization. |
| `appPackage/repairDeclarativeAgent.json` | Declarative Agent definition. |
| `appPackage/ai-plugin.json` | Plugin configuration connecting the agent to the remote MCP server. |
| `appPackage/instruction.txt` | System instructions for the Declarative Agent. |
| `appPackage/adaptiveCards/` | Adaptive Card templates used to display repair information. |
| `appPackage/manifest.json` | Microsoft Teams/Microsoft 365 app manifest. |
| `infra/azure.bicep` | Azure infrastructure definition. |
| `m365agents.yml` | Microsoft 365 Agents Toolkit provisioning and deployment pipeline. |
| `m365agents.local.yml` | Local development pipeline. |
| `env/` | Environment configuration files. |
| `mcp-auth-todo.txt` | OAuth implementation checklist. |
| `docs/HelpingAgent-Learning-Guide.pdf` | Project learning guide. |

---

## OAuth Authentication Flow

The MCP server is secured using **Microsoft Entra ID OAuth**.

1. A Microsoft Entra ID application exposes the custom scope:

   ```text
   access_as_user
   ```

2. The MCP server is configured with:

   - `OAUTH_ACCEPTED_ISSUERS`
   - `OAUTH_ACCEPTED_AUDIENCES`
   - `OAUTH_REQUIRED_SCOPES`
   - `OAUTH_JWKS_URI`

3. For every MCP tool call:

   - Extract the Bearer token
   - Verify the JWT signature using Microsoft's JWKS
   - Validate the issuer
   - Validate the audience
   - Validate the required scope
   - Reject unauthorized requests

4. The plugin (`ai-plugin.json`) uses:

   ```json
   "auth": {
     "type": "OAuthPluginVault"
   }
   ```

   Microsoft 365 Copilot handles user authentication, consent, token acquisition, and automatically includes the Bearer token with every MCP request.

5. During provisioning, the Microsoft 365 Agents Toolkit registers the OAuth configuration using the `oauth/register` step and stores the generated reference ID in the environment configuration for use by the plugin.

---

## Prerequisites

- Python 3.13
- Node.js
- Microsoft 365 Agents Toolkit
- Microsoft 365 Copilot enabled tenant
- Microsoft Entra ID App Registration
- Azure Table Storage (Azurite for local development)

---

## Local Development

### Install dependencies

```bash
pip install -r requirements.txt
npm install
```

### Start Azurite

```bash
npm run start:azurite
```

### Seed sample data

```bash
npm run init-data
```

### Start the MCP Server

```bash
npm run start:mcp-http
```

The MCP server runs at:

```text
http://127.0.0.1:3001
```

### Inspect available MCP tools

```bash
npm run inspector
```

### Run the legacy HTTP Azure Function (optional)

```bash
npm run dev
```

### Run the complete solution

Press **F5** in Visual Studio Code using the Microsoft 365 Agents Toolkit.

The toolkit will:

- Provision the application
- Start the MCP server
- Create a Development Tunnel
- Configure OAuth
- Sideload the Declarative Agent into Microsoft 365 Copilot

---

## Environment Configuration

Environment variables are organized by deployment stage.

```text
env/
├── .env.local
├── .env.local.user
├── .env.dev
└── .env.dev.user
```

- `.env.*` files contain non-secret configuration.
- `.env.*.user` files contain secrets and are excluded from source control.

### Important Variables

| Variable | Description |
|----------|-------------|
| `AZURE_STORAGE_CONNECTION_STRING` | Azure Table Storage connection string. |
| `OAUTH_ACCEPTED_ISSUERS` | Accepted Microsoft Entra ID issuer(s). |
| `OAUTH_ACCEPTED_AUDIENCES` | Accepted App ID URI(s). |
| `OAUTH_REQUIRED_SCOPES` | Required OAuth scope(s). |
| `OAUTH_JWKS_URI` | Microsoft Entra ID JWKS endpoint. |
| `MCP_SERVER_URL` | Public MCP server URL. |

---

## Technologies Used

- Microsoft 365 Copilot
- Microsoft 365 Declarative Agents
- Model Context Protocol (MCP)
- FastMCP
- Streamable HTTP
- Microsoft Entra ID
- OAuth 2.0
- JSON Web Tokens (JWT)
- JSON Web Key Sets (JWKS)
- Azure Table Storage
- Azurite
- Microsoft 365 Agents Toolkit
- Python 3.13

---

## Project Status

- ✅ Microsoft 365 Declarative Agent implemented
- ✅ Remote MCP Server implemented
- ✅ Azure Table Storage integration completed
- ✅ OAuth authentication with Microsoft Entra ID implemented
- ✅ JWT validation using JWKS implemented
- ✅ Streamable HTTP transport configured
- ✅ End-to-end communication between Microsoft 365 Copilot and the MCP server verified

---

## Learning Objectives

This project was built as a hands-on learning exercise to understand:

- Building Microsoft 365 Declarative Agents
- Developing MCP servers using FastMCP
- Exposing functionality as MCP tools
- Securing MCP servers with Microsoft Entra ID OAuth
- Validating JWT access tokens using JWKS
- Connecting Microsoft 365 Copilot to remote MCP servers
- Using Azure Table Storage as the backend datastore
- Provisioning and deploying applications with the Microsoft 365 Agents Toolkit

---