# MCP Ops Brief Agent

A read-only, MCP-style Ops Brief Agent for agencies and IT service companies managing multiple clients. It combines delivery status, financial performance, and recent client communication into a deterministic, ranked operational brief.

This repository is a portfolio/demo implementation, not a production deployment. It does not claim measured performance, accuracy, cost savings, or time savings.

## Data sources

- **ClickUp** supplies the schedule hierarchy: Client (Folder) → Project (List) → Milestone (Task).
- **QuickBooks Online sandbox** supplies project or milestone budgets and actual costs.
- **Gmail** uses read-only access to find the latest agency-sent client update associated with each canonical milestone ID.

Canonical milestone IDs, such as `MS-2026-101-01`, provide deterministic joins across systems. Project IDs are derived using the repository's canonical ID scheme. Fuzzy matching is prohibited.

## Architecture

![MCP Ops Brief Agent Architecture](docs/mcp-ops-brief-architecture.svg)

ClickUp, QuickBooks Online, and Gmail provide read-only evidence, deterministic code performs canonical merging and risk scoring, and Claude only converts already-scored JSON into a readable prioritized Ops Brief.

```text
ClickUp ─────┐
QuickBooks ──┼→ adapters → normalized records → deterministic scoring → ranked ClientScore[]
Gmail ───────┘
                                                              ↓
                                                   Claude readable brief
                                                              ↓
                                          deterministic output validation
                                                              ↓
                                                        Ops Brief
```

Connector data is normalized and scored deterministically before Claude is called. Claude Sonnet is only the readable reporting layer: it does not calculate or change risk scores or risk flags. Its structured response is locally validated against the deterministic `ClientScore[]` before it is accepted.

The current deterministic engine supports the risk and data-quality decisions implemented in the code, including:

- schedule risk based on expected versus phase-derived completion;
- overdue milestones based on due dates;
- communication risk based on the age of the latest agency-sent update;
- budget risk based on spend relative to budget and completion progress;
- supported data-gap flags, including missing budgets and low-volume data.

## Verified demo hierarchy

Client: **Acme Corp**

Projects:

- Website Redesign
- SEO Retainer

Milestones:

- Design Phase
- Development Phase
- Monthly Optimization

The demo records verify both milestone-based and project-wide costing modes. Demo names and values are fixture/sandbox data, not claims about a real business.

## Safety boundaries

The current system is read-only:

- no autonomous client communication or Gmail sending;
- no QuickBooks write actions;
- no ClickUp write actions;
- Gmail access is limited to the `gmail.readonly` scope;
- Claude cannot override deterministic scoring or flags;
- malformed, incomplete, reordered, or contradictory Claude output is rejected locally.

OAuth refresh may update local token files under `credentials/`, but it does not modify accounting, email, or project-management records.

## Deterministic joins and costing

The only cross-system association is an exact canonical identifier:

- ClickUp tasks carry a canonical milestone ID.
- Gmail message subjects are matched against exact bracketed milestone IDs.
- QuickBooks Customer Notes contain an exact `MilestoneID: ...` or `ProjectID: ...` value.

Milestone notes select milestone-based costing; project notes select project-wide costing. No client name, project name, email address, or approximate text match is used as a cross-system join.

## Development

```powershell
npm.cmd install
npm.cmd run typecheck
npm.cmd run build
npm.cmd test
```

`npm.cmd run run:live` executes the live read-only connector pipeline and calls Claude to format the already-ranked result. It requires locally configured credentials and should not be used as an offline test command.

## Local credentials

Credential and token files belong under `credentials/`, which is ignored by Git. Environment files, dependencies, and generated build output are also ignored. Never commit API keys, OAuth client secrets, access tokens, refresh tokens, authorization headers, or personal email addresses.