developing-genkit-tooling

Developing Genkit Tooling

Naming Conventions

Consistency in naming helps users and agents navigate the tooling.

CLI Commands

Use kebab-case with colon separators for subcommands.

• Format: noun:verb or category:action
• Examples: flow:run, eval:run, init
• Arguments: Use camelCase in code (flowName) but standard format in help text (<flowName>).

MCP Tools

Use snake_case for tool names to align with MCP standards.

• Format: verb_noun
• Examples: list_flows, run_flow, list_genkit_docs, read_genkit_docs

CLI Command Architecture

Commands are implemented in cli/src/commands/ using commander.

Runtime Interaction

Most commands require interacting with the user's project runtime. Use the runWithManager utility to handle the lifecycle of the runtime process.

import { runWithManager } from '../utils/manager-utils';
 
// ... command definition ...
.action(async (arg, options) => {
  await runWithManager(await findProjectRoot

Output Formatting

• Logging: Use logger from @genkit-ai/tools-common/utils.
• Machine Readable: Provide options for JSON output or file writing when the command produces data.
• Streaming: If the operation supports streaming (like flow:run), provide a --stream flag and pipe output to stdout.

MCP Tool Architecture

MCP tools in cli/src/mcp/ follow two distinct patterns: Static and Runtime.

Static Tools (e.g., Docs)

These tools do not require a running Genkit project context.

• Registration: defineDocsTool(server: McpServer)
• Dependencies: Only the server instance.
• Use Case: Documentation, usage guides, global configuration.

Runtime Tools (e.g., Flows, Runtime Control)

These tools interact with a specific Genkit project's runtime.

• Registration: defineRuntimeTools(server: McpServer, options: McpToolOptions)
• Dependencies: Requires options containing manager (process manager) and projectRoot.
• Schema: MUST use getCommonSchema(options.explicitProjectRoot, ...) to ensure the tool can accept a projectRoot argument when required (e.g., in multi-project environments).

Error Handling

MCP tools should generally catch errors and return them as content blocks with isError: true rather than throwing exceptions, which ensures the client receives a structured error response.