{
  "markdown": "# ChemGlyph\n\nPublication-quality chemical structure and reaction rendering for AI agents.\nChemGlyph is the KaTeX of chemistry: a rendering layer, a validation layer,\nand an MCP interface on top of [RDKit](https://www.rdkit.org).\n\n[![CI](https://github.com/chemglyph/chemglyph/actions/workflows/ci.yml/badge.svg)](https://github.com/chemglyph/chemglyph/actions/workflows/ci.yml)\n\n## Install\n\n```bash\npip install chemglyph\n```\n\n## Render a molecule\n\n```python\nimport chemglyph\n\nresult = chemglyph.render_molecule(\"c1ccccc1\")  # benzene\nopen(\"benzene.svg\", \"w\").write(result.data)\n```\n\n`render_molecule` takes SMILES, InChI, or molblock and returns SVG (or PNG)\nplus `canonical_smiles`, `mol_formula`, `mol_weight`, and `warnings`.\n\n## Styles\n\nThree styles, same molecule (benzoic acid, caffeine, (S)-ibuprofen):\n\n![ChemGlyph style gallery](https://raw.githubusercontent.com/chemglyph/chemglyph/main/docs/images/gallery_3x3.png)\n\n```python\nchemglyph.render_molecule(smiles, style=\"acs\")  # black/white, ACS journal\nchemglyph.render_molecule(smiles, style=\"modern\")  # colored heteroatoms, screens\nchemglyph.render_molecule(smiles, style=\"textbook-cn\")  # bold monochrome, textbook\n```\n\nAll styles default to a transparent background (`transparent=True`) and\nsupport `fmt=\"png\"`.\n\n## Reactions\n\n```python\nspec = {\n    \"steps\": [\n        {\n            \"reactants\": [\"OC(=O)c1ccccc1O\", \"CC(=O)OC(C)=O\"],\n            \"products\": [\"CC(=O)Oc1ccccc1C(=O)O\", \"CC(=O)O\"],\n            \"conditions\": {\"above\": \"H₂SO₄ (cat.)\", \"below\": \"rt, 15 min\"},\n            \"yield\": \"89%\",\n            \"arrow\": \"forward\",\n        }\n    ],\n    \"style\": \"modern\",\n}\nsvg = chemglyph.render_reaction(spec)\n```\n\nConditions are pre-formatted Unicode text, so pass `H₂SO₄`, not `H2SO4`.\nChemGlyph does not parse formulas out of text. The full schema\n(multi-step chains, equilibrium and retro arrows, line wrapping) is in\n[docs/reaction_schema.md](docs/reaction_schema.md).\n\nThe aspirin demo writes a two-step route:\n\n```bash\npython examples/aspirin_synthesis.py  # writes examples/aspirin_synthesis.svg\n```\n\n## Validation\n\n`validate_structure` reports parse errors and applies four quick fixes:\nunmatched brackets and ring closures (reported, not guessed), kekulization\nfailures of lowercase aromatic atoms, and nitrogen valence errors via a\nformal `[N+]`. Anything else passes RDKit's message through unchanged.\n\n```python\nreport = chemglyph.validate_structure(\"c1cccc1\")\nreport.fixes[0].description  # 'lowercase aromatic atoms could not be kekulized...'\nreport.fixes[0].fixed_smiles  # 'C1CCCC1'\n```\n\n## Naming\n\n```python\nchemglyph.parse_name(\"aspirin\")  # 'CC(=O)Oc1ccccc1C(=O)O'\n```\n\nEnglish IUPAC and common names resolve offline through OPSIN\n(`pip install 'chemglyph[opsin]'`, plus a Java runtime). Chinese names use\nthe built-in dictionary, and the library API accepts a translator callable\nfor names that are not in it:\n\n```python\nchemglyph.parse_name(\"阿司匹林\")  # 'CC(=O)Oc1ccccc1C(=O)O'\nchemglyph.parse_name(\"六甲基苯\", translator=to_english)\n```\n\nChemGlyph itself never calls an online service, including for translation.\n\n## MCP server\n\nRun the bundled console script (stdio transport):\n\n<!-- mcp-name: io.github.random-orbit/chemglyph -->\n\n```bash\nchemglyph-mcp\n```\n\nClaude Desktop registration (macOS:\n`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"chemglyph\": {\n      \"command\": \"chemglyph-mcp\"\n    }\n  }\n}\n```\n\n| Tool | Use it when | Returns |\n|---|---|---|\n| `render_molecule` | the user asks to draw one structure from SMILES/InChI/molblock | PNG image plus formula, MW, warnings (SVG source on request) |\n| `render_reaction` | the user asks for a reaction or synthesis route | PNG image of the reaction scheme |\n| `validate_structure` | a SMILES may be malformed and you need a repair | validation report JSON |\n| `parse_name` | the user gives a name like \"aspirin\" instead of SMILES | canonical SMILES or an error |\n\nOne thing to know about clients. Some MCP clients, LM Studio included, only\npass the text part of a tool result to the model and never display the\nattached image. The render tools write their PNG to `~/Downloads/chemglyph/`\nand return that path in the text, so you can always open the file yourself.\nIf a model claims it rendered a figure but nothing shows up, ask it for the\nsaved path rather than having it redraw the structure by hand.\n\n## Benchmarks\n\n`benchmarks/` holds the fixed 20-molecule blind test and a generator that\nwrites shuffled, numbered PNG/SVG figures plus `answer_key.json`:\n\n```bash\npython benchmarks/generate_blind_test.py --seed 1234\n```\n\nThe deck, methodology, and scoring tooling are all open-sourced: the fixed\nmolecule list, the A/B deck generator (which pairs ChemGlyph against an\nopen-source reference renderer), the runbook, and the scorer live in\n[benchmarks/](benchmarks/). Anyone can run the protocol and contribute\nresults. The pass threshold and procedure are documented in\n[benchmarks/RUNBOOK.md](benchmarks/RUNBOOK.md).\n\n![ChemGlyph vs open-source reference](https://raw.githubusercontent.com/chemglyph/chemglyph/main/docs/images/comparison_vs_reference.png)\n\nBlind test vs ChemDraw: pending. The image above is an author-generated\ncomparison of ChemGlyph `modern` against the open-source reference renderer\n(Indigo, the engine behind Ketcher) - it is not an independent review.\n\n## Known limitations\n\n- Blind-test figures for ferrocene (metal complex) and the free-base\n  porphyrin (large conjugated macrocycle) are excluded from the benchmark\n  denominator and recorded separately.\n- RDKit has no clean 2D layout for paclitaxel: its gem-dimethyl substituent\n  placement inside the central 8-membered ring is a documented layout\n  limitation.\n- Full automatic Chinese name-to-structure parsing is not implemented;\n  Chinese names resolve through a small built-in dictionary plus an optional\n  translator hook. English names resolve through OPSIN.\n\n## Roadmap\n\n- v0.2: Chinese naming (built-in dictionary plus translator hook), down-arrow\n  line wrapping, arrow column alignment, cropped fragments. All shipped.\n- Next: mechanism (electron-pushing) arrows, see\n  [docs/progress/v02-research.md](docs/progress/v02-research.md).\n- Later: a larger Chinese dictionary as an optional data extra.\n\n## Non-goals\n\nNo structure editor GUI (Ketcher/ChemDraw competition), no 3D visualization,\nno retrosynthesis or property prediction, no online database queries, and no\nautomatic mechanism generation. The full list is in the project\nspecification.\n\n## Development\n\n```bash\npython -m venv .venv\n.venv/bin/pip install -e \".[dev]\"\n.venv/bin/ruff check . && .venv/bin/ruff format . && .venv/bin/pytest\n```\n\nPython 3.11+, RDKit 2024.9+, MIT license. All errors derive from\n`chemglyph.errors.ChemGlyphError`.\n",
  "bytes": 6786,
  "sha": "3ca1e3f8aff72655543efaefd4937a828cf0098702440ca74af2bbeaa4bc7d8d",
  "repo_slug": "chemglyph/chemglyph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_random_orbit_chemglyph_15116c5e/readme"
}