platform-metadata-grounding-get

Salesforce 元数据定位

元数据定位会搜索组织的 Salesforce Catalog，这是一个组织元数据索引，包含名称、标签、描述和配置属性。它会按含义查找元数据，因此，搜索“客户奖励状态”可以找到标记为 Loyalty Tier 的字段。它有三种只读操作：搜索、查询和描述。

结果会排序并设有数量上限。它们绝不会是完整列表，定位也不会返回源代码。

何时不使用定位

• 关于 Salesforce 标准功能或产品行为的问题，且答案不取决于此组织。
• 已知的名称。使用范围限定的 SOQL 检查，因为它结果精确且实时。
• 完整列表、计数，或证明某项内容不存在。使用范围限定的 SOQL 或 sf org list metadata。
• 要编辑或部署的源代码。使用 platform-metadata-retrieve 检索。
• 某项内容的使用位置，或更改后会导致什么问题。定位没有引用数据。
• 本次对话中已返回且之后未发生变化的元数据。

platform-metadata-discovery-get 会为以上每种情况选择合适的工具。

选择服务

两个服务都可访问同一目录并返回相同结果。每个请求使用一个服务，同一次查找绝不要同时使用两个服务。

目前，Setup 中的 Salesforce MCP 显示为 Headless360 (H360) MCP Server。在该服务上，searchMetadata、queryMetadata 和 describeMetadata 是传递给 describe 和 dispatch 的操作 ID，并非工具名称。search_metadata、query_metadata 和 describe_metadata 这些工具仅存在于 Metadata Grounding MCP 中。

顺序	服务	调用方式
1	Metadata Grounding MCP	使用下方的输入调用 search_metadata、query_metadata 或 describe_metadata。
2	Salesforce MCP（当 Metadata Grounding MCP 未连接或持续失败时）	对操作 ID searchMetadata、queryMetadata 或 describeMetadata 调用 describe。不要使用 discover，也不要描述 grounding recipe，因为它太大，无法读取。然后使用 describe 返回的路径并传入相同的输入。对 searchMetadata 使用 dispatch_readonly，并将输入作为查询参数传递。对 queryMetadata 和 describeMetadata 使用 dispatch；这些是只读的 POST 调用，输入应作为 JSON 请求体传递。不要使用其他元数据搜索操作。
两者均未连接		定位不可用。使用 platform-metadata-discovery-get 中的名称和标签回退方案。

调用失败时

情况	处理方式
错误提示 Salesforce Catalog 未启用，或用户缺少 Customize Application 权限	在本次会话剩余时间内，停止在两个服务上使用定位。使用回退方案，并向用户说明原因一次。
任何其他错误或超时	重试一次。如果再次失败，则对此请求改用下一个服务。两个请求均失败后，本次会话剩余时间内改用下一个服务。
工具或服务不存在	从下一个服务开始。

工具缺失、访问错误或 404 都不能证明元数据不存在。

响应格式

调用	Metadata Grounding MCP	Salesforce MCP
搜索	{results, totalCount}	响应正文中包含相同载荷
描述和查询	包装为 {defaultExc: "<json string>", responseCode}。解析 defaultExc 字符串以读取 types、typeDetails 或 records。	响应正文中的载荷，不带包装
错误	{errorCode, message} 数组	响应正文中的相同数组

兼容这两种格式。如果响应包含 defaultExc 字符串，则解析它。否则直接读取载荷。

目录类型名称

类型名称区分大小写，有些名称与 Metadata API 名称不同。

Metadata API 名称	目录类型
CustomObject	SObject（子类型 CustomObject、StandardData）
CustomField	SObjectField（子类型 CustomField、StandardField、CustomPersonAccountField）
GlobalValueSet, StandardValueSet	PicklistValueSet（子类型 Global、Standard、Local）
FlexiPage	Flexipage
CustomTab	Tab
CustomApplication	TabSet
QuickAction	QuickActionDefinition
Queue	子类型为 Queue 的 Group
Role	UserRole

大多数其他类型使用 Metadata API 名称，例如 ApexClass、ApexTrigger、Flow、PermissionSet、PermissionSetGroup、Profile、ValidationRule、RecordType、SharingRule、FieldPermissions、PicklistValue 和 CustomPermission。

只有当所需类型不在上述任一列表中时，才在不带 requests 的情况下调用 describe，并且只读取类型名称。完整响应约有 29K 个字符。只有当你需要某个类型的属性时，才使用 metadataType 调用 describe。

搜索

输入：

• query：必填的自然语言短语。空查询会返回 ILLEGAL_QUERY_PARAMETER_VALUE。
• metadataType：可选的目录类型名称。
• metadataSubType：可选的单个值。必须同时提供 metadataType。
• parentIdentifier：可选，用于在一个对象或权限容器中搜索。
• limit：1 至 100，默认值为 50。建议使用 10 至 20。

如何做好搜索：

1. 尽可能按类型筛选。 对于宽泛的问题，请针对可能的类型（例如 SObject、SObjectField 和 Flow）分别执行几次搜索，而不是执行一次不带筛选的搜索。
2. 在对象内搜索：将返回的标识符作为 parentIdentifier 传入。先搜索 SObject 以获取准确的对象 API 名称，或复用字段结果中的 parentIdentifier，然后原样复制该标识符。切勿传入原始对象 API 名称。此方法可查找与主题相关的字段，但不会返回完整字段列表。
3. 在报告“在组织目录中未找到匹配项”之前，使用同义词或可能的标签再尝试一种表述。
4. 遵循服务的公开策略。 不要根据 API 名称后缀推断可见性或支持情况。结果应与用户请求的领域相关；相关时，必须保留有意公开的 Data Cloud 元数据。
5. 搜索后即停止：当名称、标签和描述已能回答问题时，不要继续查询。搜索没有返回结果时，也不要继续查询。

查询

Query 会返回包含特定类型 properties 的完整记录，例如字段的数据类型、必填标记、长度、公式、默认值、帮助文本和选项集。

以下两者中只能发送一项：

• metadataIdentifiers：1 至 50 个标识符，用于读取记录本身。
• parentIdentifiers：1 至 10 个标识符，用于读取其子记录。

对于选项集值，请使用 parentIdentifiers：先搜索字段的 PicklistValueSet，然后传入该值集的标识符。不要传入对象。这样会返回该对象上的每个字段，数据量非常大（Contact 约为 77KB）。如需完整字段列表，请对 EntityParticle 使用限定范围的 SOQL。

标识符由 :: 分隔的三部分组成：18 个字符的组织 ID、名称和类型。只能使用工具返回的标识符。切勿自行构造、缩短或编辑标识符。

常见模式

是否已经有此字段？ 使用用户提供的词语和对象的 parentIdentifier 搜索 SObjectField。展示最匹配的结果及其 API 名称、标签和描述。

如何配置此字段？ 搜索该字段，然后查询其标识符并读取 properties。

此选项列表有哪些值？ 搜索该字段对应的 PicklistValueSet，然后使用 parentIdentifiers 查询该值集。

谁可以读取或编辑此字段？ 使用字段的 API 名称搜索 FieldPermissions，例如 Contact.Loyalty_Tier__c。每条结果的父项都是一个配置文件或权限集。查询结果以读取读取和编辑标志。结果最多显示 100 条；如需完整列表，请对 FieldPermissions 使用限定范围的 SOQL。

此验证规则执行什么约束？ 搜索 ValidationRule，然后查询该规则以获取公式、错误消息和启用状态。

限制

• Flows： 仅包含标头，也就是流程类型、触发器类型、触发对象和启用状态。不包含元素或逻辑。触发对象不是筛选条件，因此无法通过搜索列出对象上的所有 Flow。
• Apex： 仅包含签名，不包含方法体。托管类会返回空存根。
• 页面和操作： Flexipage 和 QuickActionDefinition 记录不是其对象的子项。使用对象作为 parentIdentifier 搜索无法找到它们。请改用含义进行搜索。
• 目录中不包含： 页面布局、报表、自定义元数据类型和自定义设置。
• 时效性： 部署和其他更改可能需要几分钟才会反映到目录中。对于本次会话中更改的内容，请以部署结果为准，并通过 SOQL 确认；SOQL 可实时获取结果。

依据规范

• 引用工具返回的 API 名称、标签和属性。说明哪些陈述是观察所得，哪些是推断所得。
• 请说“在组织目录中未找到匹配项”。绝不要说元数据不存在。
• 绝不要把结果视为完整列表。
• 绝不要根据查询输出编写或部署文件。查询返回的是属性，而不是源代码。
• 每个标识符都以组织 ID 开头。如果还使用 CLI 或其他工具，请先确认两者指向同一组织，再合并结果。

操作参考

此技能使用的操作——路由和依赖项参考。

操作	用途	状态	调用	依赖项
describe-metadata	读取	—	POST /metadata-grounding/schema	—
search-metadata	读取	—	GET /metadata-grounding/search	—
query-metadata	读取	—	POST /metadata-grounding/query	—