{
  "markdown": "# PyLipidParse\n\nConvert standard lipid shorthand notation (LIPID MAPS, SwissLipids, HMDB) to molecular structures.\n\n[![CI](https://github.com/MontgomeryBohde/PyLipidParse/actions/workflows/ci.yml/badge.svg)](https://github.com/MontgomeryBohde/PyLipidParse/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/pylipidparse.svg)](https://pypi.org/project/pylipidparse/)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## What it does\n\nNo existing open-source tool converts lipid shorthand notation to SMILES, InChI, or RDKit molecules. PyLipidParse fills this gap.\n\n```python\nfrom pylipidparse import LipidConverter\n\nconv = LipidConverter()\n\nconv.to_smiles(\"PC 16:0/18:1(9Z)\")\n# → 'CCCCCCCCCCCCCCCC(=O)OC[C@@H](OC(=O)CCCCCCCC/C=C\\\\CCCCCCCC)COP(=O)([O-])OCC[N+](C)(C)C'\n\nconv.to_inchikey(\"FA 18:2(9Z,12Z)\")\n# → 'OYHQOLUKZRVURQ-HZJYTTRNSA-N'\n\nconv.to_mol(\"Cer 18:1;O2/16:0\")\n# → <rdkit.Chem.rdchem.Mol object>\n\nconv.to_sdf([\"PC 16:0/18:1(9Z)\", \"PE 18:0/20:4(5Z,8Z,11Z,14Z)\"], path=\"output.sdf\")\n```\n\n## Supported lipid classes\n\n| Class | Examples | Status |\n|-------|----------|--------|\n| Fatty Acids (FA) | FA 16:0, FA 18:1(9Z), FA 20:4(5Z,8Z,11Z,14Z) | ✅ |\n| Glycerolipids (GL) | MG, DG, TG | ✅ |\n| Glycerophospholipids (GP) | PC, PE, PA, PI, PS, PG, LPC, LPE, ... | ✅ |\n| Sphingolipids (SP) | Cer, SM, HexCer, Hex2Cer | ✅ |\n| Sterols (ST) | Cholesterol, CE, bile acids | ✅ |\n| Ether/plasmalogen linkages | O-, P- prefix | ✅ |\n\n## Installation\n\n### pip\n\n```bash\npip install pylipidparse\n```\n\n### uv\n\n```bash\nuv add pylipidparse\n```\n\n### MCP server (for Claude / AI assistants)\n\n```bash\npip install \"pylipidparse[mcp]\"   # requires Python 3.10+\n```\n\n### From source\n\n```bash\ngit clone https://github.com/MontgomeryBohde/PyLipidParse.git\ncd PyLipidParse\npip install -e \".[dev]\"\n```\n\n## Quick start\n\n```python\nfrom pylipidparse import LipidConverter\n\nconv = LipidConverter()\n\n# SMILES\nsmiles = conv.to_smiles(\"FA 18:1(9Z)\")        # Oleic acid\nsmiles = conv.to_smiles(\"PC 16:0/18:1(9Z)\")   # POPC\n\n# InChI / InChIKey\ninchi = conv.to_inchi(\"FA 16:0\")\nik = conv.to_inchikey(\"FA 16:0\")   # \"IPCSVZSSVZVIGE-UHFFFAOYSA-N\"\n\n# RDKit Mol (for downstream cheminformatics)\nmol = conv.to_mol(\"Cer 18:1;O2/16:0\")\n\n# Write to file\nconv.to_mol_file(\"PC 16:0/18:1(9Z)\", \"popc.mol\")\nconv.to_sdf([\"FA 16:0\", \"FA 18:1(9Z)\", \"PC 16:0/18:1(9Z)\"], \"lipids.sdf\")\n```\n\n## Notation requirements\n\nPyLipidParse requires **full structural notation** with explicit chain positions.\nSum-composition notation (e.g., `PC 34:1`) is rejected because a unique structure\ncannot be generated from it.\n\n| Works | Fails |\n|-------|-------|\n| `PC 16:0/18:1(9Z)` | `PC 34:1` (no chain breakdown) |\n| `TG 16:0/18:1(9Z)/18:2(9Z,12Z)` | `TG 16:0_18:1_18:2` (unknown positions) |\n| `FA 18:1(9Z)` | `FA 18:1` (no double bond position) |\n\n## Use with Claude (MCP server)\n\nPyLipidParse includes an MCP server so you can convert lipid names directly inside Claude Code\nor Claude Desktop — no Python required.\n\n**Claude Code plugin** — install from [claude.com/plugins](https://claude.com/plugins) (search\n*PyLipidParse*) or load locally:\n\n```bash\nclaude --plugin-dir ./claude-code-plugin\n```\n\n**Manual MCP config** — add to `.mcp.json` or run:\n\n```bash\nclaude mcp add pylipidparse -- uvx --from \"pylipidparse[mcp]\" pylipidparse-mcp\n```\n\nThen ask Claude naturally:\n\n```\nWhat is the SMILES for PC 16:0/18:1(9Z)?\nConvert these ceramides to InChIKey: Cer 18:1;O2/16:0, Cer 18:1;O2/24:1(15Z)\nExport these 20 lipids as an SDF file.\n```\n\nSix tools are available: `lipid_to_smiles`, `lipid_to_inchi`, `lipid_to_inchikey`,\n`batch_convert_lipids`, `lipid_to_mol_file`, `lipids_to_sdf`.\nSee the [MCP documentation](https://montgomerybohde.github.io/PyLipidParse/mcp/) for full details.\n\n## API reference\n\n### `LipidConverter(dialect=\"LipidMaps\", cache_size=512)`\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `to_mol(name)` | `Chem.Mol` | RDKit molecule (no 2D coords) |\n| `to_smiles(name)` | `str` | Canonical SMILES |\n| `to_inchi(name)` | `str` | InChI string |\n| `to_inchikey(name)` | `str` | InChIKey (27-char hash) |\n| `to_mol_file(name, path)` | — | Write `.mol` file with 2D coords |\n| `to_sdf(names, path)` | — | Write `.sdf` file (supports batch) |\n\n### Exceptions\n\n```python\nfrom pylipidparse.exceptions import (\n    LipidParseError,                  # pygoslin couldn't parse the input\n    UnsupportedLipidClassError,       # lipid class not yet implemented\n    InsufficientStructuralDetailError, # species-level / unknown positions\n    StructureGenerationError,         # molecule assembly failed\n)\n```\n\n## Contributing\n\nIssues and pull requests are welcome at [github.com/MontgomeryBohde/PyLipidParse](https://github.com/MontgomeryBohde/PyLipidParse/issues).\n\n## Citation\n\nIf you use PyLipidParse in published work, please cite this repository and the\nunderlying tools:\n\n- **pygoslin:** Kopczynski et al., *Analytical Chemistry* (2022). DOI: 10.1021/acs.analchem.1c05430\n- **RDKit:** Landrum, G. *RDKit: Open-source cheminformatics.* [rdkit.org](https://www.rdkit.org)\n\n## License\n\nMIT License — see [LICENSE](LICENSE).\n",
  "bytes": 5237,
  "sha": "ef0036bb26614356f8dc547b501410e5f600a67da866a6697cdae407fe9c1a3c",
  "repo_slug": "montgomerybohde/pylipidparse",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_montgomerybohde_pylipidparse_pylipidpars_41285be5/readme"
}