: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(mcp): build the cli tool catalog as a library for the hog cli (#125197)
Rafael Audibert5b27519c7bf7
diff --git a/services/mcp/package.json b/services/mcp/package.jsonindex 8a1326efaad8..357f55ba009a 100644--- a/services/mcp/package.json+++ b/services/mcp/package.json@@ -27,6 +27,7 @@"build:hono": "tsx scripts/build-hono.ts","build:cli": "tsx scripts/build-cli.ts","build:cli:release": "tsx scripts/build-cli-release.ts",+ "build:cli:library": "tsx scripts/build-cli-library.ts","test": "vitest","test:integration": "vitest run --config vitest.integration.config.mts","test:live": "vitest run --config vitest.live.config.mts",diff --git a/services/mcp/scripts/build-cli-library.ts b/services/mcp/scripts/build-cli-library.tsnew file mode 100644index 000000000000..3cf2cd99fb47--- /dev/null+++ b/services/mcp/scripts/build-cli-library.ts@@ -0,0 +1,23 @@+import { build } from 'esbuild'+import { resolve } from 'node:path'++import { copyInstructions } from './copy-instructions'+import { cliEsbuildOptions } from './hono-esbuild-config'++// The tool catalog as an ES module the hog CLI compiles in. Same plugins as the posthog-cli bundle.+const outfile = resolve(process.cwd(), 'dist/cli-library.mjs')++copyInstructions()+build({+ ...cliEsbuildOptions({ outfile, sourcemap: false }),+ entryPoints: [resolve(process.cwd(), 'src/cli/library.ts')],+ // The server's request logs would land on the CLI's stderr. Failures reach the caller as results instead.+ drop: ['console'],+})+ .then(() => {+ console.info(`Built the PostHog CLI tool library -> ${outfile}`)+ })+ .catch((err: unknown) => {+ console.error('Build failed:', err)+ process.exit(1)+ })diff --git a/services/mcp/src/api/client.ts b/services/mcp/src/api/client.tsindex c9f318c5f2a9..7623bc0c5859 100644--- a/services/mcp/src/api/client.ts+++ b/services/mcp/src/api/client.ts@@ -827,8 +827,11 @@ export class ApiClient {apiKeys(): Endpoint {return {- current: async (): Promise<Result<ApiRedactedPersonalApiKey>> => {- return this.fetchJson<ApiRedactedPersonalApiKey>(`${this.baseUrl}/api/personal_api_keys/@current`)+ current: async ({ signal }: { signal?: AbortSignal } = {}): Promise<Result<ApiRedactedPersonalApiKey>> => {+ return this.fetchJson<ApiRedactedPersonalApiKey>(+ `${this.baseUrl}/api/personal_api_keys/@current`,+ signal ? { signal } : undefined+ )},}}diff --git a/services/mcp/src/cli/context.ts b/services/mcp/src/cli/context.tsindex ab50c16d4d40..002592a14b56 100644--- a/services/mcp/src/cli/context.ts+++ b/services/mcp/src/cli/context.ts@@ -39,9 +39,25 @@ export async function flushAnalytics(timeoutMs = 2000): Promise<void> {}}-export async function buildCliContext(config: CliConfig): Promise<Context> {+/** Which CLI runs the tools. The default is posthog-cli; the hog CLI passes its own. */+export interface CliIdentity {+ clientName: string+ userAgent: string+ source: string+}++const POSTHOG_CLI_IDENTITY: CliIdentity = {+ clientName: 'posthog-cli',+ userAgent: 'posthog-cli api',+ source: 'posthog_cli',+}++export async function buildCliContext(+ config: CliConfig,+ identity: CliIdentity = POSTHOG_CLI_IDENTITY+): Promise<Context> {const identityKey = cliIdentityKey(config.apiKey)- const fallbackDistinctId = `posthog-cli:${identityKey}`+ const fallbackDistinctId = `${identity.clientName}:${identityKey}`// Set by the Rust wrapper; joins these events to its telemetry for the same run.const cliInvocationId = process.env.POSTHOG_CLI_INVOCATION_IDconst sessionId = randomUUID()@@ -60,10 +76,10 @@ export async function buildCliContext(config: CliConfig): Promise<Context> {const api = new ApiClient({apiToken: config.apiKey ?? '',baseUrl: config.host.replace(/\/+$/, ''),- clientUserAgent: `posthog-cli api`,- mcpClientName: 'posthog-cli',+ clientUserAgent: identity.userAgent,+ mcpClientName: identity.clientName,mcpClientVersion: sanitizeHeaderValue(process.env.POSTHOG_CLI_VERSION),- mcpConsumer: 'posthog-cli',+ mcpConsumer: identity.clientName,onPrivateResponse: () => {privateResponse = true},@@ -94,9 +110,9 @@ export async function buildCliContext(config: CliConfig): Promise<Context> {...(Object.keys(groups).length > 0 ? { groups } : {}),properties: {$ai_product: 'mcp',- $mcp_source: 'posthog_cli',- $mcp_client_name: 'posthog-cli',- $mcp_consumer: 'posthog-cli',+ $mcp_source: identity.source,+ $mcp_client_name: identity.clientName,+ $mcp_consumer: identity.clientName,$mcp_mode: 'cli',$mcp_scope_preset: resolveScopePreset(apiKey?.scopes),$mcp_version: config.version,diff --git a/services/mcp/src/cli/library-types.ts b/services/mcp/src/cli/library-types.tsnew file mode 100644index 000000000000..976e9c5a9659--- /dev/null+++ b/services/mcp/src/cli/library-types.ts@@ -0,0 +1,81 @@+// The contract of the CLI library build (`dist/cli-library.mjs`). This file imports nothing, so a+// consumer such as the hog CLI can type-check against it without compiling the MCP sources.++export interface ApiToolSummary {+ name: string+ title: string+ summary: string+ description: string+ /** The catalog category, such as "Feature flags". */+ group: string+ feature: string+ requiredScopes: string[]+ readOnly: boolean+ destructive: boolean+ idempotent: boolean+ openWorld: boolean+ /** The tool sends data to an AI provider, so it runs only where the organization allows that. */+ requiresAiConsent: boolean+}++export interface ApiConnection {+ apiKey: string+ host: string+ projectId?: string+ organizationId?: string+ /** Names the calling CLI in the user agent and in analytics, for example "hog". */+ clientName: string+ clientVersion: string+}++export interface ApiKeyAccess {+ scopes: string[]+ scopedTeams: number[]+ scopedOrganizations: string[]+}++export type ApiToolValidation = { valid: true; input: Record<string, unknown> } | { valid: false; error: string }++/** Why a key lookup or a tool call failed. `code` is stable, so a caller can branch on it. */+export interface ApiToolError {+ code:+ | 'permission_denied'+ | 'validation_error'+ | 'invalid_input'+ | 'needs_confirmation'+ | 'ai_consent_required'+ | 'rate_limited'+ | 'unreachable'+ | 'api_error'+ | 'tool_error'+ message: string+ status?: number+ /** The scope PostHog named when it refused the request. */+ missingScope?: string+}++export type ApiToolResult<T> = { ok: true; value: T } | { ok: false; error: ApiToolError }++export interface ApiSearchResult {+ names: string[]+ truncated: boolean+}++export interface ApiToolLibrary {+ tools(): ApiToolSummary[]+ search(query: string): Promise<ApiSearchResult>+ /** A summary of the tool's input schema, or of one field when `fieldPath` names it. */+ schema(tool: string, fieldPath?: string): Promise<unknown>+ validate(tool: string, input: Record<string, unknown>): ApiToolValidation+ missingScopes(granted: string[], required: string[]): string[]+ /** `signal` cancels the lookup, so a caller that stops waiting doesn't keep the process alive. */+ keyAccess(connection: ApiConnection, options?: { signal?: AbortSignal }): Promise<ApiToolResult<ApiKeyAccess>>+ /** Runs the tool and returns its JSON result. */+ call(+ tool: string,+ input: Record<string, unknown>,+ connection: ApiConnection,+ confirm: boolean+ ): Promise<ApiToolResult<unknown>>+ flush(): Promise<void>+}diff --git a/services/mcp/src/cli/library.ts b/services/mcp/src/cli/library.tsnew file mode 100644index 000000000000..fe1aa509da5b--- /dev/null+++ b/services/mcp/src/cli/library.ts@@ -0,0 +1,275 @@+// The tool catalog and tool calls, for CLIs that embed them in-process. `scripts/build-cli-library.ts`+// bundles this file. Calls run through the exec tool, so validation, destructive confirmation,+// output formatting and analytics match `posthog-cli api call`.+import { hasScope } from '@/lib/api'+import {+ ExecCommandError,+ MCPToolResultError,+ PostHogApiError,+ PostHogPermissionError,+ PostHogRateLimitError,+ PostHogTransportError,+ PostHogValidationError,+ ToolInputValidationError,+} from '@/lib/errors'+import { createExecTool, formatInputValidationError, repairArgumentNesting } from '@/tools/exec'+import { getToolDefinition } from '@/tools/toolDefinitions'+import type { Context, Tool, ZodObjectAny } from '@/tools/types'++import { buildCliContext, flushAnalytics } from './context'+import type {+ ApiConnection,+ ApiKeyAccess,+ ApiSearchResult,+ ApiToolError,+ ApiToolLibrary,+ ApiToolResult,+ ApiToolSummary,+ ApiToolValidation,+} from './library-types'+import { trackCliToolCall } from './tool-call-properties'+import { getCliTools } from './tools'++const COMMAND_REFERENCE = 'CLI-style command string: search, schema or call.'++function staticExec(tools: Tool<ZodObjectAny>[]): Tool<ZodObjectAny> {+ return createExecTool(tools, undefined, 'PostHog tools', COMMAND_REFERENCE, undefined, undefined, [], {+ requireDestructiveConfirmation: true,+ })+}++async function runExec(exec: Tool<ZodObjectAny>, context: Context | undefined, command: string): Promise<unknown> {+ const output = await exec.handler(context as Context, { command })+ return typeof output === 'string' ? JSON.parse(output) : output+}++function summarize(tool: Tool<ZodObjectAny>): ApiToolSummary {+ const definition = getToolDefinition(tool.name)+ return {+ name: tool.name,+ title: tool.title,+ summary: definition.summary,+ description: tool.description,+ group: definition.category,+ feature: definition.feature,+ requiredScopes: tool.scopes,+ readOnly: tool.annotations.readOnlyHint,+ destructive: tool.annotations.destructiveHint,+ idempotent: tool.annotations.idempotentHint,+ openWorld: tool.annotations.openWorldHint,+ requiresAiConsent: definition.requires_ai_consent === true,+ }+}++// The API answers errors as DRF JSON, so its `detail` reads better than the raw body.+function apiErrorDetail(error: PostHogApiError): string {+ try {+ const body = JSON.parse(error.body) as { detail?: unknown }+ return typeof body.detail === 'string' ? body.detail : error.message+ } catch {+ return error.message+ }+}++const MCP_RESULT_CODES: Record<MCPToolResultError['errorType'], ApiToolError['code']> = {+ validation: 'validation_error',+ permission: 'permission_denied',+ rate_limited: 'rate_limited',+ api_5xx: 'api_error',+ timeout: 'tool_error',+ memory_limit: 'tool_error',+ internal: 'tool_error',+}++function typedError(error: unknown): ApiToolError | undefined {+ if (error instanceof MCPToolResultError) {+ return { code: MCP_RESULT_CODES[error.errorType], message: error.message }+ }+ if (error instanceof PostHogPermissionError) {+ return {+ code: 'permission_denied',+ message: error.message,+ status: 403,+ ...(error.missingScope ? { missingScope: error.missingScope } : {}),+ }+ }+ if (error instanceof PostHogValidationError) {+ return { code: 'validation_error', message: error.message, status: 400 }+ }+ if (error instanceof PostHogRateLimitError) {+ return { code: 'rate_limited', message: error.message, status: 429 }+ }+ if (error instanceof PostHogApiError) {+ return { code: 'api_error', message: apiErrorDetail(error), status: error.status }+ }+ if (error instanceof PostHogTransportError) {+ return { code: 'unreachable', message: error.message }+ }+ if (error instanceof ToolInputValidationError) {+ return { code: 'invalid_input', message: error.message }+ }+ if (error instanceof ExecCommandError) {+ const codes: Partial<Record<ExecCommandError['reason'], ApiToolError['code']>> = {+ needs_confirmation: 'needs_confirmation',+ missing_scope: 'permission_denied',+ tool_not_granted: 'permission_denied',+ }+ return { code: codes[error.reason] ?? 'invalid_input', message: error.message }+ }+ return undefined+}++// Some tool handlers wrap the API failure, so the typed error can sit anywhere in the `cause` chain.+export function toApiToolError(error: unknown): ApiToolError {+ const seen = new Set<unknown>()+ for (+ let current = error;+ current instanceof Error && !seen.has(current);+ current = (current as Error & { cause?: unknown }).cause+ ) {+ seen.add(current)+ const typed = typedError(current)+ if (typed) {+ return typed+ }+ }+ return { code: 'tool_error', message: error instanceof Error ? error.message : String(error) }+}++class Failure extends Error {+ constructor(readonly failure: ApiToolError) {+ super(failure.message)+ }+}++function failure(error: ApiToolError): never {+ throw new Failure(error)+}++async function attempt<T>(work: () => Promise<T>): Promise<ApiToolResult<T>> {+ try {+ return { ok: true, value: await work() }+ } catch (error) {+ return { ok: false, error: error instanceof Failure ? error.failure : toApiToolError(error) }+ }+}++function buildContext(connection: ApiConnection): Promise<Context> {+ return buildCliContext(+ {+ apiKey: connection.apiKey,+ host: connection.host,+ version: 2,+ ...(connection.projectId ? { projectId: connection.projectId } : {}),+ ...(connection.organizationId ? { organizationId: connection.organizationId } : {}),+ },+ {+ clientName: connection.clientName,+ userAgent: `${connection.clientName}/${connection.clientVersion}`,+ source: `${connection.clientName}_cli`,+ }+ )+}++export function createApiToolLibrary(): ApiToolLibrary {+ // The catalog lists every tool. A call only offers the AI consent tools when the organization allows them.+ const tools = getCliTools({ aiConsentGiven: true })+ const byName = new Map(tools.map((tool) => [tool.name, tool]))+ const exec = staticExec(tools)+ const find = (name: string): Tool<ZodObjectAny> => {+ const tool = byName.get(name)+ if (!tool) {+ throw new Error(`Unknown tool: "${name}".`)+ }+ return tool+ }+ // Each context registers a cache that lives as long as the process.+ const contexts = new Map<string, Promise<Context>>()+ const contextFor = (connection: ApiConnection): Promise<Context> => {+ const key = JSON.stringify(connection)+ let context = contexts.get(key)+ if (!context) {+ context = buildContext(connection)+ contexts.set(key, context)+ }+ return context+ }++ return {+ tools: () => tools.map(summarize),++ async search(query: string): Promise<ApiSearchResult> {+ const result = await runExec(exec, undefined, `search ${query}`)+ if (Array.isArray(result)) {+ return { names: result as string[], truncated: false }+ }+ const object = (result ?? {}) as { matches?: string[]; truncated?: boolean }+ return { names: object.matches ?? [], truncated: object.truncated === true }+ },++ async schema(tool: string, fieldPath?: string): Promise<unknown> {+ find(tool)+ return runExec(exec, undefined, `schema ${tool}${fieldPath ? ` ${fieldPath}` : ''}`)+ },++ // The same rewrap and messages as `posthog-cli api call --dry-run`.+ validate(name: string, input: Record<string, unknown>): ApiToolValidation {+ const { schema } = find(name)+ const first = schema.safeParse(input, { reportInput: true })+ const rewrapped = first.success ? undefined : repairArgumentNesting(first.error, input, schema)+ const result = rewrapped ? schema.safeParse(rewrapped, { reportInput: true }) : first+ return result.success+ ? { valid: true, input: result.data as Record<string, unknown> }+ : { valid: false, error: formatInputValidationError(name, result.error, input, schema) }+ },++ missingScopes: (granted, required) => required.filter((scope) => !hasScope(granted, scope)),++ keyAccess: (+ connection: ApiConnection,+ options: { signal?: AbortSignal } = {}+ ): Promise<ApiToolResult<ApiKeyAccess>> =>+ attempt(async () => {+ const context = await contextFor(connection)+ const result = await context.api.apiKeys().current(options)+ if (!result.success) {+ throw result.error+ }+ return {+ scopes: result.data.scopes ?? [],+ scopedTeams: result.data.scoped_teams ?? [],+ scopedOrganizations: result.data.scoped_organizations ?? [],+ }+ }),++ call: (name, input, connection, confirm): Promise<ApiToolResult<unknown>> =>+ attempt(async () => {+ find(name)+ const context = await contextFor(connection)+ const aiConsentGiven = await context.stateManager.getAiConsentGiven()+ if (getToolDefinition(name).requires_ai_consent && !aiConsentGiven) {+ failure({+ code: 'ai_consent_required',+ message: `${name} sends data to an AI provider, and the organization has not allowed that.`,+ })+ }+ const callExec = createExecTool(+ getCliTools({ aiConsentGiven }),+ context,+ 'PostHog tools',+ COMMAND_REFERENCE,+ connection.clientName,+ (toolName, properties) => trackCliToolCall(context, toolName, properties),+ [],+ { requireDestructiveConfirmation: true }+ )+ return runExec(+ callExec,+ context,+ `call --json ${confirm ? '--confirm ' : ''}${name} ${JSON.stringify(input)}`+ )+ }),++ flush: () => flushAnalytics(),+ }+}diff --git a/services/mcp/tests/unit/cli-context.test.ts b/services/mcp/tests/unit/cli-context.test.tsindex 21c18215ea9d..0689680fdab8 100644--- a/services/mcp/tests/unit/cli-context.test.ts+++ b/services/mcp/tests/unit/cli-context.test.ts@@ -60,6 +60,34 @@ describe('CLI context', () => {})+ it.each([+ ['posthog-cli by default', undefined, 'posthog-cli', 'posthog_cli'],+ [+ 'the CLI that passes its identity',+ { clientName: 'hog', userAgent: 'hog/1.0.0', source: 'hog_cli' },+ 'hog',+ 'hog_cli',+ ],+ ])('reports %s as the client in analytics', async (_name, identity, clientName, source) => {+ const context = await buildCliContext(+ { apiKey: 'phx_key', host: 'https://us.posthog.com', version: 2 },+ identity+ )++ await context.trackEvent(AnalyticsEvent.MCP_TOOL_CALL)++ expect(mocks.capture).toHaveBeenCalledWith(+ expect.objectContaining({+ distinctId: expect.stringMatching(new RegExp(`^${clientName}:`)),+ properties: expect.objectContaining({+ $mcp_client_name: clientName,+ $mcp_consumer: clientName,+ $mcp_source: source,+ }),+ })+ )+ })+it('uses an opaque analytics distinct ID for feedback when identity resolution fails', async () => {const apiKey = 'phx_secret-token'const context = await buildCliContext({ apiKey, host: 'https://us.posthog.com', version: 2 })diff --git a/services/mcp/tests/unit/cli-library.test.ts b/services/mcp/tests/unit/cli-library.test.tsnew file mode 100644index 000000000000..731aa9571ba5--- /dev/null+++ b/services/mcp/tests/unit/cli-library.test.ts@@ -0,0 +1,86 @@+import { describe, expect, it } from 'vitest'++import { createApiToolLibrary, toApiToolError } from '@/cli/library'+import {+ ExecCommandError,+ MCPToolResultError,+ PostHogApiError,+ PostHogPermissionError,+ PostHogRateLimitError,+ wrapError,+} from '@/lib/errors'+import { getToolDefinition } from '@/tools/toolDefinitions'++describe('CLI tool library', () => {+ const library = createApiToolLibrary()++ it('describes every tool with its catalog group and required scopes', () => {+ const tools = library.tools()++ expect(tools.length).toBeGreaterThan(0)+ for (const tool of tools) {+ const definition = getToolDefinition(tool.name)+ expect(tool.group).toBe(definition.category)+ expect(tool.requiredScopes).toEqual(definition.required_scopes ?? [])+ expect(tool.requiresAiConsent).toBe(definition.requires_ai_consent === true)+ }+ expect(tools.some((tool) => tool.requiresAiConsent)).toBe(true)+ })++ it.each([+ ['accepts valid input', { limit: 5 }, true],+ ['rejects input of the wrong type, naming the field', { limit: 'five' }, false],+ ])('validation %s', (_name, input, valid) => {+ const result = library.validate('feature-flag-get-all', input)++ expect(result.valid).toBe(valid)+ if (!result.valid) {+ expect(result.error).toContain('limit')+ }+ })++ it('lists the scopes a key is missing for a tool', () => {+ expect(library.missingScopes(['feature_flag:read'], ['feature_flag:read', 'insight:write'])).toEqual([+ 'insight:write',+ ])+ })++ const request = { url: 'https://us.posthog.com/api/x', method: 'GET' }+ it.each([+ [+ 'a refusal keeps the scope PostHog named',+ new PostHogPermissionError({ detail: 'denied', missingScope: 'insight:write', ...request }),+ { code: 'permission_denied', status: 403, missingScope: 'insight:write' },+ ],+ [+ 'a rate limit is not a plain API error',+ new PostHogRateLimitError({ body: '', retryAfterSeconds: 5, ...request }),+ { code: 'rate_limited', status: 429 },+ ],+ [+ 'an API error reads the DRF detail',+ new PostHogApiError({ status: 404, statusText: 'Not Found', body: '{"detail":"Not found."}', ...request }),+ { code: 'api_error', status: 404, message: 'Not found.' },+ ],+ [+ 'a wrapped refusal keeps its scope',+ wrapError(+ 'Failed to get organizations',+ new PostHogPermissionError({ detail: 'denied', missingScope: 'organization:read', ...request })+ ),+ { code: 'permission_denied', missingScope: 'organization:read' },+ ],+ [+ 'a failed backend tool keeps its error type',+ new MCPToolResultError('Too many queries', 'rate_limited'),+ { code: 'rate_limited' },+ ],+ [+ 'a missing confirmation keeps its own code',+ new ExecCommandError('needs --confirm', 'needs_confirmation'),+ { code: 'needs_confirmation' },+ ],+ ])('maps %s', (_name, error, expected) => {+ expect(toApiToolError(error)).toMatchObject(expected)+ })+})