Repository navigation
Agent Tools Overview
This page covers the local, agent-facing ways to create, inspect, render, and export ChemDraft structures without automating the desktop interface.
ChemDraft 1.0.0 offers three related local interfaces:
| Interface | Best for | Runs where |
|---|---|---|
| Command-line interface (CLI) | Scripts, repeatable batches, and direct shell use | In a ChemDraft checkout |
| Model Context Protocol (MCP) server | A local assistant that can call tools | On the same computer as that assistant |
| Agent skill | Instructions that help Claude Code or Codex use the local CLI/MCP carefully | In that assistant's skill directory |
All three use the same document and rendering path rather than a separate “agent drawing” implementation. They accept untrusted input with limits: chemical input is limited to 5,000 characters and 500 heavy atoms, and JSON batches are limited to 500 jobs. File names and batch names are checked for portable, safe output names. A requested chemical export is checked against the source canonical SMILES; if identity cannot be preserved, it fails instead of quietly changing the structure.
Use the CLI when you want files on disk, especially a batch. Its stdout is JSON Lines: one complete JSON result per line, while progress goes to stderr. Use MCP when an assistant should receive a result and image directly in its tool response. The MCP server calls the CLI command modules in process, avoiding a second behavior to maintain. Use the skill to give an assistant the workflow rules: inspect warnings, verify stereochemistry, and do not guess an ambiguous structure.
The available operations are structure rendering, editable native-document construction, styled-document rendering, grids, reaction schemes, analysis, name conversion, stereochemistry inspection, NMR prediction, and chemical-file export. The Command-Line CLI page is the detailed command reference; MCP Server maps those operations to tools.
A grid is useful for comparing several confirmed structures; inspect labels and stereochemical marks before using it.
Agents should treat a successful transport result as the beginning of review, not proof that every requested scientific value exists. Analysis results carry statuses; “not requested” and “not computed” are different. Derived interpretations are identified in results rather than silently substituted for the drawn structure. NMR shifts are predictions from the OCL-native HOSE-fragment lookup over NMRShiftDB2 experimental assignments. Multiplicities and J values are first-order estimates, and unmatched environments remain warnings rather than invented values.
The optional NMR predictor is external code. Its directory must be explicitly listed in the owner-controlled trust file. Setting CHEMDRAFT_NMR_PLUGIN_DIR only selects among trusted directories; it does not grant trust. See MCP Server for the file shape and platform paths.
The interfaces do not edit an open desktop canvas. When a plugin or agent does change a ChemDraft document inside the application, the change must go through a labelled patch, producing one undo entry and leaving what changed selected. That makes changes reviewable rather than a side effect hidden in UI state.
The CLI and MCP server run locally. A web-only chat cannot reach a program on your computer. Install the checkout, Node 24, and pnpm 10.12.1 on the machine that will run the assistant. Name conversion also needs a JDK and the locally built OPSIN runtime. The full copy-and-paste setup for macOS and Windows is in Agent Setup Recipes.
pnpm -s is significant in command and MCP launch examples: the silent flag prevents a package-script banner from corrupting JSON Lines or MCP stdio framing. On Windows, invoke the CLI with --config.shell-emulator=true; it avoids pnpm doubling backslashes in command arguments.