Merge branch 'main' into jh-telemetry

Author: huangjeff5

bin/install_cli

@@ -11,30 +11,37 @@
 :   Introduction
 : ==========================================
 
-# This script allows you to install the latest version of the
-# "genkit" command by running:
+# This script allows you to install the latest version of the "genkit" command by running:
 #
 :   curl -sL cli.genkit.dev | bash
 #
-# If you do not want to use this script, you can manually
-# download the latest "genkit" binary.
+# If you do not want to use this script, you can manually download the latest "genkit" binary.
+#
+# Linux:
 #
 :   curl -Lo ./genkit_bin https://storage.googleapis.com/genkit-assets-cli/prod/linux-x64/latest
 #
+# macOS:
+#
+:   curl -Lo ./genkit_bin https://storage.googleapis.com/genkit-assets-cli/prod/darwin-arm64/latest
+#
+# Windows:
+#
+:   curl -Lo ./genkit_bin.exe https://storage.googleapis.com/genkit-assets-cli/prod/win32-x64/latest.exe
+#
 # Alternatively, you can download a specific version.
 #
-:   curl -Lo ./genkit_bin https://storage.googleapis.com/genkit-assets-cli/prod/linux-x64/v1.15.5/genkit
+:   curl -Lo ./genkit_bin https://storage.googleapis.com/genkit-assets-cli/prod/darwin-arm64/v1.15.5/genkit
 #
 # For Windows append ".exe" to the URL.
 #
-:   curl -Lo ./genkit_bin https://storage.googleapis.com/genkit-assets-cli/prod/win32-x64/v1.15.5/genkit.exe
+:   curl -Lo ./genkit_bin.exe https://storage.googleapis.com/genkit-assets-cli/prod/win32-x64/v1.15.5/genkit.exe
 #
-# Note: On Mac, replace "linux" with "darwin" in the URL.
 # Supported architectures: darwin-x64, darwin-arm64, linux-x64, linux-arm64, win32-x64
 #
 # For full details about installation options for the Genkit CLI
 # please see our documentation.
-#   https://genkit.dev
+#   https://genkit.dev/docs/devtools
 #
 # Please report bugs / issues with this script on GitHub.
 #   https://github.com/firebase/genkit

genkit-tools/cli/context/GENKIT.go.md

@@ -14,51 +14,6 @@ This document provides rules and examples for building with the Genkit API in Go
 
 NOTE: For the sake of brevity, the snippets below use the Google AI plugin, but you should follow the user's preference as mentioned above.
 
-## Core Setup
-
-1.  **Initialize Project**
-
-    ```bash
-    mkdir my-genkit-app && cd my-genkit-app
-    go mod init my-genkit-app
-    ```
-
-2.  **Install Dependencies**
-
-    ```bash
-    go get github.com/firebase/genkit/go/genkit
-    go get github.com/firebase/genkit/go/plugins/googlegenai
-    go get github.com/firebase/genkit/go/ai
-    go get google.golang.org/genai
-    ```
-
-3.  **Install Genkit CLI**
-
-    ```bash
-    curl -sL cli.genkit.dev | bash
-    ```
-
-4.  **Configure Genkit**
-
-    All code should be in a single `main.go` file or properly structured Go package.
-
-    ```go
-    package main
-
-    import (
-    	"context"
-    	"github.com/firebase/genkit/go/genkit"
-    	"github.com/firebase/genkit/go/plugins/googlegenai"
-    )
-
-    func main() {
-    	ctx := context.Background()
-    	g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))
-    	// Your flows and logic here
-    	<-ctx.Done()
-    }
-    ```
-
 ## Best Practices
 
 1.  **Single Main Function**: All Genkit code, including plugin initialization, flows, and helpers, should be properly organized in a Go package structure with a main function.
@@ -216,23 +171,24 @@ func main() {
 
 ## Running and Inspecting Flows
 
-1.  **Start Genkit**: Run this command from your terminal to start the Genkit Developer UI.
+**Start Genkit**: Genkit can be started locally by using the `genkit start` command, along with the process startup command:
 
-    ```bash
-    genkit start -- <command to run your code>
-    ```
+```bash
+genkit start --  <command to run your code>
+```
 
-    For Go applications:
+For e.g.:
 
-    ```bash
-    # Running a Go application directly
-    genkit start -- go run main.go
+```bash
+genkit start -- go run main.go
+```
 
-    # Running a compiled binary
-    genkit start -- ./my-genkit-app
-    ```
+You can can automate starting genkit using the following steps:
 
-    The command should output a URL for the Genkit Dev UI. Direct the user to visit this URL to run and inspect their Genkit app.
+1. Identify the command to start the user's project's (e.g., `go run main.go`)
+2. Use the `start_runtime` tool to start the runtime process. This is required for Genkit to discover flows.
+   - Example: If the project uses `go run main.go`, call `start_runtime` with `{ command: "go", args: ["run", "main.go"] }`.
+3. After starting the runtime, instruct the user to run `genkit start` in their terminal to launch the Developer UI.
 
 ## Suggested Models
 

genkit-tools/cli/context/GENKIT.js.md

@@ -14,42 +14,6 @@ This document provides rules and examples for building with the Genkit API in No
 
 NOTE: For the sake of brevity, the snippets below use the Google AI plugin, but you should follow the user's preference as mentioned above.
 
-## Core Setup
-
-1.  **Initialize Project**
-
-    ```bash
-    mkdir my-genkit-app && cd my-genkit-app
-    npm init -y
-    npm install -D typescript tsx \@types/node
-    ```
-
-2.  **Install Dependencies**
-
-    ```bash
-    npm install genkit \@genkit-ai/google-genai data-urls node-fetch
-    ```
-
-3.  **Install Genkit CLI**
-
-    ```bash
-    npm install -g genkit-cli
-    ```
-
-4.  **Configure Genkit**
-
-    All code should be in a single `src/index.ts` file.
-
-    ```ts
-    // src/index.ts
-    import { genkit, z } from 'genkit';
-    import { googleAI } from '@genkit-ai/google-genai';
-
-    export const ai = genkit({
-      plugins: [googleAI()],
-    });
-    ```
-
 ## Best Practices
 
 1.  **Single File Structure**: All Genkit code, including plugin initialization, flows, and helpers, must be placed in a single `src/index.ts` file. This ensures all components are correctly registered with the Genkit runtime.
@@ -289,29 +253,24 @@ export const videoGenerationFlow = ai.defineFlow(
 
 ## Running and Inspecting Flows
 
-1.  **Start Genkit**: Run this command from your terminal to start the Genkit Developer UI.
+**Start Genkit**: Genkit can be started locally by using the `genkit start` command, along with the process startup command:
 
-    ```bash
-    genkit start --  <command to run your code>
-    ```
-
-    The <command to run your code> will vary based on the project’s setup and
-    the file you want to execute. For e.g.:
+```bash
+genkit start --  <command to run your code>
+```
 
-    ```bash
-    # Running a typical development server
-    genkit start -- npm run dev
+For e.g.:
 
-    # Running a TypeScript file directly
-    genkit start -- npx tsx --watch src/index.ts
+```bash
+genkit start -- npm run dev
+```
 
-    # Running a JavaScript file directly
-    genkit start -- node --watch src/index.js
-    ```
+You can can automate starting genkit using the following steps:
 
-    Analyze the users project and build tools to use the right command for the
-    project. The command should output a URL for the Genkit Dev UI. Direct the
-    user to visit this URL to run and inspect their Genkit app.
+1. Identify the command to start the user's project's (e.g., `npm run dev`)
+2. Use the `start_runtime` tool to start the runtime process. This is required for Genkit to discover flows.
+   - Example: If the project uses `npm run dev`, call `start_runtime` with `{ command: "npm", args: ["run", "dev"] }`.
+3. After starting the runtime, instruct the user to run `genkit start` in their terminal to launch the Developer UI.
 
 ## Suggested Models
 

genkit-tools/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genkit-cli",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "CLI for interacting with the Google Genkit AI framework",
   "license": "Apache-2.0",
   "keywords": [

genkit-tools/cli/src/commands/mcp.ts

@@ -17,7 +17,6 @@
 import { findProjectRoot, forceStderr } from '@genkit-ai/tools-common/utils';
 import { Command } from 'commander';
 import { startMcpServer } from '../mcp/server';
-import { startManager } from '../utils/manager-utils';
 
 interface McpOptions {
   projectRoot?: string;
@@ -29,9 +28,5 @@ export const mcp = new Command('mcp')
   .description('run MCP stdio server (EXPERIMENTAL, subject to change)')
   .action(async (options: McpOptions) => {
     forceStderr();
-    const manager = await startManager(
-      options.projectRoot ?? (await findProjectRoot()),
-      true
-    );
-    await startMcpServer(manager);
+    await startMcpServer(options.projectRoot ?? (await findProjectRoot()));
   });

genkit-tools/cli/src/mcp/README.md

@@ -0,0 +1,30 @@
+## 🚀 Genkit MCP Server: Model Context Protocol Integration
+
+The **Genkit MCP (Model Context Protocol) Server** bridges your Genkit projects with external AI tools and development environments. It exposes Genkit flows and functionalities via the Model Context Protocol, allowing **LLM agents** and **IDEs** to discover, interact with, and monitor your application.
+
+> **Note:** The Genkit MCP server is an experimental feature and may change.
+
+---
+
+### What It Does
+
+The MCP Server enables external tools to:
+
+* **Discover Flows:** List all available Genkit flows, including their input schemas.
+* **Run Flows:** Execute Genkit flows by providing inputs and receiving outputs.
+* **Access Traces:** Retrieve and analyze detailed execution traces for performance insights.
+* **Look up Documentation:** Access Genkit documentation directly.
+
+---
+
+### Available MCP Tools
+
+The following tools allow MCP-aware environments to interact with the Genkit server:
+
+| Tool Name | Description |
+| :--- | :--- |
+| **`get_usage_guide`** | Fetches the Genkit AI framework usage guide (specifiable by language). Intended for AI assistants. |
+| **`lookup_genkit_docs`** | Retrieves Genkit documentation (specifiable by language and files). |
+| **`list_flows`** | Discovers and lists all defined Genkit flows with their input schemas. |
+| **`run_flow`** | Executes a specified Genkit flow, requiring `flowName` and a JSON `input` conforming to the flow's schema. |
+| **`get_trace`** | Retrieves the detailed execution trace for a flow using a `traceId`. |

genkit-tools/cli/src/mcp/flows.ts

@@ -14,13 +14,13 @@
  * limitations under the License.
  */
 
-import { RuntimeManager } from '@genkit-ai/tools-common/manager';
 import { record } from '@genkit-ai/tools-common/utils';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
 import z from 'zod';
 import { McpRunToolEvent } from './analytics.js';
+import { McpRuntimeManager } from './util.js';
 
-export function defineFlowTools(server: McpServer, manager: RuntimeManager) {
+export function defineFlowTools(server: McpServer, manager: McpRuntimeManager) {
   server.registerTool(
     'list_flows',
     {
@@ -30,8 +30,8 @@ export function defineFlowTools(server: McpServer, manager: RuntimeManager) {
     },
     async () => {
       await record(new McpRunToolEvent('list_flows'));
-
-      const actions = await manager.listActions();
+      const runtimeManager = await manager.getManager();
+      const actions = await runtimeManager.listActions();
 
       let flows = '';
       for (const key of Object.keys(actions)) {
@@ -70,7 +70,8 @@ export function defineFlowTools(server: McpServer, manager: RuntimeManager) {
       await record(new McpRunToolEvent('run_flow'));
 
       try {
-        const response = await manager.runAction({
+        const runtimeManager = await manager.getManager();
+        const response = await runtimeManager.runAction({
           key: `/flow/${flowName}`,
           input: input !== undefined ? JSON.parse(input) : undefined,
         });