Skip to content

Commit 7bc763c

Browse files
skoob13claude
andcommitted
feat(cli): add api --agent-help printing the MCP exec tool guide
The guide is composed from the same exec-tool templates the MCP server serves (tool blurb, command reference, schema drill-down rules, tool-domain index, query-tool catalog), with posthog:exec invocations rewritten to posthog-cli api syntax so there is a single source of truth. The agents-md steering snippet now tells agents to run it before their first PostHog command so the full interaction guide lands in their context. Also drops the stale versioned-registry params from getCliTools, which master removed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 556c886 commit 7bc763c

7 files changed

Lines changed: 130 additions & 12 deletions

File tree

‎cli/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ Commands require different API scopes. Make sure to set these scopes on your per
6161
`posthog-cli api` exposes PostHog's MCP tool catalog through a shell-friendly interface for coding agents:
6262

6363
```bash
64+
posthog-cli api --agent-help
6465
posthog-cli api search feature-flag
6566
posthog-cli api info feature-flag-get-all
6667
posthog-cli api schema query-trends series
@@ -73,6 +74,8 @@ posthog-cli api agents-md install
7374

7475
Destructive tools require `--confirm` when executed. Use `--dry-run` before mutations.
7576

77+
`posthog-cli api --agent-help` prints the full agent-facing guide — the same exec tool reference the PostHog MCP server serves, rewritten for CLI invocation — so agents can load it into context before interacting with PostHog APIs.
78+
7679
### Agent steering instructions
7780

7881
Install the PostHog CLI steering instructions into the agent instructions file for your project:

‎cli/src/commands.rs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,11 @@ pub enum Commands {
121121
cmd: SymbolSetsSubcommand,
122122
},
123123

124-
#[command(about = "Agent-first PostHog API tools", trailing_var_arg = true)]
124+
#[command(
125+
about = "Agent-first PostHog API tools",
126+
trailing_var_arg = true,
127+
after_help = "Run `posthog-cli api` with no arguments for usage, or `posthog-cli api --agent-help` for the full agent-facing guide."
128+
)]
125129
Api {
126130
#[arg(trailing_var_arg = true, allow_hyphen_values = true)]
127131
args: Vec<String>,

‎services/mcp/src/cli/agent-help.ts‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
import type { QueryToolInfo, ToolInfo } from '@/lib/instructions'
2+
import { type InstructionsContext, InstructionsFormatter } from '@/lib/instructions-formatter'
3+
import { getToolDefinition } from '@/tools/toolDefinitions'
4+
import type { Tool, ZodObjectAny } from '@/tools/types'
5+
6+
import { EXPERIMENTAL_API_ENV } from './experimental'
7+
8+
const AGENT_HELP_HEADER = `# PostHog API guide for agents
9+
10+
\`posthog-cli api\` is the agent-first interface to the PostHog API. It exposes the same tool surface as the PostHog MCP server's \`exec\` tool, so the reference below is the canonical guide for interacting with PostHog. Treat it as instructions to follow, not just documentation.
11+
12+
The command group is experimental: pass \`--experimental\` right after \`api\`, or set \`${EXPERIMENTAL_API_ENV}=1\` in the environment.
13+
14+
On top of the reference below, the CLI adds:
15+
16+
- \`posthog-cli api call --dry-run <tool> '<json>'\` — validate input against the tool schema without executing. Use it before any mutation.
17+
- Destructive tools refuse to run without \`--confirm\`; add it only after verifying the exact target IDs.
18+
- \`posthog-cli api skill list\` and \`posthog-cli api skill install <skill-id>\` — install PostHog agent skills into \`.agents/skills/\`.
19+
- \`posthog-cli api agents-md install [--path AGENTS.md]\` — install the PostHog steering snippet into a repository.`
20+
21+
const EXEC_INVOCATION_PATTERN = /posthog:exec\(\{\s*"command":\s*"((?:\\.|[^"\\])*)"\s*\}\)/g
22+
23+
function commandToCliInvocation(command: string): string {
24+
const braceIndex = command.indexOf('{')
25+
if (braceIndex === -1) {
26+
return `posthog-cli api ${command}`
27+
}
28+
return `posthog-cli api ${command.slice(0, braceIndex).trimEnd()} '${command.slice(braceIndex)}'`
29+
}
30+
31+
/** The MCP templates document the exec surface as \`posthog:exec({ "command": "<cmd>" })\`
32+
* tool calls. The CLI exposes the identical command strings as \`posthog-cli api <cmd>\`,
33+
* so rewriting invocations (instead of forking the templates) keeps one source of truth. */
34+
export function toCliSyntax(text: string): string {
35+
return text
36+
.replace(EXEC_INVOCATION_PATTERN, (_match, command: string) =>
37+
commandToCliInvocation(command.replace(/\\"/g, '"'))
38+
)
39+
.replace('### Using the `posthog` tool', '### Using `posthog-cli api`')
40+
.replace(
41+
'Pass CLI-style commands in the `command` parameter for all PostHog interactions.',
42+
'Pass CLI-style commands as arguments to `posthog-cli api` for all PostHog interactions.'
43+
)
44+
}
45+
46+
/** Build the full agent-facing guide for \`posthog-cli api --agent-help\` from the same
47+
* exec-tool templates the MCP server serves, including the tool-domain index and the
48+
* query-tool catalog derived from the bundled tool registry (no network or auth needed). */
49+
export function buildAgentHelp(tools: Tool<ZodObjectAny>[]): string {
50+
const formatter = new InstructionsFormatter()
51+
const toolInfos: ToolInfo[] = tools.map((tool) => ({
52+
name: tool.name,
53+
category: getToolDefinition(tool.name).category,
54+
}))
55+
const queryTools: QueryToolInfo[] = tools
56+
.filter((tool) => tool.name.startsWith('query-'))
57+
.map((tool) => {
58+
const definition = getToolDefinition(tool.name)
59+
return {
60+
name: tool.name,
61+
title: definition.title,
62+
...(definition.system_prompt_hint ? { systemPromptHint: definition.system_prompt_hint } : {}),
63+
} as QueryToolInfo
64+
})
65+
66+
const ctx: InstructionsContext = { guidelines: '', tools: toolInfos, queryTools }
67+
const sections = [
68+
AGENT_HELP_HEADER,
69+
formatter.buildExecToolDescription(),
70+
formatter.buildExecCommandReference(ctx, { stripEnvContext: false }),
71+
]
72+
return toCliSyntax(sections.join('\n\n'))
73+
}

‎services/mcp/src/cli/agents-md-snippet.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Use `posthog-cli api` for all PostHog-related queries and operations from this r
44

55
The `posthog-cli api` command group is experimental. If it reports that the command group is disabled, rerun commands with `POSTHOG_CLI_EXPERIMENTAL_API=1` in the environment or pass `--experimental` immediately after `api`.
66

7+
Before your first PostHog command in a session, run `posthog-cli api --agent-help` and load its full output into your context. It prints the complete agent guide — command reference, schema drill-down rules, data discovery workflow, and the tool index — for interacting with PostHog APIs. Treat that output as instructions to follow, not just documentation.
8+
79
You must follow this required progressive disclosure workflow for every PostHog task. Do not skip steps, even if you think you already know the right tool or schema.
810

911
1. Start by searching for the tool you need with `posthog-cli api search <term>` or list tools with `posthog-cli api tools`.

‎services/mcp/src/cli/index.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { AnalyticsEvent } from '@/lib/posthog/analytics'
33
import { createExecTool } from '@/tools/exec'
44
import type { Context, Tool, ZodObjectAny } from '@/tools/types'
55

6+
import { buildAgentHelp } from './agent-help'
67
import { installAgentsMdSnippet } from './agents-md'
78
import { takeOption } from './args'
89
import type { CliConfig } from './config'
@@ -31,6 +32,7 @@ function usage(): string {
3132
3233
Usage:
3334
posthog-cli api --experimental <command>
35+
posthog-cli api --agent-help
3436
posthog-cli api tools
3537
posthog-cli api search <regex>
3638
posthog-cli api info [--json] <tool>
@@ -41,7 +43,8 @@ Usage:
4143
posthog-cli api agents-md install [--path AGENTS.md]
4244
4345
Experimental: set ${EXPERIMENTAL_API_ENV}=1 or pass --experimental to enable this command group.
44-
Destructive tools require --confirm when executed. Use --dry-run before mutations.`
46+
Destructive tools require --confirm when executed. Use --dry-run before mutations.
47+
Agents: run \`posthog-cli api --agent-help\` and load the output into context before anything else.`
4548
}
4649

4750
function takeFlag(args: string[], flag: string): boolean {
@@ -64,7 +67,7 @@ function printResult(result: unknown): void {
6467
async function buildExec(): Promise<BuiltExec> {
6568
const config = resolveCliConfig()
6669
const context = await buildCliContext(config)
67-
const tools = getCliTools(config.version)
70+
const tools = getCliTools()
6871
const execTool = createExecTool(
6972
tools,
7073
context,
@@ -182,6 +185,11 @@ async function main(): Promise<void> {
182185
return
183186
}
184187

188+
if (command === 'agent-help' || command === '--agent-help') {
189+
process.stdout.write(`${buildAgentHelp(getCliTools())}\n`)
190+
return
191+
}
192+
185193
requireExperimentalApiEnabled({ flagEnabled: experimental })
186194

187195
switch (command) {

‎services/mcp/src/cli/tools.ts‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,12 @@ function materializeTool(
1717
}
1818
}
1919

20-
export function getCliTools(version: number): Tool<ZodObjectAny>[] {
20+
export function getCliTools(): Tool<ZodObjectAny>[] {
2121
const factories: Record<string, () => ToolBase<ZodObjectAny>> = {
2222
...TOOL_MAP,
2323
...GENERATED_TOOL_MAP,
2424
}
2525
const names = getToolsForFeatures({
26-
version,
2726
aiConsentGiven: true,
2827
})
2928

@@ -34,14 +33,9 @@ export function getCliTools(version: number): Tool<ZodObjectAny>[] {
3433
continue
3534
}
3635

37-
const base = factory()
38-
if (base.mcpVersion !== undefined && base.mcpVersion !== version) {
39-
continue
40-
}
41-
4236
try {
43-
const definition = getToolDefinition(name, version)
44-
tools.push(materializeTool(name, () => base, definition))
37+
const definition = getToolDefinition(name)
38+
tools.push(materializeTool(name, factory, definition))
4539
} catch {
4640
continue
4741
}
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import { describe, expect, it } from 'vitest'
2+
3+
import { buildAgentHelp, toCliSyntax } from '@/cli/agent-help'
4+
import { getCliTools } from '@/cli/tools'
5+
6+
describe('CLI agent help', () => {
7+
it('rewrites exec invocations to CLI syntax', () => {
8+
expect(toCliSyntax('posthog:exec({ "command": "search dashboard" })')).toBe('posthog-cli api search dashboard')
9+
expect(toCliSyntax('posthog:exec({ "command": "tools" })')).toBe('posthog-cli api tools')
10+
})
11+
12+
it('quotes JSON payloads and unescapes embedded quotes', () => {
13+
expect(
14+
toCliSyntax(
15+
'posthog:exec({ "command": "call read-data-schema {\\"query\\": {\\"kind\\": \\"events\\"}}" })'
16+
)
17+
).toBe(`posthog-cli api call read-data-schema '{"query": {"kind": "events"}}'`)
18+
})
19+
20+
it('builds the agent guide from the MCP exec templates', () => {
21+
const help = buildAgentHelp(getCliTools())
22+
23+
expect(help).toContain('posthog-cli api info <tool_name>')
24+
expect(help).toContain('SCHEMA DRILL-DOWN RULE')
25+
expect(help).not.toContain('posthog:exec(')
26+
expect(help).toContain('POSTHOG_CLI_EXPERIMENTAL_API')
27+
// Tool-domain index and query-tool catalog come from the bundled registry.
28+
expect(help).toContain('query-trends')
29+
})
30+
31+
it('does not require credentials to build', () => {
32+
expect(() => buildAgentHelp(getCliTools())).not.toThrow()
33+
})
34+
})

0 commit comments

Comments
 (0)