# CEMP Public HTTP MCP — Agent Guide

This service exposes CEMP through Streamable HTTP at:

```text
https://mcp.cleanenergymaterials.cn/mcp
```

It currently advertises 32 tools: 25 CEMP business tools, 3 account tools, and 4 usability/input-preparation tools. Without an `Authorization` header, the service uses a shared temporary test account. The response includes an anonymous notice and the [CEMP registration page](https://cleanenergymaterials.cn/register/register/). With `Authorization: Bearer <CEMP token>`, the request uses the registered user’s CEMP permissions, quota, and audit identity.

## Fast setup

Anonymous Codex setup:

```bash
codex mcp add cemp-tools \
  --url https://mcp.cleanenergymaterials.cn/mcp
codex mcp get cemp-tools --json
```

Registered users should call `POST /auth/login` once, keep the returned token only on their own computer, and configure the client’s bearer-token environment-variable feature:

```bash
codex mcp add cemp-tools \
  --url https://mcp.cleanenergymaterials.cn/mcp \
  --bearer-token-env-var CEMP_MCP_TOKEN
```

Do not put a CEMP password in MCP configuration. The server does not persist registered-user passwords or tokens.

## Agent operating rules

1. Call `get_cemp_tool_guide` when the user’s goal is ambiguous.
2. Ask only for scientifically critical missing fields. Show every safe default and assumption explicitly.
3. For `excel_file`, first upload a local file with `POST /uploads`, or create a server-side draft with `create_cemp_excel_draft`.
4. Show a generated draft’s preview, validation, assumptions, and download link. Wait for explicit user confirmation, then call `confirm_cemp_excel_draft`.
5. Submit the matching business tool only after confirmation. Confirmation never submits a job automatically.
6. Never send a local path, Mac Studio path, URL, or Base64 in a file argument. Use the returned opaque `upload_id`.
7. For asynchronous tools, save `encrypted_id` and poll `get_task_status` using `poll_after_seconds`. `terminal=false` means keep polling; `do_not_resubmit=true` always applies.
8. A timeout, 5xx, or network disconnect makes a submission result unknown. Do not automatically submit the same job again.
9. CEMP decides permissions, quota, and business validation. Do not simulate or bypass those checks.

## Uploads

```bash
curl --fail-with-body \
  -F "file=@/absolute/path/System.xlsx" \
  https://mcp.cleanenergymaterials.cn/uploads
```

Each request accepts exactly one file. The response contains `upload_id`, `filename`, `size_bytes`, `sha256`, and `expires_at`. Files are retained for one hour, are reusable during that period, and are not user-isolated. The maximum file size is 1 GiB and the temporary store is capped at 20 GiB. `files` parameters receive an array of IDs, one ID per upload.

## Draft workflow

`create_cemp_excel_draft` accepts a tool name, an array of row objects, and optional `assumptions`. It supports these Excel-capable tools:

`mdcompute`, `single_point_energy_gaussian`, `binding_energy_gaussian`, `pka_pkb_gaussian`, `ox_red_gaussian`, `reaction_thermo_gaussian`, `reaction_properties_gaussian`, `single_point_energy_orca`, `binding_energy_orca`, `ox_red_orca`, `query_smiles_to_name`, `ionic_liquid_predict_excel`, and `polymer_predict_excel`.

Example:

```json
{
  "tool_name": "polymer_predict_excel",
  "rows": [{"Name": "PEO", "PSMILES": "[*]CCO[*]"}],
  "assumptions": []
}
```

The result includes a first-20-row `preview`, `validation`, `assumptions`, `download_url`, `resource_uri`, and `requires_user_confirmation: true`. A generated draft cannot be submitted until `confirm_cemp_excel_draft` succeeds. Drafts contain values only—no formulas, macros, or server paths.

## Validation and confirmation

```json
{"tool_name":"mdcompute","upload_id":"<upload_id>"}
```

`validate_cemp_input` returns `ready`, `errors` with `row`, `field`, `code`, and Chinese/English messages, `warnings`, and a preview. It creates no task. For direct SMILES/PSMILES tools, pass `arguments` instead of `upload_id`.

```json
{"upload_id":"<draft-upload-id>"}
```

`confirm_cemp_excel_draft` returns `target_tool` and `submit_arguments`; pass those arguments to that exact tool only.

## Tool catalog

| Tool | Purpose | Input | Mode |
|---|---|---|---|
| `get_task_status` | Query an asynchronous task | `encrypted_id` | direct |
| `mdcompute` | Gromacs molecular dynamics | System Excel upload ID | async |
| `markov_gdynet_analysis` | Markov/GDyNet analysis of a completed MD task | MD `encrypted_id` | async |
| `single_point_energy_gaussian` | Gaussian single-point energy | HTQC Excel upload ID | async |
| `binding_energy_gaussian` | Gaussian dimer binding energy | Dimer Excel upload ID | async |
| `pka_pkb_gaussian` | Gaussian pKa/pKb | acid/base Excel upload ID | async |
| `ox_red_gaussian` | Gaussian redox potential | Name/SMILES Excel upload ID | async |
| `reaction_thermo_gaussian` | Gaussian reaction thermodynamics | reaction Excel upload ID | async |
| `reaction_properties_gaussian` | Gaussian reaction descriptors/sites | reaction Excel upload ID | async |
| `single_point_energy_orca` | ORCA single-point energy | HTQC Excel upload ID | async |
| `binding_energy_orca` | ORCA dimer binding energy | Dimer Excel upload ID | async |
| `ox_red_orca` | ORCA redox potential | Name/SMILES Excel upload ID | async |
| `query_smiles_to_name` | Batch SMILES-to-name lookup | SMILES Excel upload ID | async |
| `draw_esp_gaussian` | Gaussian ESP plot | `.fchk`/compatible `.chk` IDs | async |
| `draw_esp_orca` | ORCA ESP plot | `.molden`/compatible `.gbw` IDs | async |
| `draw_homo_lumo` | HOMO/LUMO plot | wavefunction file IDs | async |
| `nci_scf` | SCF NCI analysis | wavefunction file IDs | async |
| `nci_promolecular` | Promolecular NCI analysis | structure file IDs | async |
| `ionic_liquid_predict_excel` | Batch ionic-liquid prediction | Name/SMILES Excel upload ID | direct |
| `ionic_liquid_predict_smiles` | Single ionic-liquid prediction | `smiles` | direct |
| `polymer_predict_excel` | Batch polymer prediction | Name/PSMILES Excel upload ID | direct |
| `polymer_predict_psmiles` | Single polymer prediction | `psmiles` | direct |
| `crystal_predict_excel` | Crystal CIF prediction | CIF upload ID, optional `model_select` (default `GAT`) | direct |
| `material_recommendation_search` | Material database recommendation | `query`, optional domains/top-k/seeds | direct |
| `molecule_property_similarity_search` | Exact/similar structure property search | `smiles`, optional top-k/fingerprint settings | direct |
| `register_cemp_account` | Create an unactivated CEMP account | username, email, two passwords | account |
| `activate_cemp_account` | Activate an account | registration ID, activation code | account |
| `resend_cemp_activation_code` | Resend activation mail | email | account |
| `get_cemp_tool_guide` | Bilingual guide and examples | `tool_name` or alias | direct |
| `create_cemp_excel_draft` | Create a review-only workbook | `tool_name`, `rows`, assumptions | direct |
| `validate_cemp_input` | Validate upload or direct arguments | upload ID or arguments | direct |
| `confirm_cemp_excel_draft` | Mark a generated draft reviewed | draft upload ID | direct |

Use `cemp://catalog` for the machine-readable catalog, `cemp://tools/{tool_name}` for one tool, `cemp://templates/{tool_name}` for template metadata, and `cemp://drafts/{upload_id}` for generated-draft metadata. The prompts `cemp_select_tool`, `cemp_prepare_input`, and `cemp_run_reviewed_task` provide reusable workflow text.

## Async result handling

An asynchronous response contains:

```json
{
  "encrypted_id": "<opaque-task-key>",
  "phase": "submitted",
  "terminal": false,
  "poll_after_seconds": 15,
  "next_action": "调用 get_task_status 查询任务状态。",
  "do_not_resubmit": true
}
```

Poll until `terminal=true`. Results and downloads remain CEMP-owned; this MCP does not add a download proxy.

## Limits and errors

The HTTP service limits normal MCP requests to 60/min/IP, asynchronous submissions to 5/hour/IP, uploads to 10/hour/IP and two concurrent uploads/IP. Registration is limited to 3/day/IP, login to 10/hour/IP, activation to 10/hour/IP, and activation resend to 3/hour/IP with a five-minute per-email interval. CEMP account quotas still apply.

Important error codes include `draft_confirmation_required`, `draft_tool_mismatch`, `invalid_upload_id`, `upload_expired`, `file_too_large`, `upload_storage_full`, `permission_denied`, `reauthentication_required`, `upstream_timeout`, and `upstream_error`. Follow `Retry-After` for rate limits. Never automatically resubmit an asynchronous job after an unknown result.

## End-to-end examples

### Similarity search

```json
{"name":"molecule_property_similarity_search","arguments":{"smiles":"CCO","topk":3}}
```

### PSMILES prediction

```json
{"name":"polymer_predict_psmiles","arguments":{"psmiles":"*CC*"}}
```

### Excel draft, review, submit, poll

1. Call `create_cemp_excel_draft` with structured rows.
2. Show `preview`, `validation`, `assumptions`, and `download_url` to the user.
3. After explicit approval, call `confirm_cemp_excel_draft`.
4. Submit the returned `submit_arguments` to the matching tool.
5. Save `encrypted_id`, then call `get_task_status` after the suggested interval.