Copilot-M365-Insights: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Governance and telemetry reporting for Microsoft Copilot Studio agents across an M365 tenant. Pulls data from ~12 Azure/M365 APIs plus manual CSV exports, stores everything in a local SQLite database, and outputs a multi-sheet Excel workbook. Also exposes an MCP server (stdio locally, HTTP on Azure Container Apps) so AI agents can query the telemetry conversationally, and a Bot Framework conversational agent (src/agent/) that consumes that MCP server.

Commands

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Fetch all sources + export workbook
python -m src.main all

# Fetch only (no export)
python -m src.main sync

# Export last sync to Excel (no new fetch)
python -m src.main export

# Import Copilot Studio analytics CSVs from a Viva export folder
python -m src.main import-viva <path/to/csv/folder>

# Multi-tenant: point at a different .env (must be the first two args)
python -m src.main --env .env.stryker all

# Deploy MCP server to Azure Container Apps
bash deploy.sh deploy-config/<tenant>.env

# One-time tenant provisioning (run in order)
bash provision/step1_insights.sh   # Log Analytics + App Insights
bash provision/step2_identity.sh   # sync SP permissions + admin consent
bash provision/step3_mcp.sh        # register MCP server app in Entra ID

There is no test suite, linter, or type-checker configured in this repo (no tests/, pyproject.toml, or pytest.ini) — don't assume pytest or ruff commands work.

Architecture

Pipeline shape: fetchers/ (one module per data source) → store/sqlite_store.py (upsert into SQLite, keyed by a stable run_id) → writers/ (one module per Excel sheet, reads back from the store) → workbook_writer.py assembles the final .xlsx. src/main.py orchestrates sync (fetch+store) and export (store+write) as separate phases — all just runs both.