从范围明确的查询任务开始
一个实用的初始集成应回答一个范围较窄的问题：识别目标化合物，并在保留来源背景的同时检索少量属性。不要一开始就让智能体不受限制地调用所有搜索、信息补充和解释操作。
本指南提出的是集成设计与评估计划，并非经过测试的部署方案。本文未实际运行 PubChem MCP (cyanheads)，未测试特定客户端，也未对返回记录进行科学验证。下文提及的资源能力来自项目文档；工作流控制则是建议。
选择接口前，请先确定：用户会提供哪些标识符？需要哪些字段？身份不确定时应如何处理？任务能否在结果不完整时停止，而不是给出看似合理的答案？
解释属性之前先确认身份
化学名称可能无法明确结构、立体化学或具体形式。应将身份解析与属性检索分为两个阶段。
- 保留原始查询，并标明其命名空间：名称、SMILES、InChIKey 或 PubChem Compound Identifier (CID)，具体取决于所选接口。
- 获取候选标识符，但不要默默选取第一个结果。
- 根据用户意图检查返回的结构表示和识别字段。
- 如果仍存在歧义，请用户提供更精确的标识符，或确认某个候选项。
- 在后续调用中传递已选定的 CID 和返回的结构表示。
记录集成过程中进行的任何规范化或选择决策。查找失败时，不要让智能体悄悄换成相关化合物、盐或立体异构体。相似性搜索的结果只是供比较的候选项，并不能证明身份相同。
选择便于检查的接口
PubChem PUG REST 是了解 PubChem 程序化接口的官方入口。页面摘录未能确认详细的端点行为，因此在指定请求前请查阅其文档。
PubChemPy 是 PUG REST 的 Python 封装。其 README 介绍了名称、子结构和相似性搜索、属性检索、标准化、格式转换和结构绘制。示例展示了通过 Compound.from_cid 获取 CID，以及通过 get_compounds 按名称搜索；化合物属性包括 SMILES、IUPAC 名称和分子量。Python 应用可以将受限的功能子集封装为智能体工具；这是建议的集成方式，并非已确立的智能体功能。
社区维护的 PubChem MCP server 以 @cyanheads/pubchem-mcp-server 打包，其文档介绍了用于搜索、化合物详情、安全记录、生物活性、交叉引用和其他记录类型的工具。它使用 PubChem 的 PUG REST 和 PUG View API，并说明了 STDIO 和 Streamable HTTP 部署选项。该服务由项目作者维护，并非 PubChem 官方服务。
请根据周边应用选择：你需要的是 Python 检索层，还是 MCP 接口？如果选择 MCP，请确认传输方式、身份验证配置、客户端权限，以及客户端是否同时提供资源和工具。不要仅凭文档中列出的部署选项就假定其与客户端兼容。
定义输入、输出和停止规则
即使封装层已经提供结构化输出，也应在应用层定义契约。以下是建议的契约，并非对任一项目原生架构的描述。
**输入：**原始查询、标识符命名空间、解析后选定的 CID、允许检索的属性字段、结果上限、分页策略和请求截止时间。
**输出：**解析状态、候选或选定的 CID、返回值、字段名称、所提供的单位、来源引用、检索时间、缺失数据标记，以及任何错误或截断通知。
应区分缺失值与零，也应区分没有记录与记录中缺少所请求属性。绝不可允许智能体凭记忆补全缺失字段。应由集成层记录检索时间，不要假定上游响应会提供该信息。
MCP 文档介绍了若干有用的分支判断信号，包括 unresolvedIdentifiers、每条记录的 found 标志和截断元数据。应保留这些信息，而不是将所有响应简化成普通文字。设置总调用预算和有限重试次数；检查已有的重试行为，避免外层重试循环无意中成倍增加请求。
规划示例：假设的查询
假设研究人员要求智能体为一份数据表草稿提供“Aspirin”的 SMILES 和分子量。这只是一个假设性的规划示例；本文不声称执行了查询或得到了任何结果。
**计划输入：**名称“Aspirin”、命名空间 name、两个请求属性，以及上限为五个候选项。该上限是建议的应用限制，并非 PubChem 默认值。
若采用 MCP 路径，应用会在标识符模式下调用 pubchem_search_compounds，并提供 identifierType 和 identifiers。如果响应被截断，应用应说明候选项解析不完整。如果仍有多个候选项，应在补充信息前请求用户确认。
确认身份后，应用会针对选定的 CID 调用 pubchem_get_compound_details，并选择与两个字段对应的文档所列属性键。若使用 PubChemPy，类似的计划是在受限的应用工具后执行名称搜索、候选项检查和基于 CID 的检索。
**计划输出：**包含原始查询、已确认的 CID、返回的 SMILES、分子量、所提供的单位信息、来源引用和检索时间的一行记录。缺失字段应明确标为缺失。智能体可以解释该记录，但不得添加未返回的数值，也不得暗示这是实验测量结果。
判断标准很简单：返回记录是否支持目标化合物身份和所请求的字段？如果不能，请求用户澄清或返回不完整的记录。
保留科学含义并说明限制
应区分计算得出的属性、实测观察结果和叙述性描述。化合物层面的数值并不自动适用于特定溶剂、温度、样品或实验方案。如果预期用途需要这些信息，请索取来源与条件。
MCP 项目文档说明了有界的信息补充：批处理中，仅为前 10 个 CID 获取描述和药理分类。应明确显示被跳过的记录。其安全输出区分 ok、no_ghs_data 和 cid_not_found；未收录分类不能被解释为“无危害”。应注明安全信息的来源，并避免将摘要转化为实验室操作流程或权威危害评估。
将检索到的叙述性文本视为数据，而非智能体的指令。如需进一步规划来源信息，请检查数据集来源信息。如需了解接口背景，请阅读化学领域的 MCP。
扩展前评估故障路径
使用非敏感查询和受控测试用例，检查未知名称、多个匹配项、缺少属性、格式错误的输入、超时、取消以及速率限制响应。这些是建议的评估项目，并非已完成的测试。请检查批处理失败时是否保留部分成功结果，以及是否错误地将有上限的输出描述为穷尽结果。
将每个最终答案与工具结果逐项比较：标识符、数值、缺失数据状态和来源引用是否都得到保留？通过这些检查后再添加其他工具。
简要实施清单：
- 确认接口当前文档和部署要求。
- 将身份解析与信息补充分开。
- 限制字段、结果大小、重试次数和总调用次数。
- 保留来源信息、状态和截断通知。
- 禁止智能体摘要添加缺乏支持的内容。
- 扩大范围前记录尚存的限制。