PostHog MCP Tools 实现指南：从 YAML 定义到代码生成的完整流水线

PostHog MCP Tools 实现指南从 YAML 定义到代码生成的完整流水线【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthogMCP tools 是 PostHog 中面向 AI Agent 的原子能力——一个个 CRUD 操作和简单动作列出 Feature Flag、按 ID 查询实验、创建问卷、总结会话录制由 Agent 组合成高层工作流。本文以docs/published/handbook/engineering/ai/implementing-mcp-tools.md为主线结合仓库内 MCP 服务源码与真实产品配置系统讲解 PostHog MCP 工具的设计原则、双版本服务策略、YAML 定义体系、OpenAPI 代码生成流水线、SQL-first 的 HogQL 系统表以及测试与校验的最佳实践。读完本文你将掌握在 PostHog 仓库中为一个新产品新增、配置并发布 MCP 工具的完整套路。TL;DR五分钟上手流程PostHog 的 MCP 工具开发遵循脚手架 → 配置 → 生成 → 合并四步走# 1. 用脚手架生成一个所有操作均未启用的起始 YAML pnpm --filterposthog/mcp run scaffold-yaml -- --product your_product \ --output ../../products/your_product/mcp/tools.yaml # 2. 配置 YAML —— 启用工具、添加 scopes、annotations、描述 # 首选放在 products/product/mcp/*.yaml如 actions、cohorts # 3. 对由 PostHog 数据库行支撑的 list/read 工具 # 在 posthog/hogql/database/schema/system.py 添加 HogQL 系统表 # 并在 products/posthog_ai/skills/querying-posthog-data/references/ 添加模型引用 # 4. 生成 handlers 和 schemas hogli build:openapi # 5. 合并到 master —— CI 自动构建并分发工具设计原则原子能力优先MCP 工具应当是基础能力basic capabilities——原子的 CRUD 操作和简单动作由 Agent 将这些原语组合成更高级的工作流。好工具的示例列出 Feature Flags按 ID 获取一个实验创建一份问卷总结一段会话录制坏工具的示例搜索某实验的会话录制——这捆绑了多个关注点。应当拆成四个可组合的工具list experiments列出实验、get experiment获取实验、search session recordings搜索会话录制、summarize sessions总结会话。其背后的推理是Agent 组合简单工具的能力远强于在复杂工具中导航的能力同时简单工具可以在众多工作流中复用。这一原则决定了工具命名与拆分的方向——domain-action形式详见后文YAML 配置。双版本 MCP 服务器v1 与 v2客户端需要具备两大能力MCP 与 skills。MCP 支持已经非常普及但 skills 支持仍处于早期阶段目前主要是编码类 Agent 支持它。为缓解这一差异MCP 服务器通过x-posthog-mcp-version: version_number请求头提供两个版本。Legacy MCPv1面向不支持 skills 的客户端暴露完整的一套 CRUD 工具并附带简单指令list、read、create、update、delete。主要面向 vibe-coding 网页工具类客户端。SQL-first MCPv2v2 指示 Agent 通过统一的HogQL 接口读取数据通常排除 list 和 get 工具从而解锁数据检索、搜索与操作上的灵活性。此外消费者还能获得一个提供 schema 引用与示例模式的 skill从而获得关于 PostHog 数据模型更丰富的上下文。主要面向编码 AgentPostHog Desktop、PostHog AI、Claude Code。对应地YAML 中的mcp_version: 1/2字段用于控制检索类工具在 v2 中的可用性。Claude Web / Desktop 的 exec schema 预算Claude Web 与桌面版会在某个工具的序列化inputSchema达到16,384 字符时静默丢弃该工具因此最终的execinput schema 需要把测试预算控制在该限制之下。实践上只在几乎每次调用都需要的指导内容上使用内联文本包括紧凑的工具域索引其余内容全部归入learn目录Claude Web/桌面指南以及mcp-exec-skills标志之后的 PostHog 与项目 skillsskill 的名称、描述和正文从不进入工具 schemaAgent 通过learn -s query发现它们用learn source:skill [path]读取项目 skill 搜索在排序和限制结果前会应用调用方逐 skill 的读权限受限的 skill 不贡献任何元数据或摘录。搜索端点使用独立的突发与持续预算标准 API 速率480 请求/分钟、4,800 请求/小时。个人 API key 有独立预算OAuth 与浏览器会话按用户共享预算。超出任一预算会在搜索执行前返回 HTTP 429 并附带Retry-After。项目 skill API 默认单页 8,000 字符正文。learn一次调用最多请求 1,000,000 字符覆盖 API 的 1 MB UTF-8 正文限制并在搜索或格式化前拒绝超大或不完整的正文另有独立的 44,000 字符展示预算引导 Agent 对更大的文件改用搜索或按行范围读取。文件读取与限定搜索按行增量扫描搜索在 50 个匹配或展示预算耗尽时停止在可容纳的地方保留两侧各两行上下文。标题大纲在构建时受限超大行范围会以请缩小范围的请求失败。不要为迁就预算而裁剪端点序列化器或生成的工具 schema——它们仍是info与schema的真相来源。Eval runner 的--skill-delivery exec模式会移除捆绑 skills并将无显式交互来源的用例默认指向支持 skilllearn的evalMCP 消费者显式用例来源在两种交付模式下都优先。该 runner 同时把所选交付模式应用于 Python 的 sandbox-provisioning 标志覆盖与 MCP 的标志覆盖。捆绑模式保留原生 skills除非用例显式禁用exec 模式移除它们。对比expected_skill_loaded与skill_loaded_before_tool分数可知一个已完成的 eval 运行即使两项分数都为零也可能报告PASS除非用--fail-under设置分数阈值。捆绑模式 eval 通过 dev/test 进程覆盖显式禁用mcp-exec-skills从而跳过 skill 目录预热与轮询exec 模式 eval 允许 MCP 启动耗时 120 秒覆盖 60 秒预热预算加一次进行中的下载与开发构建捆绑模式则保持 30 秒启动上限。生产环境的 feature-flag 求值不控制该进程生命周期。逐步发布 MCP skill 发现发布mcp-exec-skills前先部署 Django skills API、任务启动器与 MCP 变更。在两个服务使用的 analytics 项目里创建或复用键名与该名称完全一致的布尔 flag初始为 disabled先启用一个窄范围特定用户或组织的条件。缺失的 flag 按关闭求值开发环境的FEATURE_FLAG_OVERRIDES不会启用生产行为。验证步骤确认发布的 skills 归档可加载为已启用用户启动新的 MCP 会话与 sandbox 任务演练learn -s、一次有权限的 skill 读取、一次产品调用检查未启用用户是否保持原有行为plugin与posthog-code消费者无论 flag 如何都被排除在外在扩大发布条件前监控归档校验错误、目录大小、MCP 内存与任务失败率。回滚时只需禁用 flag 并重启会话/任务。这不会恢复已从现有 sandbox 中移除的 skills回滚期间的后台缓存行为见下节。共享 skill 归档缓存每个 MCP 进程在内存中持有解析后的目录。Redis 以SHA-256 键存储不可变的归档字节并以一个 JSON 指针保存当前 SHA、ETag 与最近一次成功的上游校验时间。写入方先存字节再替换指针读取方获取命名 blob 并在使用前校验其哈希。轮询未变化的版本时不会传输归档字节。回滚语义禁用mcp-exec-skills会阻断调用方访问产品与项目 skills但不会卸载生产目录或停止归档轮询。停止后台目录工作必须通过部署变更重启同一部署会重新加载目录。上述 dev/test 覆盖不适用于生产。v2键与早期 split-key 布局相互独立因此滚动部署会启动新缓存而不影响旧进程的数据。失败的写入保持上一代可读缺失 blob 触发完整下载304 刷新会延长被引用 blob 的 TTL并仅在指针仍为当前值时更新指针。旧归档代在 30 天归档 TTL 后过期。context-mill slim manifest 使用同一辅助函数、独立命名空间与 7 天 TTL其资源正文仍按 URI 键控。共享归档每 10 分钟检查一次上游变更。用mcp_skill_archive_last_validated_timestamp_seconds检测校验故障跨进程重启依然有效成功的 304 会推进该时间戳。mcp_skill_catalog_age_seconds则度量自解析以来的时间在归档未变且健康时也会增长。候选告警表达式time() - mcp_skill_archive_last_validated_timestamp_seconds 1800持续 5 分钟值为 0 表示进程尚未观察到一次成功的共享校验。排查时配合mcp_skill_archive_events_total{resulterror}与mcp_skill_catalog_skills。注意该指标不能证明每个进程都已采用最新归档且告警需在监控系统中配置——仅仅暴露指标不会发送通知。SQL-first MCPHogQL 系统表大多数以 MCP 工具暴露的 list/get 端点都应有对应的HogQL 系统表让 Agent 可以在 REST API 工具之外或替代它们通过 SQL 查询 PostHog 数据。以下例外可以接受工具有意代理服务方所有的数据、聚合了不以团队作用域 PostHog 表表示的数据、或返回在 SQL 中重建会很别扭或不安全的精选 API 形态。这类工具应保持窄表面并在 YAML 描述中说明数据来源与形态。对于可能因用户权限或请求作用域而失败的代理端点返回区分明确的 API 可见错误细节Agent 应在真正的授权失败时停下但若响应说明所请求的作用域不可用它们常常能从错误的 project/team 过滤中恢复。系统表在posthog/hogql/database/schema/system.py中定义为PostgresTable实例每个表必须包含team_id列以保证数据隔离。仓库中的真实示例feature_flags: PostgresTable PostgresTable( namefeature_flags, postgres_table_nameposthog_featureflag, access_scopefeature_flag, access_control_creator_id_fieldcreated_by_id, descriptionFeature flags; one row per flag, with its targeting filters and rollout configuration., fields{ id: IntegerDatabaseField(nameid, descriptionFlag id.), team_id: IntegerDatabaseField(nameteam_id), key: StringDatabaseField(namekey, descriptionFlag key used by SDKs to evaluate the flag.), name: StringDatabaseField(namename, descriptionHuman-readable flag name/description.), filters: StringJSONDatabaseField( namefilters, descriptionJSON targeting rules, variants, and release conditions. ), rollout_percentage: IntegerDatabaseField( namerollout_percentage, descriptionTop-level rollout percentage (0-100); detailed rules live in filters., ), created_by_id: IntegerDatabaseField( namecreated_by_id, nullableTrue, descriptionUser who created the flag. ), created_at: DateTimeDatabaseField(namecreated_at, descriptionWhen the flag was created.), _deleted: BooleanDatabaseField(namedeleted, hiddenTrue), deleted: ExpressionField( namedeleted, exprast.Call(nametoInt, args[ast.Field(chain[_deleted])]), description1 if the flag has been deleted, 0 otherwise., ), }, )Agent 使用system.前缀查询这些表SELECT id, key, name FROM system.feature_flags WHERE active 1 LIMIT 10扩充查询示例模型引用文件新增系统表时还需在products/posthog_ai/skills/querying-posthog-data/references/添加模型引用文件命名约定为models-domain.md。现有引用包括models-actions.mdmodels-cohorts.mdmodels-dashboards-insights.mdmodels-data-warehouse.mdmodels-error-tracking.mdmodels-flags-experiments.mdmodels-groups.mdmodels-notebooks.mdmodels-surveys.mdmodels-variables.md仓库当前还扩展出了models-ai-observability-events.md、models-apm-spans.md、models-batch-exports.md、models-logs.md、models-mcp.md、models-metrics.md等更多领域文件均遵循同一约定。每个文件记录表的列、类型、可空性以及值得注意的结构如 JSON 字段。完成后把新引用注册进products/posthog_ai/skills/querying-posthog-data/SKILL.md的Data Schema一节。代码生成流水线流水线将 Django 序列化器经 OpenAPI 转换为 MCP 工具处理器完整执行方式hogli build:openapi流水线各步骤build:openapi-schema Django → OpenAPI JSON (frontend/tmp/openapi.json) │ ▼ build:openapi-types OpenAPI → TypeScript API types (frontend) │ ▼ build:openapi-mcp OpenAPI → Zod schemas for MCP (Orval) │ ▼ build:openapi-mcp-tools YAML definitions Zod schemas → TypeScript tool handlersYAML 定义配置层YAML 定义是配置层存放在products/product/mcp/*.yaml使配置贴近所属产品的代码。回退路径services/mcp/definitions/*.yaml供没有产品目录的功能使用一旦存在产品目录定义必须放在产品目录内。构建流水线会从两个路径发现 YAML 文件产品团队拥有自己的定义并控制哪些操作暴露为 MCP 工具仓库中已有 60 余个产品的tools.yaml如 products/feature_flags/mcp/tools.yaml、products/cohorts/mcp/tools.yaml 等。工作流是脚手架 → 配置 → 生成三步。第 1 步Scaffold脚手架——生成所有操作均禁用的起始 YAML。--product通过端点的x-product归属发现端点——即匹配产品归属等于产品名的端点。products/name/backend/下的 ViewSet 通过模块路径自动归属其他位置如posthog/api/、ee/的 ViewSet 需要extend_schema(extensions{x-product: product})刻意没有基于 URL 的匹配——路径是所有权归属的有损信号会把端点拉进错误产品的工具列表。当产品 API 路由与产品文件夹名使用不同 slug 时如workflows产品配/hog_flows/路由同样需要给 ViewSet 加上extend_schema(extensions{x-product: workflows})以便脚手架发现。pnpm --filterposthog/mcp run scaffold-yaml -- --product your_product # 或直接输出到产品目录 pnpm --filterposthog/mcp run scaffold-yaml -- --product your_product \ --output ../../products/your_product/mcp/tools.yaml从 scaffold-yaml.ts 的源码可确认脚本从frontend/tmp/openapi.json读取 OpenAPI 规范遍历spec.paths中每个 HTTP 方法按规范化后的x-product值匹配产品kebab 与 snake_case 归一化如llm_analytics别名到ai_observability并把operationId中的./_转为-生成工具名。脚本幂等对已有文件重跑只新增发现的操作并移除过时操作手工配置全部保留。第 2 步Configure配置——编辑 YAML启用工具添加 scopes、annotations 与描述。每个 YAML 文件顶层结构由 Zod 校验services/mcp/scripts/yaml-config-schema.ts未知键在构建时被拒绝.strict()以尽早捕获拼写错误。工具命名遵循domain-action约定小写 kebab-case[a-z0-9-]如feature-flags-list、experiments-create、surveys-delete。域domain将相关工具分组动作action描述操作。名称不能以连字符开头或结尾。功能标识符必须是小写 snake_case[a-z0-9_]如error_tracking、feature_flags应与产品文件夹名一致。工具名长度上限 52 字符——因为不同 MCP 客户端对 servertool 名有各自的组合限制客户端限制说明MCP 规范草案1–128 字符[A-Za-z0-9_\-.]建议而非强制Claude Code64 字符工具名前缀mcp____Cursor组合 60 字符server_name tool_name超限工具被静默过滤OpenAI API^[a-zA-Z0-9_-]$64 字符不允许点号服务器名为 posthog7 字符加分隔符后52 字符是安全区间。CI 运行pnpm --filterposthog/mcp lint-tool-names同时强制长度与模式。超限时缩短域前缀或使用更简洁的动作名。完整 YAML 配置骨架顶部结构与单工具字段均以仓库 yaml-config-schema.ts 与 products/feature_flags/mcp/tools.yaml 为据category: Human readable name # 工具注册表中显示的名称 feature: snake_case_name # 产品标识 url_prefix: /path # enrich_url 链接的基础 URL tools: domain-action: # 例如 feature-flags-list、experiments-create operation: your_product_endpoint_list # 必须匹配一个 OpenAPI operationId enabled: true # false 则从生成中排除 # --- enabled 时必填--- scopes: # API scopes - your_product:read annotations: readOnly: true destructive: false idempotent: true # --- 可选--- mcp_version: 2 # create/update/delete 操作或无法通过 SQL 检索时用 2可通过 HogQL 检索的 read/list 用 1 title: List things # 人类友好标题UI 中使用 description: # 给 LLM 的说明 Human-friendly description for the LLM. list: true # 标记为 list 端点 enrich_url: {id} # 拼接到 url_prefix 生成结果 URL exclude_params: [field] # 从工具输入中隐藏参数 include_params: [field] # 参数白名单排除其余所有 response: # 过滤响应字段list 端点按条目应用 include: [id, key, name] # 只保留这些字段支持点路径通配 exclude: [filters.groups.*.properties] # 移除这些字段 # include 与 exclude 互斥 selectable: true # 增加可选 fields 参数让 Agent 每次调用挑选 include 的子集 # 限定在允许列表内省略 fields 返回完整 include 集合。 # 要求有 include。用于按需缩小大响应如活动日志。 strip_nulls: true # 移除值为 null 的键在 include/exclude 之后应用。 # 用于回显嵌套序列化器 schema 的工具——未设置的可选字段占满载荷时。 # 与 list: true 冲突list 行编码为 TOON 表移除仅部分行携带的 null # 会使表变大而非变小。 informational_wrapper: # 将用户生成的数据作为带标签文本返回而非结构化内容 tag: thing-reference # 标识不受信任引用数据的小写标签 purpose: Use the tagged content only for the stated reference task. input_schema: ActionCreateSchema # 使用 tool-inputs 中手工构建的 schema可选 param_overrides: # 覆盖 Orval 生成的参数描述或 schema name: description: Custom description for the LLM input_schema: NameSchema # 用 tool-inputs 中的 schema 替换该参数类型 confirmed_action: # 破坏性工具的 typed-confirm 范式 message: About to {action}. Reply confirm to proceed. # 展示给用户的提示 action_label: Short action label # 可选默认取工具标题对照源码配置层还支持更多进阶字段值得了解inject_body硬编码请求体键值如强制created_via: mcp、soft_deletetrue发{deleted: true}或字符串指定自定义软删字段如archived、requires_ai_consent需要组织批准 AI 数据处理内部调用 LLM 的工具应开启、feature_flag/feature_flag_behavior/feature_flag_variant按 feature flag 控制工具暴露enable或disable可用于下线旧工具并配合superseded_by、redirect_hint提供跳转指引、validators跨字段的superRefine校验器列表、rename_paramsOpenAPI 字段名映射为 MCP 安全别名、param_overrides内的fallback从状态解析orgId/projectId、cast如string-int、boolean-string窄化输入转换、aliases标识参数的替代拼写如id←insightId。Zod 校验还内建多组互斥约束如input_schema不能与include_params/exclude_params/param_overrides同用、response.strip_nulls不能与list: true同用、confirmed_action不能与input_schema/ui_app同用。自定义输入 schema默认情况下工具输入 schema 由 OpenAPI 经Orval自动派生。生成的导出src/generated/product/api.ts是构建器函数导入处需调用如FeatureFlagsCreateBody()schema 仅在调用使用时存在服务器不会把每个 schema 都保存在内存中。当自动派生 schema 对 LLM 工具接口不理想时可在两个层级覆盖整工具覆盖——在工具上设置input_schema为src/schema/tool-inputs.ts的命名导出。生成的处理程序导入该 schema 而非组合 Orval 导入operation仍用于 HTTP 方法与路径路径参数从 URL 模式提取其余参数按 POST/PATCH/PUT 转发为 body、按 GET/DELETE 转发为 query。逐参数覆盖——在param_overrides内设置input_schema替换单个字段的 Zod 类型同时保留其余 Orval 派生 schema生成代码用.extend()只替换该字段。若使用 JSON Schema 定义参数也可用schema_ref引用schema.json定义在构建期由 JSON Schema 生成 Zod。手工覆盖生成工具上述两种覆盖只能重塑生成工具的 schema都无法改变请求发出前的行为validators作为同步superRefine运行不能 await 任何东西、inject_body提供静态值、rename_params只做重命名。当工具必须在写入前读取当前状态时就以生成工具自身名称导出一个手写工具。mergeToolFactories在名称冲突时让手写条目优先因此手写工具会替换生成工具出现的一切位置Hono 目录、CLI、getToolsFromContext与posthog-connection-call。仓库参考实现为services/mcp/src/tools/featureFlags/updateFeatureFlag.ts修复 issue #46501保留分组定向它展开生成工具name、schema 及 codegen 日后新增的字段都会继承只替换 handler再委托回生成 handler 发起请求const generated GENERATED_TOOLS[update-feature-flag]!() return { ...generated, handler: async (context, params) { const existing await context.api.request({ method: GET, path: ... }) return generated.handler(context, { ...params, filters: merge(existing, params.filters) }) }, }该文件在 GET 失败时不加 try/catch——PATCH 未经合并的原始 filters 会静默降级组定向 flag因此 GET 必须先成功。仅在确实需要读-改-写时才使用此手段每个覆盖都是一次必须保持刻意的名称冲突tests/unit/tool-name-validation.test.ts通过固定被遮蔽名称集合来强制这一点。若第二个工具需要同样处理应优先给 YAML 配置增加before_request:钩子而不是再造一个遮蔽。破坏性工具的 typed-confirm 范式对破坏性或安全敏感工具账号变更、密钥撤销、批量删除在 YAML 配置中声明confirmed_action。代码生成会一次发出两个工具name-prepare——校验参数返回带签名的confirmation_hash和给用户的消息name-execute——只接受哈希与用户逐字输入的 confirm然后执行签名动作。模型按顺序调用prepare → 向用户呈现消息 → 等待 confirm → execute。示例tools: org-delete: operation: organizations_destroy enabled: true scopes: [organization_admin:write] annotations: readOnly: false destructive: true idempotent: false confirmed_action: message: About to delete organization {orgId}. Reply confirm to proceed. action_label: Delete organization字段说明message必填是展示给用户的提示文本支持{paramName}占位符运行时从已校验工具参数插值action_label可选是动作的简短人类可读标签如 delete project出现在拒绝消息中默认取工具标题。安全模型prepare 步骤把校验后的参数与当前 project/organization 作用域暂存进 Redis并将其 SHA-256 摘要与用户身份、工具用途、TTL 与一次性 nonce 一起签入 HMAC-SHA256 token。token 恒定且很小——无论参数多大模型只中继对载荷的引用。execute 步骤采用严格的仅确认 schema验证签名、取用即焚暂存载荷焚毁即一次性强制、对照签名摘要检查、重新确认活动作用域与 prepare 时绑定的一致然后才用已验证载荷运行原 handler。动作参数只属于 prepareexecute 时多余的字段被拒绝在一个项目活动时准备的确认不能经switch-project换到另一项目重放。需要清醒认识确认词由模型编写工具参数提供这是指令支撑的工作流守卫而非客户端见证的人类逐字输入证明API scopes 仍是授权边界。约束confirmed_action不能与input_schema组合自定义输入 schema 尚未走 confirmed-action 代码生成路径不能与ui_app组合codegen 尚未用withUiApp包装 execute 工厂运行 MCP Hono 服务器的每个环境都需要MCP_SIGNED_STATE_KEY环境变量≥32 字节缺失或过短会在启动时禁用该范式非confirmed_action工具继续工作-prepare/-execute调用会在请求时失败并给出指向该环境变量的提示。第 3 步Generate生成hogli build:openapi保持定义同步后端 API 端点变化时同步 YAML 定义pnpm --filterposthog/mcp run scaffold-yaml -- --sync-all该操作幂等且非破坏性——只添加新发现的操作enabled: false并移除过时操作所有手工编写的配置都会被保留。CI 将其作为漂移检查运行。完整 YAML schema 参考见services/mcp/definitions/README.md注意YAML 定义本身现存放于产品目录Zod 校验源码见services/mcp/scripts/yaml-config-schema.ts。测试本地运行 MCP 服务器并端到端验证工具的方法见docs/published/handbook/engineering/ai/implementation.md的 How to develop and test 一节。tests/unit/tool-name-validation.test.ts还从单测层面钉住被手写工具遮蔽的名称集合防止有意冲突意外扩散。原生工具组件的结构化数据对posthog_ai消费者工具响应在_meta[com.posthog.mcp/app_data]携带 handler 返回的数据——包括没有 MCP UI 资源的工具直接调用与经exec的调用都适用。该元数据排除内部格式化结果覆盖模型在content中收到格式化文本显式 JSON 输出请求仍独立于组件数据控制该文本。这些响应省略重复的structuredContentMCP 工具 span 对该消费者排除 app-data 元数据但保留模型可见输出。Agent 经 ACP 的rawOutput转发 MCP 结果Claude 与 Codex 适配器在实时更新与历史中保留其元数据。从 ACP 日志重建 Claude 模型转录时Agent 在应用恢复上下文预算前移除 MCP 结果元数据——元数据对组件可用却不进入模型输入。若组件元数据使任务事件超出传输大小限制Agent 移除该元数据并重试大小检查剩余事件可容纳时文本与状态仍到达客户端持续超大的事件被丢弃。原生组件读取 app data、既有structuredContent或直接结果对象从不从结果文本解码 TOON 或 JSON。execute-sql后端在structured_content中随格式化文本返回已执行查询MCP handler 把该查询作为组件元数据转发保留已解析的保存变量定义、connectionId与sendRawQuery。组件经共享 Query 组件在DataVisualizationNode中渲染Query 组件为该可视化获取结果。所有查询组件都要求工具结果带已执行查询——只含文本的旧转录显示通用工具卡片失败调用与缺失或畸形的组件数据同样使用该回退。Web 客户端从 ACP_meta.posthog解析工具身份保留对旧_meta.claudeCode的支持非 exec 的 MCP 工具保留其限定元数据名称避免与内置渲染器冲突。部署顺序上先部署 MCP 与 Agent 传输支持再部署需要结构化组件数据的前端验证实时调用与历史回放并检查下一次模型请求确认 app 元数据确实不存在。序列化器最佳实践描述贯穿整条流水线Django serializer field → OpenAPI spec → Zod schema → MCP tool description产品团队应为序列化器字段提供类型与描述——这些描述正是 Agent 理解工具参数的依据含糊或缺失的描述会导致更差的 Agent 行为。完整后端 → 前端的类型流水线含 viewset、serializer、extend_schema的正确配置参见仓库的类型系统指南审查清单、前后对比示例与详细模式见improving-drf-endpointsskill。要点序列化器字段用help_text——它会成为 OpenAPI 描述。注意help_text中避免祈使语气因为同样的注解会出现在 API 文档中用 YAML 定义中的param_overrides覆盖 Orval 生成的描述适合给特定字段追加祈使式指令具体说明格式、约束与合法取值避免 LLM 无上下文难以理解的术语ListField与JSONField需要显式类型——用ListField(childserializers.CharField())而非裸ListField()JSONField 子类上使用extend_schema_field(PydanticModel)参考posthog/api/alert.py的模式。否则 Orval 会生成z.unknown()手工校验的普通ViewSet方法需要extend_schema(requestYourSerializer)——缺了它drf-spectacular 无法发现请求体生成工具会得到零参数的空 schema。带serializer_class的ModelViewSet自动工作。部分更新设置中的默认值对 PATCH 时合并的 JSON 设置不要把嵌套default值留在共享请求 schema 中——Orval 会把它变成 Zod default于是 MCP 发送调用方省略的值并覆盖已存储的设置。例如评估更新时调用方只改true_is_failure就必须保留allows_na反之亦然。创建默认值应在后端校验中应用并在字段 help text 中描述。根路由 ViewSet挂载在根 URL路径中无team_id/project_id的 ViewSet 会设置param_derived_from_user_current_team并被默认排除在 OpenAPI schema 之外——这意味着对前端类型生成与 MCP 工具脚手架不可见。若你的 viewset 属于此类且要暴露在类上设置force_include_in_api_docs True参考ee/api/billing.py。该标志只控制 schema 收录运行时访问仍来自 viewset 的scope_object、scope_object_read_actions、scope_object_write_actions以及任何按动作的required_scopes或dangerously_get_required_scopes覆盖。只标记你确实想让 PAT、OAuth token 与 MCP 客户端调用的动作。HogQL 查询 schemaWIPfrontend/src/queries/schema/schema-assistant-queries.ts为 AI 助手定义了结构化查询类型trends、funnels、retention 等。这些 schema 以丰富的 JSDoc 注释描述分析查询的形态帮助 Agent 生成正确的 HogQL——schema 越干净、描述越好Agent 在查询生成上的表现就越好。这是进行中的工作目标是让从类型化 schema 生成 HogQL 查询比从自由文本 SQL 更容易schema.json集成进 codegen 流水线已在规划中。支撑 MCP 服务器的 Agent skillsquerying-posthog-data——HogQL 查询模式、系统模型 schema 与可用函数。扩展此 skill 以说明 Agent 应如何使用你通过 HogQL 暴露的表与查询。见products/posthog_ai/skills/querying-posthog-data/SKILL.mdimproving-drf-endpoints——DRF 序列化器与 viewset 的审查清单与模式。编辑或审查端点时使用确保help_text、字段类型与extend_schema注解正确流过类型流水线。见.agents/skills/improving-drf-endpoints/SKILL.md。总结PostHog 的 MCP 工具体系是一个配置驱动、代码生成、双版本并存的完整工程以 YAML 为唯一配置真相源products/product/mcp/*.yaml以 OpenAPI 为中间契约由hogli build:openapi一键生成 Zod schema 与 TypeScript 处理器通过x-posthog-mcp-version头同时服务不支持 skills 的 v1 客户端与支持 skills、走 HogQL 数据面的 v2 客户端用 HogQL 系统表 skill 引用文件为 Agent 提供可检索的数据模型上下文并以confirmed_action签名确认、严格 Zod 校验与 CI 漂移检查守住安全与一致性底线。对希望在 PostHog 中为新产品接入 MCP 的开发者本文给出的流程与源码路径即是完整行动指南。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考