Amplitude MCP 分析设置
为MCP服务器添加埋点，使每个工具调用都成为Amplitude事件，并能够与产品其余部分的Amplitude数据（留存、收入、Web/移动端使用情况）关联起来。
权威SDK参考文档位于包README中：
https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics)
SDK处于预览阶段且演进迅速——务必获取最新的README并按照其说明进行安装、API形状、配置和默认事件的操作。 不要依赖记忆中的代码片段或本技能的摘要作为SDK API细节的依据；如有冲突，以README为准。
共分四个步骤。步骤1–2是必需的，并在README中有文档说明——本技能告诉您应遵循哪些章节以及应验证哪些不变条件。步骤3–4是强烈推荐的，并在此处完整记录，因为它们需要修改SDK之外的内容（服务器的工具模式及产品的Web应用），而SDK README有意未涵盖这些内容。
按顺序执行：步骤1（工具调用）→ 步骤2（身份）→ 步骤3（推理过程）→ 步骤4（UTM，仅当服务器返回链接时）。在确认一切“完成”之前，请先正确设置身份——下游所有内容都依赖于此。
开始之前
确认：
- 这是一个基于
@modelcontextprotocol/sdk构建的 Node/TypeScript MCP服务器。此SDK不支持其他语言/运行时。 - 用户拥有（或可以获得）要发送事件的目标项目的 Amplitude API密钥 。
- 仓库使用的包管理器（pnpm/npm/yarn）——据此调整安装命令。
步骤 1 — 安装SDK并追踪工具调用（必需）
获取README并遵循其 安装 和 快速入门 部分。始终安装最新的发布版本（例如 pnpm add @amplitude/mcp-analytics@latest）——永远不要从记忆中固定版本，也不要复现本技能中的安装命令。
连接完成后需要验证的不变条件（README解释了每一项）：
analytics.instrumentServer(server, ...)在server.connect()之前 运行——顺序很重要。- 每个 工具处理程序都用
analytics.instrumentTool(...)包装。未包装的工具不会被追踪。该包装器与处理程序具有完全相同的形状，并且如果服务器从未绑定，则它是一个空操作直通，因此防御性地包装是安全的。 - 默认事件都带有
[MCP]前缀，因此它们永远不会与产品现有的Amplitude事件冲突。有关当前的事件集和属性，请参阅README的 默认事件 表格（以及仓库中的docs/events.md）。
可选：通过 instrumentTool/instrumentServer 上的 extra 附加稳定的自定义维度（套餐层级、团队、功能开关）——请参阅README的 自定义事件属性 部分。
步骤 2 — 正确设置身份（必需，在将步骤1称为“完成”之前执行此操作）
MCP事件必须携带产品已经通过Web/移动端发送到Amplitude的 相同的 user_id 。跳过此步骤，MCP使用情况将显示为一个无法与产品数据关联的孤立人群——这会使集成的大部分意义失效。
请遵循README的 身份 部分以了解当前API：它提供了服务器级绑定、处理程序内部的 setIdentity() 方法，以及基于请求的 authInfo 声明的可选 resolveIdentity 映射。选择适合服务器认证模型的方案。
需要向用户说明的一个行为：完全匿名、无标识的事件 默认被丢弃（不计算为用户），除非通过 emitAnonymousEvent: true 明确选择加入以进行仅聚合跟踪——在启用此选项之前请询问用户，因为它会改变计数内容。
步骤 3 — 捕获推理过程（推荐）
与人类点击按钮不同，代理可以告诉您 为什么 它调用了某个工具。捕获这个信息可以将数据从“发生了什么”转变为“用户试图做什么”。
SDK端只需一次调用（analytics.setRationale(...)——请参阅README的 推理过程 部分），但SDK本身不会从工具输入中读取推理过程：推理过程如何到达服务器是本技能实现的服务器端约定。 经过实战检验的模式是模式注入——向 每个 工具的输入模式添加一个可选的 rationale 字段。由于参数已在代理读取的模式中进行描述，代理会在无需任何客户端更改的情况下，在所有客户端上主动填写它：
// 添加到每个工具的输入模式（zod示例）：
rationale: z
.string()
.optional()
.describe(
'简要说明您为何调用此工具以及您期望从结果中学到什么。',
),
然后在被检测的处理程序内部读取它并将其传递给SDK：
analytics.instrumentTool(async (args, extra) => {
if (typeof args.rationale === 'string') {
analytics.setRationale(args.rationale);
}
return doWork(args);
}, { name: 'search' });
使该字段为可选项意味着当代理省略它时不会破坏任何功能。它作为保留的 [MCP] Rationale 属性发出（截断为1,000个字符；最后一次写入生效）。值得在每个工具上执行此操作，而不仅仅是示例。
步骤 4 — 为出站链接添加UTM参数（推荐，仅当服务器返回URL时）
此步骤完全在SDK之外——它改变了服务器构建URL的方式，并依赖于产品Web端的分析。SDK README 未 涵盖此内容。
如果任何工具响应包含链接（仪表盘、文档、产品页面），请在链接离开服务器之前添加标签，以便点击归因于MCP/代理流量，而不是显示为直接访问：
function addUtmParams(url: string, clientName?: string): string {
const u = new URL(url);
u.searchParams.append('utm_source', 'mcp');
u.searchParams.append('utm_medium', 'referral');
// 连接的客户端（例如"Claude"、"Cursor"），如果您知道的话：
u.searchParams.append('utm_content', clientName ?? 'unknown');
return u.toString();
}
将工具响应中所有构建URL的路径都通过像这样的一个中央函数——单个未添加标签的链接会破坏该流程的归因效果。
前提条件（明确告知用户）： 这仅在他们的Web分析工具在页面浏览事件（或他们的网站在着陆时触发的任何其他事件）中捕获UTM参数时才有效。Amplitude的Browser SDK 2默认执行此操作——请参阅 追踪营销归因（UTM、引荐来源和点击ID参数开箱即用即可捕获）。如果他们使用自定义的页面浏览追踪器，则需要确认UTM值也落到了这些事件上，否则就没有什么可以将MCP标签点击关联起来了。
相关的Amplitude文档：
- Browser SDK 2 — 追踪营销归因（Web端UTM捕获，此步骤的实现部分）
- 营销分析的会话、渠道和归因（标签流量如何变为渠道分析）
- 自动捕获（页面浏览等）
完成埋点后
一旦事件开始流动，让编码代理指向Amplitude发布的 analyze-mcp-server 技能，以运行意图聚类并展示按意图分类的工具调用错误模式。（如果该项目已安装 mcp-intent-error-analysis 技能，则使用该技能——一旦用户有数据流动并希望进行分析时使用，而不是在此处重复该分析。）
需要标记的常见错误
- 遵循过时的API代码片段，而不是当前的README——请获取最新版本；SDK处于预览阶段且变化迅速。
- 安装固定/较旧的版本，而不是最新版本。
- 在
server.connect()之后调用instrumentServer()——必须在之前调用。 - 包装了某些工具处理程序，但没有包装其他工具——每个工具都需要
instrumentTool。 - 发送的
user_id与Web/移动端使用的user_id不匹配——破坏了可关联性，而这正是集成的全部意义所在。 - 在用户不理解的情况下启用
emitAnonymousEvent: true，这会使聚合计数因无标识流量而膨胀。 - 忘记UTM的前提条件（Web端捕获），并假设仅添加标签就足够了。