Skip to content

: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.

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.json
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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_ID
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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)
+ })
+})