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.

9.8 KB
Raw Blame
import { hasScopes } from '@/lib/api'
import { filterStaffOnlyTools } from '@/lib/staff-only-tools'

// AI observability
import getLLMCosts from './aiObservability/getLLMCosts'
import parserRecipeCreate from './aiObservability/parserRecipeCreate'
import parserRecipeReference from './aiObservability/parserRecipeReference'
// Debug
import debugMcpUiApps from './debug/debugMcpUiApps'
// Experiments (hand-written — CRUD + lifecycle are codegen in generated/experiments.ts)
import experimentGetByFlagKey from './experiments/getByFlagKey'
import getExperimentResults from './experiments/getResults'
// Feature flags
import featureFlagGetDefinitionByKey from './featureFlags/getDefinitionByKey'
// Feedback
import submitFeedback from './feedback/submit'
// Generated tools (from definitions/*.yaml)
import { GENERATED_TOOL_MAP } from './generated'
import explainChart from './insights/explainChart'
import explainChartSave from './insights/explainChartSave'
// Insights
import queryInsight from './insights/query'
import insightTrustCheck from './insights/trustCheck'
// Links (utility — builds canonical app URLs from the frontend's route table)
import generateAppUrl from './links/generate-app-url'
import { mergeToolFactories } from './mergeToolFactories'
// Notebooks (edit + cell tools are hand-written — generated CRUD lives in generated/notebooks.ts)
import notebookAddCell from './notebooks/addCell'
import notebookCreateMarkdown from './notebooks/createMarkdown'
import notebookDeleteCell from './notebooks/deleteCell'
import notebookEdit from './notebooks/edit'
import notebookRunCell from './notebooks/runCell'
import notebookRun from './notebooks/runNotebook'
import notebookRunStatus from './notebooks/runNotebookStatus'
import notebookSetVariables from './notebooks/setVariables'
import notebookUpdateCell from './notebooks/updateCell'
// Organizations
import getOrganizations from './organizations/getOrganizations'
import setActiveOrganization from './organizations/setActive'
// PostHog AI tools
import {
    EXECUTE_SQL_TOOL_NAME,
    executeSql,
    externalDataSourcesDbSchema,
    externalDataSourcesJobs,
    externalDataSourcesPreview,
    externalDataSyncLogs,
    readDataSchema,
} from './posthogAiTools'
// PostHog connections (run this project's tools against a connected project in another org/region)
import { createConnectionCallTool } from './posthogConnections/call'
// Projects
import createEventDefinition from './projects/createEventDefinition'
import getEventDefinition from './projects/getEventDefinition'
import getProjects from './projects/getProjects'
import setActiveProject from './projects/setActive'
import updateEventDefinition from './projects/updateEventDefinition'
import updatePathCleaning from './projects/updatePathCleaning'
import updatePropertyDefinition from './projects/updatePropertyDefinition'
// Skills (deprecation aliases for the llma-skill-* → skill-* rename)
import { SKILL_DEPRECATED_ALIASES } from './skills/deprecatedAliases'
import { tasksArtifactsList, tasksCommentsList, tasksCommentsRetrieve } from './tasksContext'
// Misc
import {
    type ToolFilterOptions,
    getToolsForFeatures as getFilteredToolNames,
    getToolDefinition,
} from './toolDefinitions'
import type { Context, Tool, ToolBase, ZodObjectAny } from './types'
// Workflows (batch — orchestration over existing REST endpoints with a blast-radius guard)
import { workflowsBlastRadius, workflowsRunBatch, workflowsScheduleCreate } from './workflows/batch'
// Workflows (lifecycle — CRUD lives in generated/workflows.ts). workflows-disable is intentionally not
// registered: draft routing is gated on ACTIVE status, so disable→edit→enable lands the edit straight on
// the live row and resumes it, skipping the impact preview and signed confirm token that workflows-publish
// makes unskippable. A tool description telling the agent not to do that isn't enforcement — prompt
// injection reaching the agent would just ignore it. Register this only once edits made while disabled
// stage a draft too, or re-enabling a workflow edited while disabled requires publish confirmation.
// The factory stays in lifecycle.ts for that day.
import { workflowsArchive, workflowsEnable } from './workflows/lifecycle'

// Map of tool names to tool factory functions
export const TOOL_MAP: Record<string, () => ToolBase<ZodObjectAny>> = {
    // Organizations
    'organizations-get': getOrganizations,
    'switch-organization': setActiveOrganization,

    // Projects
    'projects-get': getProjects,
    'switch-project': setActiveProject,
    'event-definition-create': createEventDefinition,
    'event-definition-get': getEventDefinition,
    'event-definition-update': updateEventDefinition,
    'property-definition-update': updatePropertyDefinition,

    // Feature flags (get-definition-by-key is hand-written; get-definition by numeric id is codegen)
    'feature-flag-get-definition-by-key': featureFlagGetDefinitionByKey,

    'path-cleaning-rules-update': updatePathCleaning,

    // Experiments (results and get-by-flag-key are hand-written; CRUD + lifecycle are codegen)
    'experiment-results-get': getExperimentResults,
    'experiment-get-by-flag-key': experimentGetByFlagKey,

    // Insights
    'insight-query': queryInsight,
    'insight-trust-check': insightTrustCheck,
    'explain-chart': explainChart,
    'explain-chart-save': explainChartSave,

    // Links (utility — canonical app URLs so the model never hand-builds/mis-slugs entity links)
    'generate-app-url': generateAppUrl,

    // AI observability
    'get-llm-total-costs-for-project': getLLMCosts,
    'llma-parser-recipe-create': parserRecipeCreate,
    'llma-parser-recipe-reference': parserRecipeReference,

    // Notebooks
    'notebook-edit': notebookEdit,
    'notebooks-add-cell': notebookAddCell,
    'notebooks-create-markdown': notebookCreateMarkdown,
    'notebooks-delete-cell': notebookDeleteCell,
    'notebooks-run': notebookRun,
    'notebooks-run-cell': notebookRunCell,
    'notebooks-run-status': notebookRunStatus,
    'notebooks-set-variables': notebookSetVariables,
    'notebooks-update-cell': notebookUpdateCell,

    // Debug
    'debug-mcp-ui-apps': debugMcpUiApps,

    // Feedback
    'agent-feedback': submitFeedback,

    // Current-task comments. The model never supplies a task id; the host-stamped MCP context does.
    'tasks-artifacts-list': tasksArtifactsList,
    'tasks-comments-list': tasksCommentsList,
    'tasks-comments-retrieve': tasksCommentsRetrieve,

    // PostHog AI tools
    [EXECUTE_SQL_TOOL_NAME]: executeSql,
    'read-data-schema': readDataSchema,

    // Data warehouse (custom handlers for non-standard request shapes)
    'external-data-sources-db-schema': externalDataSourcesDbSchema,
    'external-data-sources-preview-resource': externalDataSourcesPreview,
    'external-data-sources-jobs': externalDataSourcesJobs,
    'external-data-sync-logs': externalDataSyncLogs,

    // Workflows lifecycle (thin wrappers over hog_flows_partial_update so MCP gets
    // an idiomatic enable/disable/archive surface without three new REST endpoints).
    'workflows-enable': workflowsEnable,
    'workflows-archive': workflowsArchive,

    // Workflows batch (hand-rolled: blast-radius sizing + echo-back guard before fan-out,
    // composing the existing user_blast_radius / batch_jobs / schedules endpoints).
    'workflows-blast-radius': workflowsBlastRadius,
    'workflows-run-batch': workflowsRunBatch,
    'workflows-schedule-create': workflowsScheduleCreate,

    // PostHog connections — runs any other tool in this map (or a generated one) against a connected
    // project. The registry is injected rather than imported over there so the two don't form a cycle.
    'posthog-connection-call': () => createConnectionCallTool(resolveToolBase),

    // Skills — deprecated llma-skill-* aliases forwarding to the renamed skill-* tools.
    ...SKILL_DEPRECATED_ALIASES,
}

/** Build one tool by name, from the hand-written and generated registries alike. */
function resolveToolBase(name: string): ToolBase<ZodObjectAny> | undefined {
    return mergeToolFactories({ generated: GENERATED_TOOL_MAP, handwritten: TOOL_MAP })[name]?.()
}

export const getToolsFromContext = async (
    context: Context,
    options?: ToolFilterOptions
): Promise<Tool<ZodObjectAny>[]> => {
    // Check org AI consent to gate tools that use LLMs internally (cached in StateManager)
    const aiConsentGiven = await context.stateManager.getAiConsentGiven()
    const effectiveOptions = aiConsentGiven !== undefined ? { ...options, aiConsentGiven } : options
    const effectiveMap = mergeToolFactories({ generated: GENERATED_TOOL_MAP, handwritten: TOOL_MAP })
    const excludeTools = options?.excludeTools ?? []
    const allowedToolNames = getFilteredToolNames(effectiveOptions).filter((name) => !excludeTools.includes(name))
    const toolBases: ToolBase<ZodObjectAny>[] = []

    for (const toolName of allowedToolNames) {
        const toolFactory = effectiveMap[toolName]
        if (toolFactory) {
            toolBases.push(toolFactory())
        }
    }

    const tools: Tool<ZodObjectAny>[] = toolBases.map((toolBase) => {
        const definition = getToolDefinition(toolBase.name)
        return {
            ...toolBase,
            title: definition.title,
            description: definition.description,
            searchKeywords: definition.search_keywords,
            scopes: definition.required_scopes ?? [],
            annotations: definition.annotations,
        }
    })

    const apiKey = await context.stateManager.getApiKey()
    const scopes = apiKey?.scopes ?? []

    const candidates = tools.filter(
        (tool) =>
            hasScopes(scopes, tool.scopes) &&
            (!scopes.includes('internal_run:read') || !['tasks-run-create', 'tasks-create-and-run'].includes(tool.name))
    )

    return filterStaffOnlyTools(candidates, apiKey ?? { scopes: [] }, () => context.stateManager.getUser())
}