# jeremylongshore/guidewire-mcp-for-claude architecture

> Architecture diagram of the GitHub repository jeremylongshore/guidewire-mcp-for-claude, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeremylongshore/guidewire-mcp-for-claude
- Repository: https://github.com/jeremylongshore/guidewire-mcp-for-claude

## Overview

This is a carrier-vocabulary MCP server for Guidewire PolicyCenter, backed by shared auth, API-client, audit, schema, observability, and MCP-runtime packages. An underwriter asks Claude a question; the PolicyCenter tool queries Cloud API, maps raw fields to carrier vocabulary, and returns a result while emitting audit events. The README documents five read-only tools and planned drafting tools; the source index and excerpts expose only some tool internals, so unsampled tool details are represented at their exact paths without inferred call chains.

Main entry points: [`servers/policycenter-mcp/src/index.ts`](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/index.ts) (PolicyCenter MCP), [`packages/harness/src/harness.ts`](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/harness.ts) (Execution harness), [`servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts`](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts) (Lost account history), [`packages/client-sdk/src/client.ts`](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/client-sdk/src/client.ts) (Guidewire API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["PolicyCenter server"]
  node_server["PolicyCenter MCP<br/>[index.ts]"]
  node_manifest["Tool catalog<br/>[manifest.ts]"]
  node_waiting["Waiting submissions"]
  node_insured["Insured policies"]
  node_summary["Submission summary"]
  node_lost["Lost account history"]
  node_pull["Submission detail"]
  node_draftnote["Referral note draft"]
  node_draftendorsement["Endorsement draft"]
  node_referral["Referral explanation"]
  node_appetite["Risk appetite"]
  node_mapping["Field mapping<br/>[field-mapping.ts]"]
end

subgraph group_foundation["Shared runtime"]
  node_client["Guidewire API client<br/>[client.ts]"]
  node_auth["OAuth client<br/>[client.ts]"]
  node_mcp["MCP registry<br/>[server.ts]"]
  node_audit[("Audit stores<br/>[pg-store.ts]")]
  node_observability["Observability<br/>[factory.ts]"]
end

subgraph group_safety["Write governance"]
  node_harness["Execution harness<br/>[harness.ts]"]
  node_approvals[("Approval sinks<br/>[pg.ts]")]
  node_policy["Policy engine<br/>[in-memory.ts]"]
  node_evidence["Evidence export<br/>[exporter.ts]"]
end

subgraph group_profile["Tenant configuration"]
  node_profile["Profile loader<br/>[profile.ts]"]
  node_schemas["Profile schemas<br/>[baa-gate.ts]"]
end

node_underwriter(("Underwriter"))
node_claude["Claude MCP host"]
node_guidewire["Guidewire Cloud API"]
node_oauthservice["OAuth token service"]
node_postgres[("Postgres")]

node_underwriter -->|"asks"| node_claude
node_claude -->|"invokes tools"| node_server
node_server -->|"catalogs"| node_manifest
node_server -->|"registers"| node_waiting
node_server -->|"registers"| node_insured
node_server -->|"registers"| node_summary
node_server -->|"registers"| node_lost
node_server -->|"registers"| node_pull
node_server -->|"registers"| node_draftnote
node_server -->|"registers"| node_draftendorsement
node_server -->|"registers"| node_referral
node_server -->|"registers"| node_appetite
node_lost -->|"queries"| node_client
node_lost -->|"maps fields"| node_mapping
node_lost -->|"emits events"| node_audit
node_mapping -->|"uses aliases"| node_profile
node_client -->|"gets token"| node_auth
node_client -->|"sends requests"| node_guidewire
node_auth -->|"requests token"| node_oauthservice
node_server -.->|"uses registry"| node_mcp
node_profile -->|"validates profile"| node_schemas
node_harness -->|"appends events"| node_audit
node_harness -.->|"requests approval"| node_approvals
node_harness -.->|"evaluates policy"| node_policy
node_harness -.->|"builds evidence"| node_evidence
node_approvals -.->|"stores approvals"| node_postgres

click node_server "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/index.ts"
click node_manifest "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/manifest.ts"
click node_waiting "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/find-submissions-waiting-on-me.ts"
click node_insured "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/show-policies-for-this-insured.ts"
click node_summary "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/summarize-this-submission.ts"
click node_lost "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts"
click node_pull "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/pull-this-submission.ts"
click node_draftnote "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/draft-referral-note.ts"
click node_draftendorsement "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/draft-endorsement.ts"
click node_referral "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/explain-why-this-got-referred.ts"
click node_appetite "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/whats-our-appetite-on-this-risk.ts"
click node_mapping "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/field-mapping.ts"
click node_client "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/client-sdk/src/client.ts"
click node_auth "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/auth/src/client.ts"
click node_mcp "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/mcp-runtime/src/server.ts"
click node_audit "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/audit/src/pg-store.ts"
click node_observability "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/observability/src/factory.ts"
click node_harness "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/harness.ts"
click node_approvals "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/approvals/pg.ts"
click node_policy "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/policy/in-memory.ts"
click node_evidence "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/evidence/exporter.ts"
click node_profile "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/profile.ts"
click node_schemas "https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/schemas/src/profile/baa-gate.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_manifest,node_waiting,node_insured,node_summary,node_lost,node_pull,node_draftnote,node_draftendorsement,node_referral,node_appetite,node_mapping toneBlue
class node_client,node_auth,node_mcp,node_audit,node_observability,node_postgres toneAmber
class node_harness,node_approvals,node_policy,node_evidence,node_guidewire toneMint
class node_profile,node_schemas toneRose
class node_underwriter,node_claude,node_oauthservice toneIndigo
```

## Components

### PolicyCenter server

- [PolicyCenter MCP](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/index.ts): `servers/policycenter-mcp/src/index.ts`
- [Tool catalog](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/manifest.ts): `servers/policycenter-mcp/src/manifest.ts`
- [Waiting submissions](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/find-submissions-waiting-on-me.ts): `servers/policycenter-mcp/src/tools/find-submissions-waiting-on-me.ts`
- [Insured policies](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/show-policies-for-this-insured.ts): `servers/policycenter-mcp/src/tools/show-policies-for-this-insured.ts`
- [Submission summary](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/summarize-this-submission.ts): `servers/policycenter-mcp/src/tools/summarize-this-submission.ts`
- [Lost account history](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts): `servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts`
- [Submission detail](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/pull-this-submission.ts): `servers/policycenter-mcp/src/tools/pull-this-submission.ts`
- [Referral note draft](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/draft-referral-note.ts): `servers/policycenter-mcp/src/tools/draft-referral-note.ts`
- [Endorsement draft](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/draft-endorsement.ts): `servers/policycenter-mcp/src/tools/draft-endorsement.ts`
- [Referral explanation](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/explain-why-this-got-referred.ts): `servers/policycenter-mcp/src/tools/explain-why-this-got-referred.ts`
- [Risk appetite](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/tools/whats-our-appetite-on-this-risk.ts): `servers/policycenter-mcp/src/tools/whats-our-appetite-on-this-risk.ts`
- [Field mapping](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/field-mapping.ts): `servers/policycenter-mcp/src/field-mapping.ts`

### Shared runtime

- [Guidewire API client](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/client-sdk/src/client.ts): `packages/client-sdk/src/client.ts`
- [OAuth client](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/auth/src/client.ts): `packages/auth/src/client.ts`
- [MCP registry](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/mcp-runtime/src/server.ts): `packages/mcp-runtime/src/server.ts`
- [Audit stores](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/audit/src/pg-store.ts): `packages/audit/src/pg-store.ts`
- [Observability](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/observability/src/factory.ts): `packages/observability/src/factory.ts`

### Write governance

- [Execution harness](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/harness.ts): `packages/harness/src/harness.ts`
- [Approval sinks](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/approvals/pg.ts): `packages/harness/src/approvals/pg.ts`
- [Policy engine](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/policy/in-memory.ts): `packages/harness/src/policy/in-memory.ts`
- [Evidence export](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/harness/src/evidence/exporter.ts): `packages/harness/src/evidence/exporter.ts`

### Tenant configuration

- [Profile loader](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/servers/policycenter-mcp/src/profile.ts): `servers/policycenter-mcp/src/profile.ts`
- [Profile schemas](https://github.com/jeremylongshore/guidewire-mcp-for-claude/blob/main/packages/schemas/src/profile/baa-gate.ts): `packages/schemas/src/profile/baa-gate.ts`

### Other components

- **Underwriter**
- **Claude MCP host**
- **Guidewire Cloud API**
- **OAuth token service**
- **Postgres**

## Connections

- Underwriter → Claude MCP host: asks (evidence: `README.md`)
- Claude MCP host → PolicyCenter MCP: invokes tools (evidence: `README.md`)
- PolicyCenter MCP → Tool catalog: catalogs (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Waiting submissions: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Insured policies: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Submission summary: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Lost account history: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Submission detail: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Referral note draft: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Endorsement draft: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Referral explanation: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- PolicyCenter MCP → Risk appetite: registers (evidence: `servers/policycenter-mcp/src/index.ts`)
- Lost account history → Guidewire API client: queries (evidence: `servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts`)
- Lost account history → Field mapping: maps fields (evidence: `servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts`)
- Lost account history → Audit stores: emits events (evidence: `servers/policycenter-mcp/src/tools/did-we-lose-this-account.ts`)
- Field mapping → Profile loader: uses aliases (evidence: `servers/policycenter-mcp/src/field-mapping.ts`)
- Guidewire API client → OAuth client: gets token (evidence: `packages/client-sdk/src/client.ts`)
- Guidewire API client → Guidewire Cloud API: sends requests (evidence: `README.md`)
- OAuth client → OAuth token service: requests token (evidence: `packages/auth/src/client.ts`)
- PolicyCenter MCP → MCP registry: uses registry
- Profile loader → Profile schemas: validates profile (evidence: `servers/policycenter-mcp/src/profile.ts`)
- Execution harness → Audit stores: appends events (evidence: `packages/harness/src/harness.ts`)
- Execution harness → Approval sinks: requests approval
- Execution harness → Policy engine: evaluates policy
- Execution harness → Evidence export: builds evidence
- Approval sinks → Postgres: stores approvals
