# agentic-msteams-mcp

A self-hosted Microsoft Teams MCP server that serves as an agnostic human-in-the-loop gateway for AI agents.

## Overview

This project implements a dual-surface architecture to allow AI agents to interact with humans via Microsoft Teams without requiring the agent to have direct Graph API access or complex bot logic.

### v0.4.0 Feature: Human-in-the-Loop & Approvals
v0.4.0 provides a comprehensive suite of tools for agents to interact with humans via Microsoft Teams, including notifications, asynchronous questions, and formal approval workflows.

- **`msteams_send_notification`**: Sends one-way alerts.
- **`msteams_ask_user`**: Poses structured questions; returns `request_id`.
- **`msteams_get_user_reply`**: Tracks responses to asks.
- **`msteams_request_approval`**: Requests a formal binary decision (Approve/Reject).
- **`msteams_get_approval`**: Checks the state of an approval request.

## Core Architecture

### 1. The MCP Surface (Stdio)
The primary interface for AI agents. It exposes a strictly limited toolset of six tools:
- `msteams_health_check`: Verifies server connectivity.
- `msteams_send_notification`: Sends one-way alerts to allowlisted users/channels.
- `msteams_ask_user`: Requests information from an allowlisted user.
- `msteams_get_user_reply`: Checks the state of a requested reply.
- `msteams_request_approval`: Initiates a formal approval request.
- `msteams_get_approval`: Retrieves the decision for an approval request.

### 2. The Teams Surface (HTTP)
A lightweight FastAPI app that acts as the webhook receiver for Microsoft Teams. It is designed to be hosted behind a proxy/gateway.

## Security Model (Secure-by-Design)

### Closed-World Toolset
The server explicitly denies any arbitrary Graph API operations. All interactions are gated through specific, high-level tools.

### Fail-Closed Allowlist
Notifications and Asks are only delivered to IDs defined in the `MSTEAMS_ALLOWED_USER_IDS` or `MSTEAMS_ALLOWED_CHANNEL_IDS` environment variables. If an ID is not listed, the request is rejected immediately.

### Audit Logging
Every attempt to notify or ask a user is logged to a local audit file (`MSTEAMS_AUDIT_LOG_PATH`). 
- **Privacy**: Log entries contain metadata and fingerprints but NEVER include the actual message or question body.
- **Stability**: Uses SHA-256 deterministic fingerprinting for audit evidence.

### Dry-Run Mode
By default, `MSTEAMS_NOTIFICATION_DRY_RUN=True`. In this mode, the server validates all requests and logs them to audit but does not actually call the Microsoft Graph API. NOTE: Real Teams/Graph delivery is currently not implemented; dry-run is the intended safe default for current versions.

## Installation & Configuration

### Environment Variables
| Variable | Default | Description |
| --- | --- | --- |
| `SERVER_HOST` | `127.0.0.1` | Bind address for the HTTP surface. |
| `SERVER_PORT` | `8000` | Port for the HTTP surface. |
| `MSTEAMS_ALLOWED_USER_IDS` | `""` | Comma-separated list of allowlisted User IDs (Required). |
| `MSTEAMS_ALLOWED_CHANNEL_IDS` | `""` | Comma-separated list of allowlisted Channel IDs. |
| `MSTEAMS_NOTIFICATION_DRY_RUN` | `True` | If true, no real Graph API calls are made. |
| `MSTEAMS_AUDIT_LOG_PATH` | `data/audit.log` | Path to the append-only audit log file. |

### Running the Server
The server provides two distinct modes:

**1. MCP Stdio Mode (for AI Agents)**
```bash
python -m agentic_msteams_mcp.main --mcp
```

**2. HTTP Surface Mode (for Teams Webhooks)**
```bash
python -m agentic_msteams_mcp.main --http
```

## Deployment

The server is provided as a Docker image for consistent runtime environments.
```bash
docker build -t agentic-msteams-mcp .
docker run -p 8000:8000 -e MSTEAMS_ALLOWED_USER_IDS="user1,user2" agentic-msteams-mcp --http
```