pedigree-mcp by zzgael - MCP Server

Pedigree MCP Server

An MCP (Model Context Protocol) server for generating family pedigree tree diagrams as PNG images using standard genetic notation per Bennett 2008/2022 NSGC guidelines.

BRCA1 hereditary breast/ovarian cancer family history demonstrating: 3 generations, affected individuals with combined conditions, MZ identical twins, carrier status, deceased indicators, proband + consultand markers, and gene test results (BRCA1+/BRCA1-)

Installation

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "pedigree": {
      "command": "npx",
      "args": ["pedigree-mcp"],
      "env": {}
    }
  }
}

Build from Source

If you prefer to build from source:

git clone https://github.com/zzgael/pedigree-mcp.git
cd pedigree-mcp
npm install
npm run build

Then use in your MCP client configuration:

{
  "mcpServers": {
    "pedigree": {
      "command": "node",
      "args": ["/absolute/path/to/pedigree-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Features

Bennett 2008 Standard Compliance

This implementation follows the NSGC Standardized Human Pedigree Nomenclature:

Symbol	Description	Property
Square	Male	`sex: "M"`
Circle	Female	`sex: "F"`
Diamond	Unknown sex	`sex: "U"`
Filled shape	Affected individual	`conditions: [...]`
Diagonal line	Deceased	`status: 1`
Arrow (lower-left)	Proband	`proband: true`
Double arrow (lower-left)	Consultand (person seeking counseling)	`consultand: true`
Brackets [ ]	Adopted	`noparents: true`
Double line	Consanguinity	Auto-detected from shared ancestors
Text on double line	Consanguinity degree	`consanguinity_degree: "1st cousins"`
Horizontal bar	MZ (identical) twins	`mztwin: "group_id"`
Diagonal lines	DZ (fraternal) twins	`dztwin: "group_id"`
Dot in center	Carrier status	`carrier: true`
Outlined dot	Obligate carrier (inferred)	`obligate_carrier: true`
"P" inside symbol	Pregnancy	`pregnant: true`
"P" + weeks label	Pregnancy duration	`pregnant: true, terminated_age: 12`
Small triangle	Early pregnancy loss (<20 weeks)	`terminated: true, terminated_age: 8`
Large triangle	Stillbirth (≥20 weeks)	`terminated: true, terminated_age: 24`
"EP" below symbol	Ectopic pregnancy	`ectopic: true`
Crossed lines (X)	Infertility	`infertility: true`
Hash marks on line	Divorced/separated	`divorced: true`
Line through offspring	No children by choice	`no_children_by_choice: true`
"A" in upper right	Ashkenazi ancestry	`ashkenazi: 1`
"*" in upper left	Genetic anticipation	`anticipation: true`
"d. XXy" label	Age at death (auto-calculated)	`yob: 1950, yod: 2020, status: 1`
Arrow + "OUT" label	Adopted OUT (placed for adoption)	`adoption_type: "out"`
Dashed brackets	Foster placement (temporary)	`adoption_type: "foster"`
Roman numerals I, II, III	Birth order in sibling group	`birth_order: 1` (displays as "I")
"E" marker (blue)	ART - Egg donor conception	`art_type: "egg_donor"`
"S" marker (blue)	ART - Sperm donor conception	`art_type: "sperm_donor"`
"Em" marker (blue)	ART - Embryo donor conception	`art_type: "embryo_donor"`
"GC" marker (blue)	ART - Gestational carrier (surrogate)	`art_type: "surrogate"`
"SAB" label	Pregnancy outcome - Spontaneous abortion	`pregnancy_outcome: "miscarriage"`
"TOP" label	Pregnancy outcome - Termination of pregnancy	`pregnancy_outcome: "induced_termination"`
"SB" label	Pregnancy outcome - Stillbirth	`pregnancy_outcome: "stillbirth"`
"Het" label (green)	Gene copy number - Heterozygous	`gene_copy_number: "heterozygous"`
"Hom" label (green)	Gene copy number - Homozygous	`gene_copy_number: "homozygous"`
"CH" label (green)	Gene copy number - Compound heterozygous	`gene_copy_number: "compound_heterozygous"`
Dashed partnership line	Unmarried/common-law partnership	`relationship_type: "unmarried"`

Conditions (Bennett Standard - FREE TEXT)

Per Bennett 2008 standard, conditions are documented using free text. Simply provide a conditions array with any disease/condition name:

{
  "conditions": [
    { "name": "Breast cancer", "age": 42 },
    { "name": "Ovarian cancer", "age": 55 }
  ]
}

Examples:

{ "name": "Huntington's disease", "age": 45 }
{ "name": "Type 2 diabetes" } (no age = affected status only)
{ "name": "Cystic fibrosis" }
{ "name": "Hereditary hemochromatosis", "age": 38 }

Colors are auto-assigned from a palette based on unique condition names. Multiple conditions show as quadrants (male) or pie slices (female).

Genetic Testing Results

Supports any gene - use pattern {gene}_gene_test:

{
  "brca1_gene_test": { "type": "T", "result": "P" },
  "htt_gene_test": { "type": "T", "result": "P" },
  "apoe_gene_test": { "type": "S", "result": "N" }
}

Gene test result codes:

type: T (tested), S (screening), - (unknown)
result: P (positive), N (negative), - (unknown/VUS)

Labels appear as: BRCA1+ (positive), HTT- (negative)

Tools

`get_pedigree_documentation`

Returns comprehensive documentation about the pedigree data format. Always call this first before generating a pedigree.

`generate_pedigree`

Generates a family pedigree tree in PNG or SVG format.

Parameters:

Parameter	Type	Default	Description
`dataset`	`Individual[]`	required	Array of family members
`width`	`number`	800	Image width in pixels
`height`	`number`	600	Image height in pixels
`symbol_size`	`number`	35	Node diameter in pixels
`background`	`string`	#ffffff	Background color
`labels`	`string[]`	['age']	Attributes to display
`format`	`'png' \| 'svg'`	'png'	Output format: png (base64 image) or svg (XML text)

Data Format

Individual Object

interface Individual {
  // Required
  name: string;           // Unique ID (max 7 chars)
  sex: "M" | "F" | "U";   // Male, Female, Unknown

  // Identity
  display_name?: string;  // Human-readable name for display (max 13 chars)
  top_level?: boolean;    // Founding individual (no parents)
  proband?: boolean;      // Index case

  // Relationships
  mother?: string;        // Mother's name (must exist in dataset)
  father?: string;        // Father's name (must exist in dataset)

  // Demographics
  age?: number;           // Current age
  yob?: number;           // Year of birth
  status?: number;        // 0 = alive, 1 = deceased

  // Twins (Bennett standard)
  mztwin?: string;        // MZ twin group ID (identical)
  dztwin?: string;        // DZ twin group ID (fraternal)

  // Special indicators (Bennett standard)
  carrier?: boolean;      // Carrier status (dot in center)
  pregnant?: boolean;     // Current pregnancy (P inside symbol)
  terminated?: boolean;   // Stillbirth/SAB (small triangle)
  divorced?: boolean;     // Divorced from partner (hash marks)
  noparents?: boolean;    // Adopted (brackets around symbol)

  // Conditions (Bennett standard - FREE TEXT)
  conditions?: Array<{
    name: string;         // Any condition: "Breast cancer", "Huntington's disease", etc.
    age?: number;         // Age at diagnosis/onset
  }>;

  // Genetic tests (pattern: {gene}_gene_test)
  brca1_gene_test?: { type: "-"|"S"|"T", result: "-"|"P"|"N" };
  brca2_gene_test?: { type: "-"|"S"|"T", result: "-"|"P"|"N" };
  // ... any gene test
}

Examples

📸

See the full gallery of standardized pedigree scenarios demonstrating Bennett 2008/2022 compliance, including gender diversity, twins, consanguinity, ART indicators, and complex multi-generation families.

Basic Three-Generation Pedigree

[
  {"name": "MGF", "sex": "M", "top_level": true},
  {"name": "MGM", "sex": "F", "top_level": true, "conditions": [{"name": "Breast cancer", "age": 55}]},
  {"name": "Mother", "sex": "F", "mother": "MGM", "father": "MGF", "conditions": [{"name": "Breast cancer", "age": 42}]},
  {"name": "Father", "sex": "M", "top_level": true},
  {"name": "Proband", "display_name": "Sarah", "sex": "F", "mother": "Mother", "father": "Father", "proband": true, "age": 25, "brca1_gene_test": {"type": "T", "result": "P"}}
]

Neurological Condition Pedigree

[
  {"name": "GF", "sex": "M", "top_level": true, "status": 1, "conditions": [{"name": "Huntington's disease", "age": 52}]},
  {"name": "GM", "sex": "F", "top_level": true},
  {"name": "Father", "sex": "M", "mother": "GM", "father": "GF", "conditions": [{"name": "Huntington's disease", "age": 48}]},
  {"name": "Mother", "sex": "F", "top_level": true},
  {"name": "Proband", "sex": "M", "mother": "Mother", "father": "Father", "proband": true, "age": 25, "carrier": true}
]

Twins Example

[
  {"name": "Dad", "sex": "M", "top_level": true},
  {"name": "Mom", "sex": "F", "top_level": true},
  {"name": "Twin1", "sex": "M", "mother": "Mom", "father": "Dad", "mztwin": "mz1"},
  {"name": "Twin2", "sex": "M", "mother": "Mom", "father": "Dad", "mztwin": "mz1"},
  {"name": "DZTwin1", "sex": "M", "mother": "Mom", "father": "Dad", "dztwin": "dz1"},
  {"name": "DZTwin2", "sex": "F", "mother": "Mom", "father": "Dad", "dztwin": "dz1"}
]

Complex Family with Bennett Features

[
  {"name": "GF", "sex": "M", "top_level": true, "status": 1},
  {"name": "GM", "sex": "F", "top_level": true, "carrier": true},
  {"name": "Father", "sex": "M", "mother": "GM", "father": "GF", "divorced": true},
  {"name": "Mother", "sex": "F", "top_level": true},
  {"name": "Child1", "sex": "F", "mother": "Mother", "father": "Father", "proband": true, "noparents": true},
  {"name": "Loss", "sex": "U", "mother": "Mother", "father": "Father", "terminated": true}
]

Development

# Install dependencies
npm install

# Run in development mode (watch)
npm run dev

# Run all tests
npm test

# Build for production
npm run build

# Type check
npx tsc --noEmit

Testing

159 tests total covering:
- Validation (parent references, gender constraints)
- SVG rendering (all symbol types, indicators)
- Condition markers and multi-condition pie charts
- Gene test formatting
- Twin rendering (MZ with bar, DZ without)
- Consanguinity detection
- Bennett 2008 compliance (carrier, pregnancy, termination, divorced)
- Edge cases (deep pedigrees, wide generations, half-siblings)

References

License

MIT License - see