# LexOS Compliance MCP Server

Pilot build for eCSI — the first real piece of the LexOS platform. Started as
the **Operations Engine** slice (compliance tracking + document chase) and
has grown to cover the first four LexOS milestones: go-live infrastructure,
a Google Calendar connector, client-facing status/chase, and an AI document
drafting engine. Milestone 5 (GEO/visibility) is a research deliverable, not
code — see `../lexos-ecsi-audit/` (or wherever that landed).

Scoped to match Item 4 ("New Business Operational Automation") in the signed
eCSI Delivery Plan Exhibit — a one-time build, delivered within 60 days of
scope sign-off. M3 and M4 below are product-shaped work that belongs in the
separate License, Referral & Advisory Agreement conversation once M1/M2 have
proven out — see the milestone plan for why.

## What's built — 16 MCP tools across 4 milestones

Backed by local SQLite (Node's built-in `node:sqlite` — no native compile
step, `npm install` just works, no Xcode CLT dependency).

**Core tracking (the original pilot):**

| Tool | Does |
|---|---|
| `add_client` | Register a client entity |
| `add_deadline` | Add a compliance deadline (SEC_GIS, BIR_FILING, PEZA_RENEWAL, SSS, PHILHEALTH, HDMF, CORPORATE_HOUSEKEEPING, OTHER) |
| `list_upcoming_deadlines` | What's due within N days, across the book or one client |
| `mark_deadline_done` | Close out a completed deadline |
| `request_document` | Log a document request to a client (the chase queue) |
| `mark_document_received` | Clear a document off the chase queue |
| `list_outstanding_documents` | What's still outstanding, across the book or one client |
| `client_status_summary` | Full picture for one client in a single call |

**M1 — Go-live infrastructure:**

| Tool | Does |
|---|---|
| `import_clients_csv` | Bulk-register clients from CSV (name,entity_type,contact_whatsapp,contact_email) — onboard eCSI's real book in one call |
| `generate_digest` | Formats upcoming deadlines + outstanding documents as readable text. Returns text only — sending it anywhere is a separate step |

**M2 — MCP Connector Fabric (Google Calendar):**

| Tool | Does |
|---|---|
| `sync_deadline_to_gcal` | Push one deadline to Google Calendar (idempotent — updates, doesn't duplicate) |
| `sync_all_deadlines_to_gcal` | Push all upcoming deadlines within N days in one call |

Sync logic is fully unit-tested against `FakeCalendarClient` (`npm run
smoke:gcal`) — the algorithm is proven correct independent of real Google
credentials. **What's still needed to go live:** a real Google Cloud OAuth
client (`GCAL_CLIENT_ID`, `GCAL_CLIENT_SECRET`, `GCAL_REFRESH_TOKEN`) — a
Google Cloud Console step (new project, OAuth consent screen), not a code
problem. Without it, both tools fail with a clear, actionable error instead
of doing something wrong silently.

**M3 — Client-facing status + document-chase policy:**

| Tool | Does |
|---|---|
| `check_client_status` | Look up a client by name/id, return a client-facing status message — backend for a WhatsApp "STATUS" command |
| `get_chase_policy_actions` | Applies the escalation policy (nudge after 3 days outstanding, escalate after 7 — tune in `src/chase.ts`) and returns drafted messages for review |

**Neither tool sends anything.** They produce text for a human to review,
or to wire into a channel once eCSI has explicitly signed off on message
tone and the auto-send policy. That boundary is deliberate — these messages
go out under eCSI's brand to their real clients.

**M4 — AI document drafting:**

| Tool | Does |
|---|---|
| `list_templates` | Lists the 4 starter templates and what fields each requires |
| `draft_document` | Merges client data + supplied fields into a template, returns a draft |

Four starter templates (`src/templates/registry.ts`): Secretary's
Certificate, Board Resolution, GIS Transmittal Note, Special Power of
Attorney — standard PH corporate-document conventions, **not** eCSI's actual
house templates (those need to be collected from their team before this
goes live for real). Every draft is explicitly marked
`"DRAFT — requires human legal review before use"`. Missing required fields
throw a clear error rather than silently producing a document with blanks.
No case-law or statute reasoning anywhere in this tool — deliberately out
of the legal-research lane that Anycase.ai/Digest.ph already occupy.

## Running it

```bash
npm install
npm run smoke:all   # all 3 smoke suites (core, gcal, drafting) — 29 assertions
npm run build        # compiles to dist/
npm run dev           # runs the server on stdio via tsx (no build step needed)
```

Point Claude Desktop / Claude Code at the built server:

```json
{
  "mcpServers": {
    "lexos-compliance": {
      "command": "node",
      "args": ["/Users/tonymac/code/lexos-compliance-mcp/dist/index.js"]
    }
  }
}
```

For the Google Calendar connector, also set `GCAL_CLIENT_ID`,
`GCAL_CLIENT_SECRET`, `GCAL_REFRESH_TOKEN` in `env`.

Data lives in `./data/lexos.db` (gitignored). Override with `LEXOS_DB_PATH`.

## Verified working

- `npm run smoke` — 11/11 assertions against the core tracking tools.
- `npm run smoke:gcal` — 9/9 assertions against the calendar sync algorithm
  via `FakeCalendarClient` (create-then-update idempotency, window filtering)
  — no real Google credentials involved.
- `npm run smoke:drafting` — 9/9 assertions against the drafting engine
  (successful merge, missing-field rejection, unknown-template rejection).
- A real MCP client (`@modelcontextprotocol/sdk`'s `Client` +
  `StdioClientTransport`) was run against the built server covering all 16
  tools: `tools/list` returns everything, and a full round-trip — bulk
  import → deadline → digest → status check → chase policy → template
  listing → document draft — works over the actual stdio protocol. The
  Google Calendar tool was confirmed to fail with the clear configuration
  error (not a crash) when credentials aren't set, which is the correct
  behavior right now.

## Known issue, deliberately not fixed yet

`npm audit` flags a moderate-severity transitive vulnerability (a `uuid`
buffer-bounds issue) via `googleapis`'s dependency chain. Not exploitable in
how this code calls it, and a clean fix means a breaking `googleapis`
major-version bump. Since the connector isn't live yet anyway (blocked on
real OAuth credentials), fix this before wiring up real credentials, not
before.

## What's genuinely blocked on external input, not on more building

- **eCSI's real client data.** Nothing here is seeded with anything but
  test/demo data. Real onboarding needs their actual roster.
- **Which calendar/CRM they actually run.** M2 was built against Google
  Calendar as the most likely target for a small PH firm — that's an
  informed bet, not a confirmed fact. If it's something else, the
  `CalendarClient` interface in `src/calendar-client.ts` is designed to be
  swapped without touching the sync algorithm.
- **eCSI's actual document templates.** M4 ships with generic PH-standard
  placeholders. Swapping in their real house templates is a content
  collection step with their team.
- **Real Google OAuth credentials** for M2, and **WhatsApp Business API
  access** for M3's channel — both need eCSI (or Tony) to set up accounts
  this code can't create on its own.
- **Sign-off on message tone and auto-send policy** for M3 — these messages
  represent eCSI to their own clients; that's their call, not a default I
  should ship silently.

## Milestone 5 — GEO/visibility

Not code. See the audit deliverable produced alongside this build for a
real assessment of eCSI's current online visibility and concrete
recommendations — that's research/content work, not an MCP tool.