Skip to content

Instantly share code, notes, and snippets.

@jeremylongshore

jeremylongshore/0-guidewire-mcp-for-claude-one-pager-and-operator-audit.md

Last active May 7, 2026 02:31
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jeremylongshore/7f2718520f8a2a392866d99dfa4038bb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jeremylongshore/7f2718520f8a2a392866d99dfa4038bb to your computer and use it in GitHub Desktop.
Download ZIP
Raw
0-guidewire-mcp-for-claude-one-pager-and-operator-audit.md

Guidewire MCP for Claude

Carrier-native MCP server for the Guidewire InsuranceSuite. Ask Claude underwriter / claims / billing questions in operator vocabulary; the harness gates writes.

Status: v0.1.1 License: Apache 2.0 MCP Compatible Built with Claude

Links: GitHub · Live Architecture · v0.1.1 Release · Changelog

One-Pager

The Problem

Insurance carriers run on Guidewire InsuranceSuite (PolicyCenter, ClaimCenter, BillingCenter). Underwriters, claims adjusters, and billing operators spend hours navigating the UI to answer questions like "what submissions are waiting on me?" or "why did we lose this account?" The Cloud API exists but requires developer intervention — operators can't self-serve.

The Solution

A Claude Code plugin that exposes Guidewire as carrier-vocabulary MCP tools. Operators ask questions in their language (find-submissions-waiting-on-me), not API verbs (GET /job/v1/jobs). A governance harness gates all writes via plan → policy → approval → execute → audit → rollback. The hash-chained audit trail + carrier vocabulary are the durable moats.

W5 Table

Who What Where When Why
Underwriters, claims adjusters, billing operators Ask Claude natural-language carrier questions Claude Code / Claude Desktop Real-time during workflows Reduce context-switching, enable self-service
Carrier IT / DevOps Configure per-tenant profiles 9-YAML profile directory One-time setup Customize LOBs, typelists, field aliases per carrier
Compliance / Audit Review hash-chained audit trail Postgres audit store Post-hoc Immutable record of all AI-assisted operations

Stack Table

Layer Technology Purpose
Agent Host Claude Code, Claude Desktop, Anthropic API Natural language interface
MCP Servers servers/*-mcp/ (policycenter shipped; claim/billing planned) Tool catalog per InsuranceSuite module
Harness packages/harness/ Gates writes via plan/policy/approval/execute/audit/rollback
Foundation 7 packages (schemas, observability, auth, audit, client, mcp-runtime, harness) Shared infrastructure
External Guidewire Cloud API, Hub OAuth, Postgres, OTel, Sentry Carrier systems + observability

Key Differentiators

  1. Carrier vocabulary, not API verbs — Tool names are the question an operator would actually ask
  2. No mocks — Real Guidewire Cloud endpoints from day one
  3. Three execution modes — read_only, draft_only, approved_execute per tool via profile
  4. Hash-chained audit — Tamper-resistant via three Postgres roles (writer/reader/verifier)
  5. Per-tenant profiles — 9-YAML customization for LOBs, typelists, field aliases, approval matrix

Operator-Grade System Analysis

Executive Summary

Guidewire MCP for Claude v0.1.1 is a production-grade Claude Code plugin shipping:

  • 7 E1 foundation packages
  • 5 E2 read-only PolicyCenter tools
  • E3 harness skeleton with approval workflow
  • E4 profile loader scaffold

133 tests pass across 8 workspaces. Live architecture diagram at guidewire-mcp.intentsolutions.io.

v0.1.1 is a same-day install-path patch on top of v0.1.0 — fixes a silent-success failure mode in the prepare hook.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│ Agent Host (Claude Code / Claude Desktop / Anthropic API)   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│ MCP Servers (servers/*-mcp/)                                │
│  └── policycenter-mcp (5 read-only tools)                   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│ Harness (packages/harness/)                                 │
│  └── plan → policy → approval → execute → audit → rollback  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│ E1 Foundation Packages                                      │
│  schemas │ observability │ auth │ audit │ client │ runtime  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│ External Systems                                            │
│  Guidewire Cloud API │ Hub OAuth │ Postgres │ OTel │ Sentry │
└─────────────────────────────────────────────────────────────┘

Operational Commands

# Install via Claude Code
/plugin install jeremylongshore/guidewire-mcp-for-claude

# Or develop locally
pnpm install                      # prepare hook builds all
pnpm -r build                     # rebuild all 8 workspaces
pnpm -r test                      # 133 tests
pnpm lint                         # biome check
node servers/policycenter-mcp/dist/cli.js --profile profiles/oss-demo

v0.1.1 Tools (carrier-vocabulary, read-only)

Tool Purpose
find-submissions-waiting-on-me Assigned-to-me queue
show-policies-for-this-insured Cross-LOB policy lookup
summarize-this-submission Full submission narrative
did-we-lose-this-account Non-renewal / cancellation history
pull-this-submission Single submission detail

Quality Gates

Gate Status
Tests (133) ✓ Passing
Lint (Biome) ✓ Clean
Typecheck ✓ Passing
Build ✓ All 8 workspaces
CI ✓ 7 required checks
Branch protection ✓ Ruleset enforced

License

Apache-2.0

Author

Jeremy Longshore — Intent Solutions · intentsolutions.io · jeremylongshore.com

Changelog

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.1.1 — 2026-05-06 — install-path patch (prepare hook)

Same-day patch on top of v0.1.0. Fixes the silent-success failure mode in the plug-and-play install path surfaced during the v0.1.0 release smoke-test.

Fixed

  • prepare hook no longer swallows build failures via || true (#96). If pnpm -r build fails during pnpm install on an end-user's machine, the install now fails loudly with the underlying error instead of silently succeeding and leaving a non-functional dist/cli.js. The silent-success failure mode was the worst kind: plugin installs cleanly, MCP server fails to register, user has no error message to act on. Surfaced during v0.1.0 release smoke-test (clone fresh to /tmp, pnpm install, verify dist/cli.js produced — test passed with current dependencies, but the silent-failure mode was unacceptable to leave in place).

0.1.0 — 2026-05-06 — E1 foundation + E2 read-only tools + E3 harness skeleton

First software release. E1 foundation packages, E2 PolicyCenter MCP with 5 read-only tools, and E3 harness skeleton are built and tested. 133 tests pass across 8 workspaces. Live architecture diagram at guidewire-mcp.intentsolutions.io.

Added

E1 Foundation (7 packages):

  • @intentsolutions/guidewire-schemas — Zod schemas + TS contracts
  • @intentsolutions/guidewire-observability — OTel + pino + Sentry factory
  • @intentsolutions/guidewire-auth — Hub OAuth + JWT propagation
  • @intentsolutions/guidewire-audit — Postgres + hash-chain audit store
  • @intentsolutions/guidewire-client — undici Cloud API client with two-key idempotency
  • @intentsolutions/guidewire-mcp-runtime — MCP SDK wrapper (stdio + HTTP transports)
  • @intentsolutions/guidewire-harness — plan/policy/approval/execute/audit/rollback pipeline (#80)

E2 PolicyCenter MCP (5 read-only tools):

  • find-submissions-waiting-on-me — assigned-to-me queue
  • show-policies-for-this-insured — cross-LOB policy lookup
  • summarize-this-submission — full submission narrative
  • did-we-lose-this-account — non-renewal / cancellation history
  • pull-this-submission — single submission detail

E3 Harness skeleton:

  • Harness library + CLI skeleton — plan/policy/approval/execute/audit/rollback pipeline (#80)
  • Postgres-backed ApprovalSink for approval workflow (#92)
  • Boot-path error translator + CLI wiring (#93)
  • BAA carve enforcement at boot when lob_class:health (#87)
  • oauthScope + idempotency.pruned plumbed through audit chain (#85)
  • Approvals table + grants in 0001_init.sql (#86)

E4 Profile loader scaffold:

  • On-disk profile loader — --profile <path> boots policycenter-mcp against a real tenant (#75)
  • 9-YAML schema: auth, roles, lob, typelists, custom-entities, field-aliases, approval-matrix, pii-policy, events

Infrastructure + tooling:

  • Ship as Claude Code plugin — /plugin install jeremylongshore/guidewire-mcp-for-claude (#76)
  • Karate contract testing for Cloud API layer (D-022) (#79)
  • Testcontainers role-separation enforcement + pg-store TIMESTAMPTZ fix (#94)
  • Live architecture diagram at guidewire-mcp.intentsolutions.io (#53)
  • 5th project-level specialist: guidewire-reference-librarian (#23)
  • 11-auditor staffed panel — security, MCP safety, harness contract, etc. (#52)
  • README badges (CI, license, MCP-compatible, built-with-Claude) (#24)
  • Workflow phase guards — CI no-ops without package.json, release is workflow_dispatch only

Documentation:

  • 05-TECHNICAL-SPEC.md content (7.4k words) (#41)
  • 04-USER-JOURNEY.md content (5.4k words) (#42)
  • 01-BUSINESS-CASE.md content (3.0k words) (#39)
  • 07-ROADMAP with E2.5 aggregate-query sub-epic (#43)
  • Comprehensive CLAUDE.md rewrite reflecting current state (#77, #84)
  • Public Guidewire docs reference (librarian KB) with PartnerConnect sandbox + Swagger UI (#54)

Changed

  • Moved site from demo.intentsolutions.io to guidewire-mcp.intentsolutions.io (#53)
  • CI/release workflows customized to pnpm + Biome + Vitest + audit-harness gates
  • Main branch ruleset now enforced with 6 required status checks + 1 review (#90)

Fixed

  • CI workflow startup — dropped secrets ref from job-level if: condition (#88)
  • Lint baseline from 43 → 0 — Biome ignore for Karate JS, auto-fix harness package (#89)
  • Mobile-responsive architecture page — removed 1024px floor, added breakpoints (#71)
  • Diagram layout — clean lane layout, separate desktop + mobile views (#72)
  • Diagram mermaid syntax — frontmatter + escape primaryObject.id (#50, #55, #70)

Security

  • OWNER-bypass claim corrected — explicit bypass_actors required in ruleset (#91)
  • Audit DB role separation enforced via testcontainers — audit_writer cannot UPDATE/DELETE (#94)

v0.0.1 — 2026-05-04 — paperwork foundation

Auto-cut by the release.yml workflow on initial push to main. Marker for the paperwork-foundation milestone, NOT a software release. Subsequent releases will be manual via workflow_dispatch once code begins shipping in E1+.

Added

  • Repo scaffold + beads + Claude integration + git hooks
  • 14 GH issues mirroring 14 beads via bd-sync (12 epics + Phase 0 sub-beads + E11+ marketplace epic)
  • Phase 0 design inputs in 000-docs/: 001-DR-RES-research-report.md, 002-DR-CRIT-personas.md, 003-DR-ARCH-oss-cowork.md, 004-DR-DEC-architecture-decisions.md
  • 000-docs/blueprint/ — 12-section master blueprint scaffold (00 master index, 01-08 skeletons, 09 diagram placeholder, 10-AAR/ conventions, audits/ panel scaffold for 11 auditors)
  • .claude/agents/ — 4 dual-mode specialist agent definitions (mcp-safety-reviewer, carrier-vocabulary-curator, guidewire-api-archaeologist, harness-runtime-architect)
  • Standard governance set: LICENSE (Apache-2.0), CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, SUPPORT, .editorconfig, .gitattributes, GitHub issue/PR templates, CODEOWNERS, FUNDING, dependabot, default CI/release workflows
  • /validate-consistency post-GW-1.1 audit ran clean after fix PR #17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment