io.github.chowdhurylab-studio/ipro-agent
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| IPRO_REPO | No | Path to a checkout so the server can serve its own documents rather than tell the agent where to fetch them. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Protein redesign via IPRO.
Read the resource ipro://skill before anything beyond a single tool call -- it is the operating manual, and it carries the degraded modes, the spec format and the validation checklist that these tool descriptions cannot. ipro://house-rules is the short version.
Call ipro_doctor first and report the mode it gives with any result; if it says can_design is false, use ipro_setup rather than guessing at the install. Validate a spec before running one. ipro_run is detached: poll ipro_status, never read iterations.jsonl. A run with accepted: 0 designed nothing -- its best_* fields are the starting point. Energies from the built-in backend are a screening scale, not kcal/mol comparable to the published papers. Never quietly weaken a constraint the user stated to make a failing run succeed. Every design is a hypothesis for the bench.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| ipro_doctorA | What is installed and what a run can therefore do. Call this FIRST: it returns can_run, can_design and the degraded backend list, and the resolved mode must be reported with any design. |
| ipro_setupA | Check whether this machine can actually run a design and, with confirm=true, install what is missing. Call it when ipro_doctor reports can_design=false. PyMOL is conda-only and has no fallback, so pip cannot fix it. Installs nothing without confirm=true; tell the user what it will do first. |
| ipro_fetch_structureA | Download a structure from the RCSB PDB by its four-character ID (e.g. 2OMF), optionally writing a copy reduced to one chain. This is the ONLY tool here that uses the network. Use it when the user names a protein or a PDB entry rather than giving you a file. Always check what you got with ipro_inspect_structure afterwards: resolution, missing residues and engineered mutations all change what a design means. |
| ipro_inspect_structureA | What is in a structure file: chains, residue counts and ranges, the one-letter sequence, ligands and waters -- and, for residues you name, the NATIVE identity plus a ready-to-paste spec line. Call this before writing a spec, every time. A user who says 'residues 18, 20, 38 and 40' has not said which chain, and a residue number that resolves to the wrong chain silently designs a different residue. It needs no PyMOL and no network. |
| ipro_goalsA | The design objectives this tool can express (bind_tighter, switch_specificity, reshape_channel, improve_catalysis, stabilize), each with the paper it comes from. Use it to pick a goal before writing a spec. |
| ipro_validateA | Check a design spec without spending any CPU: parses it, resolves positions against the structure, reports the design-space size and every problem found. Always do this before ipro_run. |
| ipro_positionsB | Propose design positions from the structure: residues of the design molecule within a cutoff of a named partner, i.e. the interface or pocket. Use it when the user says 'the interface' instead of listing residue numbers. |
| ipro_scoreA | Measure a structure without designing anything: interaction energies per partner, the goal's score and its components, plus the run mode and notes. Use it for a wild-type baseline, or to get goal_options.reference_interaction before a constrained run. |
| ipro_milpA | Emit the rotamer-selection integer program as a CPLEX LP file and report its size. Use it to prove to a user that their stated constraints really are in the program before a long run. |
| ipro_runA | Launch a design run and return immediately with a run id. The run is DETACHED and can take minutes to days, so poll ipro_status rather than waiting. Refuses to launch when a design is impossible (no PyMOL). Always pass max_minutes for an unattended run. |
| ipro_statusA | Progress of a run: iterations, how many were ACCEPTED, the best score and mutations, the mode and the notes. Cheap and bounded in size however long the run has gone on, so it is safe to poll. Never read iterations.jsonl directly -- it grows without limit. |
| ipro_resultA | The design a run produced: the mutation string, the sequence, the score change, the components, the notes, the ensemble of alternatives, and -- with include_structure -- the designed PDB itself. Report from this rather than from ipro_status alone: an MCP client has no shell, so this is the only way to hand over the coordinates. If no mutation was kept it says so, and the structure is then the starting point. |
| ipro_iterationsA | The tail of the trajectory: per-iteration score, whether it was accepted, and why it was rejected. The reporting rule tells you to read the per-iteration reasons, and this is how. Never read iterations.jsonl directly; it grows without limit. |
| ipro_runsA | Every run this server can see, with its status. For when a run id has been lost, or to check what is already running before starting another. |
| ipro_cancelA | Stop a running design. It stops after the iteration it is in and keeps what it has written, so the best design found so far is still readable with ipro_result. Only runs this server started, on this machine. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| ipro-redesign | Redesign a protein toward a stated goal, start to finish, the way the operating manual says to. |
| ipro-check-setup | Check whether this machine can run a design, and fix it if not. |
| ipro-report | Turn a finished run into an honest report, with the mode, the notes and the caveats the house rules require. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Operating manual (SKILL.md) | READ THIS FIRST for anything beyond a single tool call. Goal selection, spec format, encoding a user's constraints into the integer program, the degraded modes, and the validation checklist to work through before reporting a design. Everything the tool schemas cannot say. |
| House rules | The non-negotiables: report the mode and notes with every design, never present screening energies as published kcal/mol, never quietly weaken a user's stated constraints, and when to stop and ask a human. |
| README, including Responsible use | What the tool is, what it has actually been run on, its known open defect, and the scope-of-use limits that need a human decision before anything is run. |
| Provenance and deviations (DESIGN.md) | Every capability traced to the paper and equation it came from, every deviation from the published method, and every defect found by audit with the measurement that exposed it. Use it to answer 'where does this number come from'. |
| The integer program | The rotamer-selection formulation in full, with its constraints. |
| Dependencies and what each unlocks | What PyMOL, PyRosetta, AutoDock Vina and a MILP solver each buy, and what their absence costs. Pair with ipro_setup. |
| Worked example spec (annotated) | A complete, heavily commented spec to copy from: molecules, positions, allowed residues, restraints, goal options. The fastest way to write a correct spec for a new protein. |
| What the worked example can and cannot reproduce | An honest account of which comparisons against the published paper are meaningful, and which are not available at all. |
TDQS
Scored across 15 tools
Most tools occupy clearly separate slots in the workflow (doctor vs setup, fetch vs inspect, validate vs run vs cancel), and descriptions explicitly carve out boundaries such as 'never read iterations.jsonl directly' and 'report from ipro_result rather than ipro_status alone'. The only genuinely adjacent trio is ipro_status / ipro_iterations / ipro_result, where the distinction is real but relies on careful reading of the descriptions.
Every tool is namespaced with the same ipro_ prefix and uses lower snake_case, with predictable noun or verb_noun forms (ipro_fetch_structure, ipro_inspect_structure, ipro_validate, ipro_run). No mixed casing or style outliers anywhere in the set.
At 15 tools the set sits at the upper edge of the ideal band, but the count is largely earned by a multi-stage workflow: environment checks, structure acquisition/inspection, spec validation, execution, polling, cancellation, and reporting all need separate calls. A couple of members (ipro_milp, and arguably ipro_score) are niche diagnostic extras rather than core operations.
Coverage is strong end to end: readiness check, installation, structure fetch and inspection, goal selection, position proposal, validation, launch, status, per-iteration reasons, result with coordinates, run listing, and cancellation. The remaining gaps are minor housekeeping — no way to persist a spec or result to disk, and no cleanup/removal of old runs.