# ServiceNow Cowork Automation API

FastAPI + MCP-compatible backend for Microsoft 365 Copilot Cowork ServiceNow incident automation.

## What this backend does

- Receives ServiceNow new-incident webhooks.
- Deduplicates automation jobs.
- Queues jobs to Azure Service Bus when enabled.
- Exposes controlled `/api/cowork/*` APIs for Cowork plugin/MCP use.
- Exposes a remote MCP-compatible `/mcp` JSON-RPC endpoint.
- Applies backend policy checks before ServiceNow or Microsoft Graph actions.
- Searches/classifies ServiceNow KB articles.
- Performs eligible Microsoft Entra ID password reset/profile update through Graph.
- Writes job, policy, KB, and audit records.
- Never returns or logs temporary passwords.

## Local setup

```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
copy .env.example .env
uvicorn app.main:app --reload
```

## Test

```powershell
pytest -q
pytest --cov=app
```

## Required environment variables

See `.env.example`.

For local/dev, keep:

```env
SERVICE_BUS_ENABLED=false
GRAPH_ENABLED=false
DATABASE_URL=sqlite+aiosqlite:///./cowork.db
```

For Azure, set `DATABASE_URL`, ServiceNow credentials, Graph settings, and Service Bus settings in App Service/Function App configuration or Key Vault references.

## REST examples

Health:

```bash
curl http://localhost:8000/health
```

Webhook:

```bash
curl -X POST http://localhost:8000/api/servicenow/webhook/incidents ^
  -H "Content-Type: application/json" ^
  -H "x-api-key: local-test-key" ^
  -d "{\"sys_id\":\"inc-1\",\"number\":\"INC0010001\",\"state\":\"New\",\"category\":\"access\",\"priority\":\"3\",\"short_description\":\"forgot password\"}"
```

Analyze:

```bash
curl -X POST http://localhost:8000/api/cowork/incidents/analyze ^
  -H "Content-Type: application/json" ^
  -H "x-api-key: local-test-key" ^
  -d "{\"incident_sys_id\":\"inc-1\",\"authenticated_user_upn\":\"user@contoso.com\"}"
```

MCP initialize:

```bash
curl -X POST http://localhost:8000/mcp ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}"
```

List MCP tools:

```bash
curl -X POST http://localhost:8000/mcp ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"
```

## Safety model

Cowork should mainly call:

- `analyze_incident`
- `run_incident_automation`
- `get_automation_job_status`

The backend remains the final trust boundary for identity, policy, VIP/admin/security exclusions, KB safety classification, and Graph actions.