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

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:

{
  "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.