diff --git a/.github/workflows/update-ref-docs.yaml b/.github/workflows/update-ref-docs.yaml index 5e4303fc..9cbd47b6 100644 --- a/.github/workflows/update-ref-docs.yaml +++ b/.github/workflows/update-ref-docs.yaml @@ -30,6 +30,8 @@ jobs: KAGENT_API_PAGE: docs-site/content/kagent/resources/api-ref.md KMCP_API_PAGE: docs-site/content/kmcp/reference/api-ref.md HELM_PAGE: docs-site/content/kagent/resources/helm.md + KAGENT_CLI_DIR: docs-site/content/kagent/resources/cli + KMCP_CLI_DIR: docs-site/content/kmcp/reference/cli steps: - name: Checkout kagent repository @@ -374,16 +376,49 @@ jobs: echo "Final generated file contents (first 50 lines):" head -50 "$HELM_PAGE" + - name: Build kagent CLI binary + run: | + # kagent is a single-module monorepo rooted at go/, not the repo root. + cd "$GITHUB_WORKSPACE/kagent/go" + go build -o /tmp/kagent-cli ./core/cli/cmd/kagent + /tmp/kagent-cli --help > /dev/null + echo "kagent CLI binary built and smoke-tested successfully" + + - name: Build kmcp CLI binary + run: | + cd "$GITHUB_WORKSPACE/kmcp" + go build -o /tmp/kmcp-cli ./cmd/kmcp + /tmp/kmcp-cli --help > /dev/null + echo "kmcp CLI binary built and smoke-tested successfully" + + - name: Generate kagent CLI reference docs + run: | + cd "$GITHUB_WORKSPACE/website" + mkdir -p "$KAGENT_CLI_DIR" + python3 scripts/generate-cli-docs.py \ + --binary /tmp/kagent-cli \ + --display-name kagent \ + --out-dir "$KAGENT_CLI_DIR" + + - name: Generate kmcp CLI reference docs + run: | + cd "$GITHUB_WORKSPACE/website" + mkdir -p "$KMCP_CLI_DIR" + python3 scripts/generate-cli-docs.py \ + --binary /tmp/kmcp-cli \ + --display-name kmcp \ + --out-dir "$KMCP_CLI_DIR" + - name: Create Pull Request uses: peter-evans/create-pull-request@v6 with: token: ${{ secrets.GITHUB_TOKEN }} path: website - commit-message: "docs: Update kagent and kmcp API reference docs" + commit-message: "docs: Update kagent and kmcp API, Helm, and CLI reference docs" signoff: true - title: "Update kagent and kmcp API reference docs" + title: "Update kagent and kmcp API, Helm, and CLI reference docs" body: | - Automated API and kagent Helm chart documentation update based on the latest commits: + Automated API, kagent Helm chart, and CLI reference documentation update based on the latest commits: - **kagent**: [`${{ env.KAGENT_COMMIT }}`](https://github.com/${{ github.repository_owner }}/kagent/commit/${{ env.KAGENT_COMMIT }}) - **kmcp**: [`${{ env.KMCP_COMMIT }}`](https://github.com/${{ github.repository_owner }}/kmcp/commit/${{ env.KMCP_COMMIT }}) diff --git a/docs-site/content/kagent/resources/cli/_index.md b/docs-site/content/kagent/resources/cli/_index.md index aa2b9e24..6f8ac84b 100644 --- a/docs-site/content/kagent/resources/cli/_index.md +++ b/docs-site/content/kagent/resources/cli/_index.md @@ -6,3 +6,18 @@ weight: 1 Review the kagent CLI commands and learn how to use them effectively. +- [`kagent add-mcp`](kagent-add-mcp/) - Add an MCP server entry to kagent.yaml +- [`kagent bug-report`](kagent-bug-report/) - Generate a bug report +- [`kagent build`](kagent-build/) - Build a Docker images for an agent project +- [`kagent completion`](kagent-completion/) - Generate the autocompletion script for the specified shell +- [`kagent dashboard`](kagent-dashboard/) - Open the kagent dashboard +- [`kagent db`](kagent-db/) - Database operations (migrations, inspection) +- [`kagent deploy`](kagent-deploy/) - Deploy an agent to Kubernetes +- [`kagent get`](kagent-get/) - Get a kagent resource +- [`kagent init`](kagent-init/) - Initialize a new agent project +- [`kagent install`](kagent-install/) - Install kagent +- [`kagent invoke`](kagent-invoke/) - Invoke a kagent agent +- [`kagent mcp`](kagent-mcp/) - MCP (Model Context Protocol) server management +- [`kagent run`](kagent-run/) - Run agent project locally with docker-compose and launch chat interface +- [`kagent uninstall`](kagent-uninstall/) - Uninstall kagent +- [`kagent version`](kagent-version/) - Print the kagent version diff --git a/docs-site/content/kagent/resources/cli/kagent-add-mcp.md b/docs-site/content/kagent/resources/cli/kagent-add-mcp.md index 563e80c2..88c37011 100644 --- a/docs-site/content/kagent/resources/cli/kagent-add-mcp.md +++ b/docs-site/content/kagent/resources/cli/kagent-add-mcp.md @@ -1,57 +1,34 @@ --- title: kagent add-mcp -description: kagent add-mcp command +description: Add an MCP server entry to kagent.yaml. Use flags for non-interactive setup or run without flags to open the wizard. weight: 10 --- -Add an MCP server entry to `kagent.yaml`. +Add an MCP server entry to kagent.yaml. Use flags for non-interactive setup or run without flags to open the wizard. ```bash kagent add-mcp [name] [args...] [flags] ``` -**Arguments:** -- `name` - Name of the MCP server -- `args` - Command arguments (optional) - **Flags:** -- `--arg` - Command argument (repeatable) -- `--build` - Construct image specification (e.g., `docker build`) -- `--command` - Command to run MCP server (e.g., `npx`, `uvx`, `kmcp`) -- `--env` - Environment variable in KEY=VALUE format (repeatable) -- `--header` - HTTP header for remote MCP in KEY=VALUE format (repeatable, supports `${VAR}` for env vars) -- `--image` - Container image (optional; mutually exclusive with `--build`) -- `--project-dir` - Project directory (default: current directory) -- `--remote` - Remote MCP server URL (`http://` or `https://`) +- `--arg strings` - Command argument (repeatable) +- `--build string` - Container build (optional; mutually exclusive with --image) +- `--command string` - Command to run MCP server (e.g., npx, uvx, kmcp, or a binary) +- `--env strings` - Environment variable in KEY=VALUE format (repeatable) +- `--header strings` - HTTP header for remote MCP in KEY=VALUE format (repeatable, supports ${VAR} for env vars) +- `-h, --help` - help for add-mcp +- `--image string` - Container image (optional; mutually exclusive with --build) +- `--project-dir string` - Project directory (default: current directory) +- `--remote string` - Remote MCP server URL (http/https) **Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## About `kagent add-mcp` - -Adds an MCP server entry to your `kagent.yaml` file. Use flags for non-interactive setup or run without flags to open the wizard. - -## Example - -Add a remote MCP server: - -```bash -kagent add-mcp my-mcp-server --remote https://mcp.example.com -``` - -Add an MCP server with a command: - -```bash -kagent add-mcp my-mcp-server --command npx --arg @modelcontextprotocol/server-filesystem -``` - -Add an MCP server with custom environment variables: - -```bash -kagent add-mcp my-mcp-server --command my-server --env API_KEY=secret --env LOG_LEVEL=debug -``` - +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-bug-report.md b/docs-site/content/kagent/resources/cli/kagent-bug-report.md index 700e9287..d374c640 100644 --- a/docs-site/content/kagent/resources/cli/kagent-bug-report.md +++ b/docs-site/content/kagent/resources/cli/kagent-bug-report.md @@ -1,36 +1,26 @@ --- title: kagent bug-report -description: kagent bug-report command -weight: 10 +description: Generate a bug report +weight: 20 --- -Generate a bug report for troubleshooting. +Generate a bug report ```bash kagent bug-report [flags] ``` -**Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## About `kagent bug-report` - -This command generates a comprehensive bug report that includes: -- kagent CLI version -- kagent server version -- Kubernetes cluster information -- Resource status and logs -- Configuration details - -## Example - -Generate a bug report: - -```bash -kagent bug-report -``` +**Flags:** +- `-h, --help` - help for bug-report +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-build.md b/docs-site/content/kagent/resources/cli/kagent-build.md index 4610e231..d002302f 100644 --- a/docs-site/content/kagent/resources/cli/kagent-build.md +++ b/docs-site/content/kagent/resources/cli/kagent-build.md @@ -1,60 +1,43 @@ --- title: kagent build -description: kagent build command -weight: 10 +description: Build Docker images for an agent project created with the init command. +weight: 30 --- -Build a Docker image for an agent project. +Build Docker images for an agent project created with the init command. + +This command will look for a kagent.yaml file in the specified project directory and build Docker images using docker build. The images can optionally be pushed to a registry. + +Image naming: +- If --image is provided, it will be used as the full image specification (e.g., ghcr.io/myorg/my-agent:v1.0.0) +- Otherwise, defaults to localhost:5001/{agentName}:latest where agentName is loaded from kagent.yaml ```bash kagent build [project-directory] [flags] ``` -**Arguments:** -- `project-directory` - The directory containing the agent project with `kagent.yaml` - **Flags:** -- `--image` - Full image specification (e.g., ghcr.io/myorg/my-agent:v1.0.0) -- `--platform` - Target platform for Docker build (e.g., linux/amd64, linux/arm64) +- `-h, --help` - help for build +- `--image string` - Full image specification (e.g., ghcr.io/myorg/my-agent:v1.0.0) +- `--platform string` - Target platform for Docker build (e.g., linux/amd64, linux/arm64) - `--push` - Push the image to the registry **Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## About `kagent build` - -The `kagent build` command builds Docker images for an agent project created with the `init` command. It looks for a `kagent.yaml` file in the specified project directory and builds Docker images using `docker build`. - -**Image naming:** -- If `--image` is provided, it is used as the full image specification (e.g., `ghcr.io/myorg/my-agent:v1.0.0`) -- Otherwise, defaults to `localhost:5001/{agentName}:latest` where `agentName` is loaded from `kagent.yaml` +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output ## Example -Build a Docker image: - ```bash kagent build ./my-agent -``` - -Build and tag a Docker image: - -```bash -kagent build ./my-agent --image ghcr.io/myorg/my-agent:v1.0.0 -``` - -Build and push an image to a registry: - -```bash -kagent build ./my-agent --image ghcr.io/myorg/my-agent:v1.0.0 --push -``` - -Build for a specific platform: - -```bash -kagent build ./my-agent --platform linux/amd64 --image ghcr.io/myorg/my-agent:v1.0.0 + kagent build ./my-agent --image ghcr.io/myorg/my-agent:v1.0.0 + kagent build ./my-agent --image ghcr.io/myorg/my-agent:v1.0.0 --push ``` diff --git a/docs-site/content/kagent/resources/cli/kagent-completion-bash.md b/docs-site/content/kagent/resources/cli/kagent-completion-bash.md new file mode 100644 index 00000000..94a5ed00 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-completion-bash.md @@ -0,0 +1,46 @@ +--- +title: kagent completion bash +description: Generate the autocompletion script for the bash shell. +weight: 50 +--- + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(kagent completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + kagent completion bash > /etc/bash_completion.d/kagent + +#### macOS: + + kagent completion bash > $(brew --prefix)/etc/bash_completion.d/kagent + +You will need to start a new shell for this setup to take effect. + +```bash +kagent completion bash +``` + +**Flags:** +- `-h, --help` - help for bash +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-completion-fish.md b/docs-site/content/kagent/resources/cli/kagent-completion-fish.md new file mode 100644 index 00000000..be3bbf20 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-completion-fish.md @@ -0,0 +1,37 @@ +--- +title: kagent completion fish +description: Generate the autocompletion script for the fish shell. +weight: 60 +--- + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + kagent completion fish | source + +To load completions for every new session, execute once: + + kagent completion fish > ~/.config/fish/completions/kagent.fish + +You will need to start a new shell for this setup to take effect. + +```bash +kagent completion fish [flags] +``` + +**Flags:** +- `-h, --help` - help for fish +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-completion-powershell.md b/docs-site/content/kagent/resources/cli/kagent-completion-powershell.md new file mode 100644 index 00000000..583c2c7b --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-completion-powershell.md @@ -0,0 +1,34 @@ +--- +title: kagent completion powershell +description: Generate the autocompletion script for powershell. +weight: 70 +--- + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + kagent completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + +```bash +kagent completion powershell [flags] +``` + +**Flags:** +- `-h, --help` - help for powershell +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-completion-zsh.md b/docs-site/content/kagent/resources/cli/kagent-completion-zsh.md new file mode 100644 index 00000000..26ad4249 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-completion-zsh.md @@ -0,0 +1,48 @@ +--- +title: kagent completion zsh +description: Generate the autocompletion script for the zsh shell. +weight: 80 +--- + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(kagent completion zsh) + +To load completions for every new session, execute once: + +#### Linux: + + kagent completion zsh > "${fpath[1]}/_kagent" + +#### macOS: + + kagent completion zsh > $(brew --prefix)/share/zsh/site-functions/_kagent + +You will need to start a new shell for this setup to take effect. + +```bash +kagent completion zsh [flags] +``` + +**Flags:** +- `-h, --help` - help for zsh +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-completion.md b/docs-site/content/kagent/resources/cli/kagent-completion.md index d6674520..da5461f0 100644 --- a/docs-site/content/kagent/resources/cli/kagent-completion.md +++ b/docs-site/content/kagent/resources/cli/kagent-completion.md @@ -1,23 +1,33 @@ --- title: kagent completion -description: kagent completion command +description: Generate the autocompletion script for kagent for the specified shell. weight: 40 --- -Generate the autocompletion script for kagent for the specified shell. See each sub-command's help for details on how to use the generated script. +Generate the autocompletion script for kagent for the specified shell. +See each sub-command's help for details on how to use the generated script. ```bash kagent completion [command] ``` -**Global Flags:** -- `--config` - config file -- `--kagent-url` - KAgent URL (default "http://localhost:8083") -- `--timeout` - Timeout (default 5m0s) - **Subcommands:** -- `bash` - Generate the autocompletion script for bash -- `fish` - Generate the autocompletion script for fish -- `powershell` - Generate the autocompletion script for powershell -- `zsh` - Generate the autocompletion script for zsh +- [`kagent completion bash`](../kagent-completion-bash/) - Generate the autocompletion script for bash +- [`kagent completion fish`](../kagent-completion-fish/) - Generate the autocompletion script for fish +- [`kagent completion powershell`](../kagent-completion-powershell/) - Generate the autocompletion script for powershell +- [`kagent completion zsh`](../kagent-completion-zsh/) - Generate the autocompletion script for zsh +**Flags:** +- `-h, --help` - help for completion + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-dashboard.md b/docs-site/content/kagent/resources/cli/kagent-dashboard.md index 0eacf911..ecd1c723 100644 --- a/docs-site/content/kagent/resources/cli/kagent-dashboard.md +++ b/docs-site/content/kagent/resources/cli/kagent-dashboard.md @@ -1,27 +1,26 @@ --- title: kagent dashboard -description: kagent dashboard command -weight: 10 +description: Open the kagent dashboard +weight: 90 --- -Open the kagent dashboard in your default web browser. +Open the kagent dashboard ```bash kagent dashboard [flags] ``` -**Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## Example - -Open the dashboard: - -```bash -kagent dashboard -``` +**Flags:** +- `-h, --help` - help for dashboard +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-db-migrate-down.md b/docs-site/content/kagent/resources/cli/kagent-db-migrate-down.md new file mode 100644 index 00000000..43123fd4 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db-migrate-down.md @@ -0,0 +1,26 @@ +--- +title: kagent db migrate down +description: Roll back the N most-recent applied migrations for the selected source. +weight: 120 +--- + +Roll back the N most-recent applied migrations for the selected source. + +Down migrations can lose data by design — a rolled-back column loses +its contents. Refuses to run while the source's tracking table is +dirty; clear it with 'force' first. + +```bash +kagent db migrate down N [flags] +``` + +**Flags:** +- `-h, --help` - help for down + +**Global Flags:** +- `--db-url string` - PostgreSQL connection URL (defaults to value of POSTGRES_DATABASE_URL env var) +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--source string` - Migration source name for per-source ops (down/goto/force/version); inferred when only one source is registered. Not applicable to up or status — those aggregate across every registered source. diff --git a/docs-site/content/kagent/resources/cli/kagent-db-migrate-force.md b/docs-site/content/kagent/resources/cli/kagent-db-migrate-force.md new file mode 100644 index 00000000..cc59d458 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db-migrate-force.md @@ -0,0 +1,27 @@ +--- +title: kagent db migrate force +description: Used to reconcile the selected source's tracking table after manual +weight: 130 +--- + +Used to reconcile the selected source's tracking table after manual +remediation, e.g. to clear a dirty flag left by a failed migration. +V=0 clears the version record entirely (the "no migrations applied" +state). Any other V must correspond to a shipped migration file in +the selected source — otherwise the tracking row would point at a +version the binary cannot apply or roll back to, wedging the DB. + +```bash +kagent db migrate force V [flags] +``` + +**Flags:** +- `-h, --help` - help for force + +**Global Flags:** +- `--db-url string` - PostgreSQL connection URL (defaults to value of POSTGRES_DATABASE_URL env var) +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--source string` - Migration source name for per-source ops (down/goto/force/version); inferred when only one source is registered. Not applicable to up or status — those aggregate across every registered source. diff --git a/docs-site/content/kagent/resources/cli/kagent-db-migrate-goto.md b/docs-site/content/kagent/resources/cli/kagent-db-migrate-goto.md new file mode 100644 index 00000000..eddf3b4f --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db-migrate-goto.md @@ -0,0 +1,27 @@ +--- +title: kagent db migrate goto +description: Move the selected source's schema to version V (forward or backward). +weight: 140 +--- + +Move the selected source's schema to version V (forward or backward). +V=0 is the special "empty schema" target: every applied migration in +the source is rolled back. + +Refuses to run while the source's tracking table is dirty; clear it +with 'force' first. + +```bash +kagent db migrate goto V [flags] +``` + +**Flags:** +- `-h, --help` - help for goto + +**Global Flags:** +- `--db-url string` - PostgreSQL connection URL (defaults to value of POSTGRES_DATABASE_URL env var) +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--source string` - Migration source name for per-source ops (down/goto/force/version); inferred when only one source is registered. Not applicable to up or status — those aggregate across every registered source. diff --git a/docs-site/content/kagent/resources/cli/kagent-db-migrate-status.md b/docs-site/content/kagent/resources/cli/kagent-db-migrate-status.md new file mode 100644 index 00000000..92762ebc --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db-migrate-status.md @@ -0,0 +1,23 @@ +--- +title: kagent db migrate status +description: Show how many migrations are applied vs pending across all sources +weight: 150 +--- + +Show how many migrations are applied vs pending across all sources + +```bash +kagent db migrate status [flags] +``` + +**Flags:** +- `-h, --help` - help for status +- `--output string` - Output format: "text" (default) or "json" (default "text") + +**Global Flags:** +- `--db-url string` - PostgreSQL connection URL (defaults to value of POSTGRES_DATABASE_URL env var) +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--source string` - Migration source name for per-source ops (down/goto/force/version); inferred when only one source is registered. Not applicable to up or status — those aggregate across every registered source. diff --git a/docs-site/content/kagent/resources/cli/kagent-db-migrate-up.md b/docs-site/content/kagent/resources/cli/kagent-db-migrate-up.md new file mode 100644 index 00000000..082c473b --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db-migrate-up.md @@ -0,0 +1,31 @@ +--- +title: kagent db migrate up +description: Applies pending migrations for every registered source in +weight: 160 +--- + +Applies pending migrations for every registered source in +registration order, through the same orchestrator the server runs at +startup: per-source advisory locking, pre-run version snapshots, and +compensating rollback of earlier sources when a later one fails. + +Refuses to run while any source's tracking table is dirty; clear it +with 'force' first. + +The --source flag is intentionally not applicable to up; pass it only +on the per-source subcommands (down/goto/force). + +```bash +kagent db migrate up [flags] +``` + +**Flags:** +- `-h, --help` - help for up + +**Global Flags:** +- `--db-url string` - PostgreSQL connection URL (defaults to value of POSTGRES_DATABASE_URL env var) +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--source string` - Migration source name for per-source ops (down/goto/force/version); inferred when only one source is registered. Not applicable to up or status — those aggregate across every registered source. diff --git a/docs-site/content/kagent/resources/cli/kagent-db-migrate-version.md b/docs-site/content/kagent/resources/cli/kagent-db-migrate-version.md new file mode 100644 index 00000000..cbf9f376 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db-migrate-version.md @@ -0,0 +1,25 @@ +--- +title: kagent db migrate version +description: Print the highest applied migration version. +weight: 170 +--- + +Print the highest applied migration version. +For a single registered source the value is on one line; multi-source +binaries print one line per source. When multiple sources are +registered, --source filters to a single track. + +```bash +kagent db migrate version [flags] +``` + +**Flags:** +- `-h, --help` - help for version + +**Global Flags:** +- `--db-url string` - PostgreSQL connection URL (defaults to value of POSTGRES_DATABASE_URL env var) +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--source string` - Migration source name for per-source ops (down/goto/force/version); inferred when only one source is registered. Not applicable to up or status — those aggregate across every registered source. diff --git a/docs-site/content/kagent/resources/cli/kagent-db-migrate.md b/docs-site/content/kagent/resources/cli/kagent-db-migrate.md new file mode 100644 index 00000000..8a28e39b --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db-migrate.md @@ -0,0 +1,32 @@ +--- +title: kagent db migrate +description: Apply, roll back, and inspect database migrations independently +weight: 110 +--- + +Apply, roll back, and inspect database migrations independently +of server startup. Reads POSTGRES_DATABASE_URL from the environment when +--db-url is omitted. + +```bash +kagent db migrate [command] +``` + +**Subcommands:** +- [`kagent db migrate down`](../kagent-db-migrate-down/) - Roll back the N most-recent applied migrations for the selected source +- [`kagent db migrate force`](../kagent-db-migrate-force/) - Mark version V as applied without running its SQL +- [`kagent db migrate goto`](../kagent-db-migrate-goto/) - Move the selected source's schema to version V +- [`kagent db migrate status`](../kagent-db-migrate-status/) - Show how many migrations are applied vs pending across all sources +- [`kagent db migrate up`](../kagent-db-migrate-up/) - Apply all pending migrations across every registered source +- [`kagent db migrate version`](../kagent-db-migrate-version/) - Print the highest applied migration version + +**Flags:** +- `--db-url string` - PostgreSQL connection URL (defaults to value of POSTGRES_DATABASE_URL env var) +- `-h, --help` - help for migrate +- `--source string` - Migration source name for per-source ops (down/goto/force/version); inferred when only one source is registered. Not applicable to up or status — those aggregate across every registered source. + +**Global Flags:** +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") diff --git a/docs-site/content/kagent/resources/cli/kagent-db.md b/docs-site/content/kagent/resources/cli/kagent-db.md new file mode 100644 index 00000000..2d06768e --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-db.md @@ -0,0 +1,23 @@ +--- +title: kagent db +description: Database operations (migrations, inspection) +weight: 100 +--- + +Database operations (migrations, inspection) + +```bash +kagent db [command] +``` + +**Subcommands:** +- [`kagent db migrate`](../kagent-db-migrate/) - Apply, roll back, and inspect database migrations + +**Flags:** +- `-h, --help` - help for db + +**Global Flags:** +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") diff --git a/docs-site/content/kagent/resources/cli/kagent-deploy.md b/docs-site/content/kagent/resources/cli/kagent-deploy.md index afb16479..a20bfe49 100644 --- a/docs-site/content/kagent/resources/cli/kagent-deploy.md +++ b/docs-site/content/kagent/resources/cli/kagent-deploy.md @@ -1,76 +1,62 @@ --- title: kagent deploy -description: kagent deploy command -weight: 10 +description: Deploy an agent to Kubernetes. +weight: 180 --- Deploy an agent to Kubernetes. -```bash -kagent deploy [project-directory] [flags] -``` - -**Arguments:** -- `project-directory` - The directory containing the agent project with `kagent.yaml` +This command will read the kagent.yaml file from the specified project directory, +load environment variables from a .env file, and create an Agent CRD with necessary secrets. -**Flags:** -- `--api-key` - API key for the model provider (convenience option to create secret) -- `--api-key-secret` - Name of existing secret containing API key (recommended) -- `--dry-run` - Output YAML manifests without applying them to the cluster -- `--image, -i` - Image to use (defaults to `localhost:5001/{agentName}:latest`) -- `--namespace` - Kubernetes namespace to deploy to -- `--platform` - Target platform for Docker build (e.g., linux/amd64, linux/arm64) - -**Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output +The command will: +1. Load the agent configuration from kagent.yaml +2. Load environment variables from a .env file (including the model provider API key) +3. Create Kubernetes secrets for environment variables and API keys +4. Create an Agent CRD with the appropriate configuration -## About `kagent deploy` +API Key Requirements: + The .env file MUST contain the API key for your model provider: + - Anthropic: ANTHROPIC_API_KEY=your-key-here + - OpenAI: OPENAI_API_KEY=your-key-here + - Gemini: GOOGLE_API_KEY=your-key-here -The `kagent deploy` command deploys an agent to Kubernetes by performing the following steps: +Environment Variables: + --env-file: REQUIRED. Path to a .env file containing environment variables (including API keys). + Variables will be stored in a Kubernetes secret and mounted as environment variables. -1. Loads the agent configuration from `kagent.yaml` -2. Either creates a new secret with the provided API key or verifies an existing secret -3. Creates an `Agent` Custom Resource Definition (CRD) with the appropriate configuration - -**API Key Options:** -- `--api-key`: Convenience option to create a new secret with the provided API key -- `--api-key-secret`: Recommended way to reference an existing secret by name - -**Dry-Run Mode:** -Use the `--dry-run` flag to output YAML manifests without applying them to the cluster. This is useful for previewing changes or for use with GitOps workflows. - -## Example - -Deploy using an existing secret: +Dry-Run Mode: + --dry-run: Output YAML manifests without applying them to the cluster. This is useful + for previewing changes or for use with GitOps workflows. ```bash -kagent deploy ./my-agent --api-key-secret "my-existing-secret" -``` - -Deploy and create a new secret: - -```bash -kagent deploy ./my-agent --api-key "your-api-key-here" --image "myregistry/myagent:v1.0" -``` - -Deploy to a specific namespace: - -```bash -kagent deploy ./my-agent --api-key-secret "my-secret" --namespace "my-namespace" +kagent deploy [project-directory] [flags] ``` -Generate manifests without deploying: +**Flags:** +- `--dry-run` - Output YAML manifests without applying them to the cluster +- `--env-file string` - Path to .env file containing environment variables (including API keys) +- `-h, --help` - help for deploy +- `-i, --image string` - Image to use (defaults to localhost:5001/{agentName}:latest) +- `--namespace string` - Kubernetes namespace to deploy to (default "kagent") +- `--platform string` - Target platform for Docker build (e.g., linux/amd64, linux/arm64) -```bash -kagent deploy ./my-agent --api-key "your-api-key" --dry-run > manifests.yaml -``` +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output -Deploy with a specific platform for the Docker build: +## Example ```bash -kagent deploy ./my-agent --env-file .env --platform linux/amd64 +kagent deploy ./my-agent --env-file .env + kagent deploy ./my-agent --env-file .env --image "myregistry/myagent:v1.0" + kagent deploy ./my-agent --env-file .env --namespace "my-namespace" + kagent deploy ./my-agent --env-file .env --dry-run > manifests.yaml ``` - diff --git a/docs-site/content/kagent/resources/cli/kagent-get-agent.md b/docs-site/content/kagent/resources/cli/kagent-get-agent.md new file mode 100644 index 00000000..3d92624f --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-get-agent.md @@ -0,0 +1,26 @@ +--- +title: kagent get agent +description: Get an agent by name or list all agents +weight: 200 +--- + +Get an agent by name or list all agents + +```bash +kagent get agent [agent_name] [flags] +``` + +**Flags:** +- `-h, --help` - help for agent + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-get-session.md b/docs-site/content/kagent/resources/cli/kagent-get-session.md new file mode 100644 index 00000000..09ea38f1 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-get-session.md @@ -0,0 +1,26 @@ +--- +title: kagent get session +description: Get a session by ID or list all sessions +weight: 210 +--- + +Get a session by ID or list all sessions + +```bash +kagent get session [session_id] [flags] +``` + +**Flags:** +- `-h, --help` - help for session + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-get-tool.md b/docs-site/content/kagent/resources/cli/kagent-get-tool.md new file mode 100644 index 00000000..962eb04b --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-get-tool.md @@ -0,0 +1,26 @@ +--- +title: kagent get tool +description: List all available tools +weight: 220 +--- + +List all available tools + +```bash +kagent get tool [flags] +``` + +**Flags:** +- `-h, --help` - help for tool + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-get.md b/docs-site/content/kagent/resources/cli/kagent-get.md index ee3c9d53..0978cef6 100644 --- a/docs-site/content/kagent/resources/cli/kagent-get.md +++ b/docs-site/content/kagent/resources/cli/kagent-get.md @@ -1,56 +1,32 @@ --- title: kagent get -description: kagent get command -weight: 10 +description: Get a kagent resource +weight: 190 --- -Get kagent resources. +Get a kagent resource ```bash -kagent get [resource-type] [resource-name] [flags] +kagent get [flags] +kagent get [command] ``` **Subcommands:** -- `agent [agent_name]` - Get an agent by name or list all agents -- `session [session_id]` - Get a session by ID or list all sessions -- `tool` - List all available tools +- [`kagent get agent`](../kagent-get-agent/) - Get an agent or list all agents +- [`kagent get session`](../kagent-get-session/) - Get a session or list all sessions +- [`kagent get tool`](../kagent-get-tool/) - Get tools -**Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## Example - -List all agents: - -```bash -kagent get agent -``` - -Get a specific agent: - -```bash -kagent get agent k8s-agent -``` - -List all sessions: - -```bash -kagent get session -``` - -Get a specific session: - -```bash -kagent get session abc123 -``` - -List all tools: - -```bash -kagent get tool -``` +**Flags:** +- `-h, --help` - help for get +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-help.md b/docs-site/content/kagent/resources/cli/kagent-help.md deleted file mode 100644 index 43673a48..00000000 --- a/docs-site/content/kagent/resources/cli/kagent-help.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: kagent help -description: kagent help command -weight: 150 ---- - -Help provides help for any command in the `kagent` CLI. - -```bash -kagent help [command] [flags] -``` - -**Global Flags:** -- `--config` - config file -- `--kagent-url` - KAgent URL (default "http://localhost:8083") -- `--timeout` - Timeout (default 5m0s) - diff --git a/docs-site/content/kagent/resources/cli/kagent-init.md b/docs-site/content/kagent/resources/cli/kagent-init.md index ea12cadd..658e5631 100644 --- a/docs-site/content/kagent/resources/cli/kagent-init.md +++ b/docs-site/content/kagent/resources/cli/kagent-init.md @@ -1,62 +1,43 @@ --- title: kagent init -description: kagent init command -weight: 10 +description: Initialize a new agent project using the specified framework and language. +weight: 230 --- -Initialize a new agent project with the specified framework and language. +Initialize a new agent project using the specified framework and language. + +You can customize the root agent instructions using the --instruction-file flag. +You can select a specific model using --model-provider and --model-name flags. +If no custom instruction file is provided, a default dice-rolling instruction will be used. +If no model is specified, the agent will need to be configured later. ```bash kagent init [framework] [language] [agent-name] [flags] ``` -**Arguments:** -- `framework` - The framework to use (currently supports `adk`) -- `language` - The programming language to use (supports `python`) -- `agent-name` - The name of the agent project - **Flags:** -- `--description` - Description for the agent -- `--instruction-file` - Path to file containing custom instructions for the root agent -- `--model-name` - Model name (e.g., gpt-4, claude-3-5-sonnet, gemini-2.0-flash) (default: "gemini-2.0-flash") -- `--model-provider` - Model provider (OpenAI, Anthropic, Gemini) (default: "Gemini") +- `--description string` - Description for the agent +- `-h, --help` - help for init +- `--instruction-file string` - Path to file containing custom instructions for the root agent +- `--model-name string` - Model name (e.g., gpt-4, claude-3-5-sonnet, gemini-2.5-flash) (default "gemini-2.5-flash") +- `--model-provider string` - Model provider (OpenAI, Anthropic, Gemini) (default "Gemini") **Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## About `kagent init` - -The `kagent init` command creates a bootstrap agent project. Select a specific model using the `--model-provider` and `--model-name` flags. You can also customize the root agent instructions by using the `--instruction-file` flag. - -If no custom instruction file is provided, a default dice-rolling instruction is used. If no model is specified, the agent can be configured later. - -Currently supported model providers are the models that are supported in the models configuration: -- OpenAI -- Anthropic -- AzureOpenAI -- Gemini +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output ## Example -Create a new agent project: - ```bash kagent init adk python dice + kagent init adk python dice --instruction-file instructions.md + kagent init adk python dice --model-provider Gemini --model-name gemini-2.5-flash ``` - -Create a new agent project with custom instructions: - -```bash -kagent init adk python dice --instruction-file instructions.md -``` - -Create a new agent project with a specific model: - -```bash -kagent init adk python dice --model-provider Gemini --model-name gemini-2.0-flash -``` - diff --git a/docs-site/content/kagent/resources/cli/kagent-install.md b/docs-site/content/kagent/resources/cli/kagent-install.md index 4f724ade..c306559d 100644 --- a/docs-site/content/kagent/resources/cli/kagent-install.md +++ b/docs-site/content/kagent/resources/cli/kagent-install.md @@ -1,42 +1,27 @@ --- title: kagent install -description: kagent install command -weight: 10 +description: Install kagent +weight: 240 --- -Install kagent in a Kubernetes cluster. +Install kagent ```bash kagent install [flags] ``` **Flags:** -- `--profile` - Installation profile (minimal|demo) +- `-h, --help` - help for install +- `--profile string` - Installation profile (minimal|demo) **Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## Example - -Install kagent with the default profile: - -```bash -kagent install -``` - -Install kagent with the minimal profile: - -```bash -kagent install --profile minimal -``` - -Install kagent with the demo profile: - -```bash -kagent install --profile demo -``` - +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-invoke.md b/docs-site/content/kagent/resources/cli/kagent-invoke.md index 19d70175..6fcbaf95 100644 --- a/docs-site/content/kagent/resources/cli/kagent-invoke.md +++ b/docs-site/content/kagent/resources/cli/kagent-invoke.md @@ -1,47 +1,38 @@ --- title: kagent invoke -description: kagent invoke command -weight: 10 +description: Invoke a kagent agent +weight: 250 --- -Invoke a kagent agent to perform a task. +Invoke a kagent agent ```bash kagent invoke [flags] ``` **Flags:** -- `--agent, -a` - Agent to invoke -- `--file, -f` - File to read the task from -- `--session, -s` - Session -- `--stream, -S` - Stream the response -- `--task, -t` - Task to perform -- `--url-override, -u` - URL override +- `-a, --agent string` - Agent +- `-f, --file string` - File to read the task from +- `-h, --help` - help for invoke +- `-s, --session string` - Session +- `-S, --stream` - Stream the response +- `-t, --task string` - Task +- `--token string` - Bearer token to include in A2A requests (for API key passthrough) **Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output ## Example -Invoke an agent with a task: - ```bash kagent invoke --agent "k8s-agent" --task "Get all the pods in the kagent namespace" ``` - -Invoke with streaming output: - -```bash -kagent invoke --agent "k8s-agent" --task "Get all the pods" --stream -``` - -Invoke from a task file: - -```bash -kagent invoke --agent "k8s-agent" --file task.txt -``` - diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-add-tool.md b/docs-site/content/kagent/resources/cli/kagent-mcp-add-tool.md new file mode 100644 index 00000000..f43074fd --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-add-tool.md @@ -0,0 +1,44 @@ +--- +title: kagent mcp add-tool +description: Generate a new MCP tool that will be automatically loaded by the server. +weight: 270 +--- + +Generate a new MCP tool that will be automatically loaded by the server. + +This command creates a new tool file in src/tools/ with a generic template. +The tool will be automatically discovered and loaded when the server starts. + +Each tool is a Python file containing a function decorated with @mcp.tool(). +The function should use the @mcp.tool() decorator from FastMCP. + +```bash +kagent mcp add-tool [tool-name] [flags] +``` + +**Flags:** +- `-d, --description string` - Tool description +- `-f, --force` - Overwrite existing tool file +- `-h, --help` - help for add-tool +- `-i, --interactive` - Interactive tool creation +- `--project-dir string` - Project directory (default: current directory) + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output + +## Example + +```bash +kagent mcp add-tool weather + kagent mcp add-tool database --description "Database operations tool" + kagent mcp add-tool weather --force # Overwrite existing tool +``` diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-build.md b/docs-site/content/kagent/resources/cli/kagent-mcp-build.md new file mode 100644 index 00000000..e2699428 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-build.md @@ -0,0 +1,42 @@ +--- +title: kagent mcp build +description: Build an MCP server from the current project. +weight: 280 +--- + +Build an MCP server from the current project. + +This command will detect the project type and build the appropriate +MCP server Docker image. + +```bash +kagent mcp build [flags] +``` + +**Flags:** +- `-h, --help` - help for build +- `--kind-load` - Load image into kind cluster (requires kind) +- `--kind-load-cluster string` - Name of the kind cluster to load image into (default: current cluster) +- `--platform string` - Target platform (e.g., linux/amd64,linux/arm64) +- `-d, --project-dir string` - Build directory (default: current directory) +- `--push` - Push Docker image to registry +- `-t, --tag string` - Docker image tag (alias for --output) + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output + +## Example + +```bash +kagent mcp build # Build Docker image from current directory + kagent mcp build --project-dir ./my-project # Build Docker image from specific directory +``` diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-deploy-package.md b/docs-site/content/kagent/resources/cli/kagent-mcp-deploy-package.md new file mode 100644 index 00000000..47cdce34 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-deploy-package.md @@ -0,0 +1,53 @@ +--- +title: kagent mcp deploy package +description: Deploy an MCP server using a package manager to run Model Context Protocol servers. +weight: 300 +--- + +Deploy an MCP server using a package manager to run Model Context Protocol servers. + +This subcommand creates an MCPServer Custom Resource Definition (CRD) that runs +an MCP server using npx (for npm packages) or uvx (for Python packages). + +The deployment name, manager, and args are required. The package manager must be either 'npx' or 'uvx'. + +```bash +kagent mcp deploy package [flags] +``` + +**Flags:** +- `--args strings` - Arguments to pass to the package manager (e.g., package names) (required) +- `--deployment-name string` - Name for the deployment (required) +- `--dry-run` - Generate manifest without applying to cluster +- `--env strings` - Environment variables (KEY=VALUE) +- `-h, --help` - help for package +- `--image string` - Docker image to deploy (overrides default) +- `--manager string` - Package manager to use (npx or uvx) (required) +- `-n, --namespace string` - Kubernetes namespace +- `--no-inspector` - Do not start the MCP inspector after deployment (default true) +- `--output string` - Output file for the generated YAML +- `--port int` - Container port (default: 3000) +- `--secrets strings` - List of Kubernetes secret names to mount +- `--transport string` - Transport type (stdio, http) + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output + +## Example + +```bash +kagent mcp deploy package --deployment-name github-server --manager npx --args @modelcontextprotocol/server-github # Deploy GitHub MCP server + kagent mcp deploy package --deployment-name github-server --manager npx --args @modelcontextprotocol/server-github --dry-run # Print YAML without deploying + kagent mcp deploy package --deployment-name my-server --manager npx --args my-package --env "KEY1=value1,KEY2=value2" # Set environment variables + kagent mcp deploy package --deployment-name github-server --manager npx --args @modelcontextprotocol/server-github --secrets secret1,secret2 # Mount Kubernetes secrets + kagent mcp deploy package --deployment-name my-server --manager npx --args my-package --no-inspector # Deploy without starting inspector + kagent mcp deploy package --deployment-name my-server --manager uvx --args mcp-server-git # Use UV and write managed tools and installables to /tmp directories +``` diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-deploy.md b/docs-site/content/kagent/resources/cli/kagent-mcp-deploy.md new file mode 100644 index 00000000..a2e3eef5 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-deploy.md @@ -0,0 +1,72 @@ +--- +title: kagent mcp deploy +description: Deploy an MCP server to Kubernetes by generating MCPServer CRDs. +weight: 290 +--- + +Deploy an MCP server to Kubernetes by generating MCPServer CRDs. + +This command generates MCPServer Custom Resource Definitions (CRDs) based on: +- Project configuration from manifest.yaml +- Docker image built with 'kagent mcp build --docker' +- Deployment configuration options + +The generated MCPServer will include: +- Docker image reference from the build +- Transport configuration (stdio/http) +- Port and command configuration +- Environment variables and secrets + +The command can also apply Kubernetes secret YAML files to the cluster before deploying the MCPServer. +The secrets will be referenced in the MCPServer CRD for mounting as volumes to the MCP server container. +Secret namespace will be overridden with the deployment namespace to avoid the need for reference grants +to enable cross-namespace references. + +```bash +kagent mcp deploy [flags] +kagent mcp deploy [command] +``` + +**Subcommands:** +- [`kagent mcp deploy package`](../kagent-mcp-deploy-package/) - Deploy an MCP server using a package manager (npx, uvx) + +**Flags:** +- `--args strings` - Command arguments +- `--command string` - Command to run (overrides project config) +- `--dry-run` - Generate manifest without applying to cluster +- `--env strings` - Environment variables (KEY=VALUE) +- `--environment string` - Target environment for deployment (e.g., staging, production) (default "staging") +- `-f, --file string` - Path to manifest.yaml file (default: current directory) +- `--force` - Force deployment even if validation fails +- `-h, --help` - help for deploy +- `--image string` - Docker image to deploy (overrides build image) +- `-n, --namespace string` - Kubernetes namespace (default "default") +- `--no-inspector` - Do not start the MCP inspector after deployment (default true) +- `--output string` - Output file for the generated YAML +- `--port int` - Container port (default: from project config) +- `--transport string` - Transport type (stdio, http) + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output + +## Example + +```bash +kagent mcp deploy # Deploy with project name to cluster + kagent mcp deploy my-server # Deploy with custom name + kagent mcp deploy --namespace staging # Deploy to staging namespace + kagent mcp deploy --dry-run # Generate manifest without applying to cluster + kagent mcp deploy --image custom:tag # Use custom image + kagent mcp deploy --transport http # Use HTTP transport + kagent mcp deploy --output deploy.yaml # Save to file + kagent mcp deploy --file /path/to/manifest.yaml # Use custom manifest.yaml file + kagent mcp deploy --environment staging # Target environment for deployment (e.g., staging, production) +``` diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-init-go.md b/docs-site/content/kagent/resources/cli/kagent-mcp-init-go.md new file mode 100644 index 00000000..6459b682 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-init-go.md @@ -0,0 +1,38 @@ +--- +title: kagent mcp init go +description: Initialize a new MCP server project using the mcp-go framework. +weight: 320 +--- + +Initialize a new MCP server project using the mcp-go framework. + +This command will create a new directory with a basic mcp-go project structure, +including a go.mod file, a main.go file, and an example tool. + +You must provide a valid Go module name for the project. + +```bash +kagent mcp init go [project-name] [flags] +``` + +**Flags:** +- `--go-module-name string` - The Go module name for the project (e.g., github.com/my-org/my-project) +- `-h, --help` - help for go + +**Global Flags:** +- `--author string` - Author name for the project +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-init-java.md b/docs-site/content/kagent/resources/cli/kagent-mcp-init-java.md new file mode 100644 index 00000000..b4c5a058 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-init-java.md @@ -0,0 +1,35 @@ +--- +title: kagent mcp init java +description: Initialize a new MCP server project using the Java MCP framework. +weight: 330 +--- + +Initialize a new MCP server project using the Java MCP framework. + +This command will create a new directory with a basic Java MCP project structure, +including a pom.xml file, a Main.java file, and an example tool. + +```bash +kagent mcp init java [project-name] [flags] +``` + +**Flags:** +- `-h, --help` - help for java + +**Global Flags:** +- `--author string` - Author name for the project +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-init-python.md b/docs-site/content/kagent/resources/cli/kagent-mcp-init-python.md new file mode 100644 index 00000000..39162274 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-init-python.md @@ -0,0 +1,35 @@ +--- +title: kagent mcp init python +description: Initialize a new MCP server project using the fastmcp-python framework. +weight: 340 +--- + +Initialize a new MCP server project using the fastmcp-python framework. + +This command will create a new directory with a basic fastmcp-python project structure, +including a pyproject.toml file, a main.py file, and an example tool. + +```bash +kagent mcp init python [project-name] [flags] +``` + +**Flags:** +- `-h, --help` - help for python + +**Global Flags:** +- `--author string` - Author name for the project +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-init-typescript.md b/docs-site/content/kagent/resources/cli/kagent-mcp-init-typescript.md new file mode 100644 index 00000000..4b6a0322 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-init-typescript.md @@ -0,0 +1,35 @@ +--- +title: kagent mcp init typescript +description: Initialize a new MCP server project using the TypeScript MCP framework. +weight: 350 +--- + +Initialize a new MCP server project using the TypeScript MCP framework. + +This command will create a new directory with a basic TypeScript MCP project structure, +including a package.json file, a tsconfig.json file, and an example tool. + +```bash +kagent mcp init typescript [project-name] [flags] +``` + +**Flags:** +- `-h, --help` - help for typescript + +**Global Flags:** +- `--author string` - Author name for the project +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-init.md b/docs-site/content/kagent/resources/cli/kagent-mcp-init.md new file mode 100644 index 00000000..dd8e23c1 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-init.md @@ -0,0 +1,42 @@ +--- +title: kagent mcp init +description: Initialize a new MCP server project with dynamic tool loading. +weight: 310 +--- + +Initialize a new MCP server project with dynamic tool loading. + +This command provides subcommands to initialize a new MCP server project +using one of the supported frameworks. + +```bash +kagent mcp init [project-name] [flags] +kagent mcp init [command] +``` + +**Subcommands:** +- [`kagent mcp init go`](../kagent-mcp-init-go/) - Initialize a new Go MCP server project +- [`kagent mcp init java`](../kagent-mcp-init-java/) - Initialize a new Java MCP server project +- [`kagent mcp init python`](../kagent-mcp-init-python/) - Initialize a new Python MCP server project +- [`kagent mcp init typescript`](../kagent-mcp-init-typescript/) - Initialize a new TypeScript MCP server project + +**Flags:** +- `--author string` - Author name for the project +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `-h, --help` - help for init +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-run.md b/docs-site/content/kagent/resources/cli/kagent-mcp-run.md new file mode 100644 index 00000000..a00f8d13 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-run.md @@ -0,0 +1,49 @@ +--- +title: kagent mcp run +description: Run an MCP server locally using the Model Context Protocol inspector. +weight: 360 +--- + +Run an MCP server locally using the Model Context Protocol inspector. + +By default, this command will: +1. Load the manifest.yaml configuration from the project directory +2. Determine the framework type and create the appropriate mcp inspector configuration +3. Launch the MCP inspector and select STDIO as the transport type, the server will start when you click "Connect" + +If you want to run the server directly without the inspector, use the --no-inspector flag. +This will execute the server directly using the appropriate framework command. + +Supported frameworks: +- fastmcp-python: Requires uv to be installed +- mcp-go: Requires Go to be installed + +```bash +kagent mcp run [flags] +``` + +**Flags:** +- `-h, --help` - help for run +- `--no-inspector` - Run the server directly without launching the MCP inspector +- `-d, --project-dir string` - Project directory to use (default: current directory) +- `--transport string` - Transport mode (stdio or http) (default "stdio") + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output + +## Example + +```bash +kagent run mcp --project-dir ./my-project # Run with inspector (default) + kagent run mcp --no-inspector # Run server directly without inspector + kagent run mcp --transport http # Run with HTTP transport +``` diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-secrets-sync.md b/docs-site/content/kagent/resources/cli/kagent-mcp-secrets-sync.md new file mode 100644 index 00000000..921b6d4f --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-secrets-sync.md @@ -0,0 +1,51 @@ +--- +title: kagent mcp secrets sync +description: Sync secrets from a local .env file to a Kubernetes secret. +weight: 380 +--- + +Sync secrets from a local .env file to a Kubernetes secret. + +This command reads a .env file and the project's manifest.yaml file to determine +the correct secret name and namespace for the specified environment. It then +creates or updates the Kubernetes secret directly in the cluster. + +The command will look for a ".env" file in the project root by default. + +```bash +kagent mcp secrets sync [environment] [flags] +``` + +**Flags:** +- `--dry-run` - Output the generated secret YAML instead of applying it +- `--from-file string` - Source .env file to sync from (default ".env") +- `-h, --help` - help for sync +- `-d, --project-dir string` - Project directory (default: current directory) + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output + +## Example + +```bash +# Sync secrets to the "staging" environment defined in manifest.yaml + kagent mcp secrets sync staging + + # Sync secrets from a custom .env file + kagent mcp secrets sync staging --from-file .env.staging + + # Sync secrets from a specific project directory + kagent mcp secrets sync staging --project-dir ./my-project + + # Perform a dry run to see the generated secret without applying it + kagent mcp secrets sync production --dry-run +``` diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp-secrets.md b/docs-site/content/kagent/resources/cli/kagent-mcp-secrets.md new file mode 100644 index 00000000..8a3feec1 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp-secrets.md @@ -0,0 +1,29 @@ +--- +title: kagent mcp secrets +description: Manage secrets for MCP server projects. +weight: 370 +--- + +Manage secrets for MCP server projects. + +```bash +kagent mcp secrets [command] +``` + +**Subcommands:** +- [`kagent mcp secrets sync`](../kagent-mcp-secrets-sync/) - Sync secrets to a Kubernetes environment from a local .env file + +**Flags:** +- `-h, --help` - help for secrets + +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp.md b/docs-site/content/kagent/resources/cli/kagent-mcp.md index 1b1a65ff..550ca9fd 100644 --- a/docs-site/content/kagent/resources/cli/kagent-mcp.md +++ b/docs-site/content/kagent/resources/cli/kagent-mcp.md @@ -1,42 +1,35 @@ --- title: kagent mcp -description: kagent mcp command -weight: 10 +description: MCP server management commands for creating and managing +weight: 260 --- -Model Context Protocol (MCP) server management commands for creating and managing MCP servers with dynamic tool loading. +MCP server management commands for creating and managing +Model Context Protocol servers with dynamic tool loading. ```bash -kagent mcp [subcommand] [flags] +kagent mcp [command] ``` **Subcommands:** -- `init` - Initialize a new MCP server project -- `build` - Build a Docker image for your MCP server -- `deploy` - Deploy your MCP server to a Kubernetes cluster -- `add-tool` - Generate an MCP tool boilerplate -- `run` - Run an MCP server locally -- `secrets` - Manage secrets for MCP server projects +- [`kagent mcp add-tool`](../kagent-mcp-add-tool/) - Add a new MCP tool to your project +- [`kagent mcp build`](../kagent-mcp-build/) - Build MCP server as a Docker image +- [`kagent mcp deploy`](../kagent-mcp-deploy/) - Deploy MCP server to Kubernetes +- [`kagent mcp init`](../kagent-mcp-init/) - Initialize a new MCP server project +- [`kagent mcp run`](../kagent-mcp-run/) - Run MCP server locally +- [`kagent mcp secrets`](../kagent-mcp-secrets/) - Manage project secrets -**Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## About `kagent mcp` - -The `kagent mcp` command provides a set of subcommands for managing MCP servers. This is useful for creating and managing tools that can be used by kagent agents. - -## Example - -See the kagent mcp documentation for detailed examples of each subcommand: - -- [kagent mcp init](/docs/kmcp/reference/kmcp-init) - Create a scaffold for your MCP server -- [kagent mcp build](/docs/kmcp/reference/kmcp-build) - Build a Docker image -- [kagent mcp deploy](/docs/kmcp/reference/kmcp-deploy) - Deploy to Kubernetes -- [kagent mcp add-tool](/docs/kmcp/reference/kmcp-add-tool) - Generate tool boilerplate -- [kagent mcp run](/docs/kmcp/reference/kmcp-run) - Run locally -- [kagent mcp secrets](/docs/kmcp/reference/kmcp-secrets) - Manage secrets +**Flags:** +- `-h, --help` - help for mcp +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-run.md b/docs-site/content/kagent/resources/cli/kagent-run.md index 71b90a27..37f017ab 100644 --- a/docs-site/content/kagent/resources/cli/kagent-run.md +++ b/docs-site/content/kagent/resources/cli/kagent-run.md @@ -1,62 +1,35 @@ --- title: kagent run -description: kagent run command -weight: 10 +description: Run an agent project locally using docker-compose and launch an interactive chat session. +weight: 390 --- -Run an agent project locally with docker-compose and launch an interactive chat interface. +Run an agent project locally using docker-compose and launch an interactive chat session. ```bash kagent run [project-directory] [flags] ``` -**Arguments:** -- `project-directory` - The directory containing the agent project (default: current directory) - **Flags:** - `--build` - Rebuild the Docker image before running -- `--project-dir` - Project directory (default: current directory) +- `-h, --help` - help for run +- `--project-dir string` - Project directory (default: current directory) **Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## About `kagent run` - -The `kagent run` command runs an agent project locally using `docker-compose` and launches an interactive chat session. This way, you can test and interact with your agent before deploying it to a Kubernetes cluster. - -### Rebuilding before running - -Use the `--build` flag to rebuild the Docker image before running the agent. This is useful when you've made changes to your agent code and want to test the updated version without manually running `kagent build` first. - -```bash -kagent run --build -``` - -This command rebuilds the agent image and then starts the interactive chat interface. It's equivalent to running `kagent build` followed by `kagent run`. +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output ## Example -Run an agent project from the current directory: - -```bash -kagent run -``` - -Run an agent project from a specific directory: - ```bash kagent run ./my-agent + kagent run . ``` - -Rebuild the image and run the agent: - -```bash -kagent run --build -``` - -This is useful after making code changes to ensure you're testing the latest version of your agent. - diff --git a/docs-site/content/kagent/resources/cli/kagent-uninstall.md b/docs-site/content/kagent/resources/cli/kagent-uninstall.md index 41f7b8b1..76073818 100644 --- a/docs-site/content/kagent/resources/cli/kagent-uninstall.md +++ b/docs-site/content/kagent/resources/cli/kagent-uninstall.md @@ -1,27 +1,26 @@ --- title: kagent uninstall -description: kagent uninstall command -weight: 10 +description: Uninstall kagent +weight: 400 --- -Uninstall kagent from a Kubernetes cluster. +Uninstall kagent ```bash kagent uninstall [flags] ``` -**Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## Example - -Uninstall kagent: - -```bash -kagent uninstall -``` +**Flags:** +- `-h, --help` - help for uninstall +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kagent/resources/cli/kagent-version.md b/docs-site/content/kagent/resources/cli/kagent-version.md index 094f0628..a1958d9b 100644 --- a/docs-site/content/kagent/resources/cli/kagent-version.md +++ b/docs-site/content/kagent/resources/cli/kagent-version.md @@ -1,31 +1,26 @@ --- title: kagent version -description: kagent version command -weight: 10 +description: Print the kagent version +weight: 410 --- -Print the kagent version information. +Print the kagent version ```bash kagent version [flags] ``` -**Global Flags:** -- `--kagent-url` - kagent URL (default: "http://localhost:8083") -- `--namespace, -n` - Namespace (default: "kagent") -- `--output-format, -o` - Output format (default: "table") -- `--timeout` - Timeout duration (default: 300s) -- `--verbose, -v` - Verbose output - -## About `kagent version` - -This command prints the kagent CLI version. The CLI attempts to connect to the kagent server to retrieve server version information. Versions unable to be obtained from the remote kagent server are reported as "unknown". - -## Example - -Print version information: - -```bash -kagent version -``` +**Flags:** +- `-h, --help` - help for version +**Global Flags:** +- `--config string` - config file (default is $HOME/.kagent/config.yaml) (default "$HOME/.kagent/config.yaml") +- `--kagent-grpc-ca-file string` - CA certificate file for KAgent gRPC +- `--kagent-grpc-server-name string` - TLS server name for KAgent gRPC +- `--kagent-grpc-tls` - Use TLS for KAgent gRPC +- `--kagent-grpc-url string` - KAgent gRPC target (default "localhost:8084") +- `--kagent-url string` - KAgent REST URL (default "http://localhost:8083") +- `-n, --namespace string` - Namespace (default "kagent") +- `-o, --output-format string` - Output format (default "table") +- `--timeout duration` - Timeout (default 5m0s) +- `-v, --verbose` - Verbose output diff --git a/docs-site/content/kmcp/reference/cli/_index.md b/docs-site/content/kmcp/reference/cli/_index.md new file mode 100644 index 00000000..00ffe29d --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/_index.md @@ -0,0 +1,16 @@ +--- +title: CLI docs +description: Complete reference docs for the kmcp CLI commands +weight: 1 +--- + +Review the kmcp CLI commands and learn how to use them effectively. + +- [`kmcp add-tool`](kmcp-add-tool/) - Add a new MCP tool to your project +- [`kmcp build`](kmcp-build/) - Build MCP server as a Docker image +- [`kmcp completion`](kmcp-completion/) - Generate the autocompletion script for the specified shell +- [`kmcp deploy`](kmcp-deploy/) - Deploy MCP server to Kubernetes +- [`kmcp init`](kmcp-init/) - Initialize a new MCP server project +- [`kmcp install`](kmcp-install/) - Install the KMCP controller on a Kubernetes cluster +- [`kmcp run`](kmcp-run/) - Run MCP server locally +- [`kmcp secrets`](kmcp-secrets/) - Manage project secrets diff --git a/docs-site/content/kmcp/reference/cli/kmcp-add-tool.md b/docs-site/content/kmcp/reference/cli/kmcp-add-tool.md new file mode 100644 index 00000000..b5dabc7b --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-add-tool.md @@ -0,0 +1,35 @@ +--- +title: kmcp add-tool +description: Generate a new MCP tool that will be automatically loaded by the server. +weight: 10 +--- + +Generate a new MCP tool that will be automatically loaded by the server. + +This command creates a new tool file in src/tools/ with a generic template. +The tool will be automatically discovered and loaded when the server starts. + +Each tool is a Python file containing a function decorated with @mcp.tool(). +The function should use the @mcp.tool() decorator from FastMCP. + +```bash +kmcp add-tool [tool-name] [flags] +``` + +**Flags:** +- `-d, --description string` - Tool description +- `-f, --force` - Overwrite existing tool file +- `-h, --help` - help for add-tool +- `-i, --interactive` - Interactive tool creation +- `--project-dir string` - Project directory (default: current directory) + +**Global Flags:** +- `-v, --verbose` - verbose output + +## Example + +```bash +kmcp add-tool weather + kmcp add-tool database --description "Database operations tool" + kmcp add-tool weather --force +``` diff --git a/docs-site/content/kmcp/reference/cli/kmcp-build.md b/docs-site/content/kmcp/reference/cli/kmcp-build.md new file mode 100644 index 00000000..bf0d5913 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-build.md @@ -0,0 +1,33 @@ +--- +title: kmcp build +description: Build an MCP server from the current project. +weight: 20 +--- + +Build an MCP server from the current project. + +This command will detect the project type and build the appropriate +MCP server Docker image. + +```bash +kmcp build [flags] +``` + +**Flags:** +- `-h, --help` - help for build +- `--kind-load` - Load image into kind cluster (requires kind) +- `--kind-load-cluster string` - Name of the kind cluster to load image into (default: current cluster) +- `--platform string` - Target platform (e.g., linux/amd64,linux/arm64) +- `-d, --project-dir string` - Build directory (default: current directory) +- `--push` - Push Docker image to registry +- `-t, --tag string` - Docker image tag (alias for --output) + +**Global Flags:** +- `-v, --verbose` - verbose output + +## Example + +```bash +kmcp build # Build Docker image from current directory + kmcp build --project-dir ./my-project # Build Docker image from specific directory +``` diff --git a/docs-site/content/kmcp/reference/cli/kmcp-completion-bash.md b/docs-site/content/kmcp/reference/cli/kmcp-completion-bash.md new file mode 100644 index 00000000..ef932bb9 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-completion-bash.md @@ -0,0 +1,37 @@ +--- +title: kmcp completion bash +description: Generate the autocompletion script for the bash shell. +weight: 40 +--- + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(kmcp completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + kmcp completion bash > /etc/bash_completion.d/kmcp + +#### macOS: + + kmcp completion bash > $(brew --prefix)/etc/bash_completion.d/kmcp + +You will need to start a new shell for this setup to take effect. + +```bash +kmcp completion bash +``` + +**Flags:** +- `-h, --help` - help for bash +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-completion-fish.md b/docs-site/content/kmcp/reference/cli/kmcp-completion-fish.md new file mode 100644 index 00000000..b3001adf --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-completion-fish.md @@ -0,0 +1,28 @@ +--- +title: kmcp completion fish +description: Generate the autocompletion script for the fish shell. +weight: 50 +--- + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + kmcp completion fish | source + +To load completions for every new session, execute once: + + kmcp completion fish > ~/.config/fish/completions/kmcp.fish + +You will need to start a new shell for this setup to take effect. + +```bash +kmcp completion fish [flags] +``` + +**Flags:** +- `-h, --help` - help for fish +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-completion-powershell.md b/docs-site/content/kmcp/reference/cli/kmcp-completion-powershell.md new file mode 100644 index 00000000..27147b23 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-completion-powershell.md @@ -0,0 +1,25 @@ +--- +title: kmcp completion powershell +description: Generate the autocompletion script for powershell. +weight: 60 +--- + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + kmcp completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + +```bash +kmcp completion powershell [flags] +``` + +**Flags:** +- `-h, --help` - help for powershell +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-completion-zsh.md b/docs-site/content/kmcp/reference/cli/kmcp-completion-zsh.md new file mode 100644 index 00000000..30eb927d --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-completion-zsh.md @@ -0,0 +1,39 @@ +--- +title: kmcp completion zsh +description: Generate the autocompletion script for the zsh shell. +weight: 70 +--- + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(kmcp completion zsh) + +To load completions for every new session, execute once: + +#### Linux: + + kmcp completion zsh > "${fpath[1]}/_kmcp" + +#### macOS: + + kmcp completion zsh > $(brew --prefix)/share/zsh/site-functions/_kmcp + +You will need to start a new shell for this setup to take effect. + +```bash +kmcp completion zsh [flags] +``` + +**Flags:** +- `-h, --help` - help for zsh +- `--no-descriptions` - disable completion descriptions + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-completion.md b/docs-site/content/kmcp/reference/cli/kmcp-completion.md new file mode 100644 index 00000000..a1da60c8 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-completion.md @@ -0,0 +1,24 @@ +--- +title: kmcp completion +description: Generate the autocompletion script for kmcp for the specified shell. +weight: 30 +--- + +Generate the autocompletion script for kmcp for the specified shell. +See each sub-command's help for details on how to use the generated script. + +```bash +kmcp completion [flags] +``` + +**Subcommands:** +- [`kmcp completion bash`](../kmcp-completion-bash/) - Generate the autocompletion script for bash +- [`kmcp completion fish`](../kmcp-completion-fish/) - Generate the autocompletion script for fish +- [`kmcp completion powershell`](../kmcp-completion-powershell/) - Generate the autocompletion script for powershell +- [`kmcp completion zsh`](../kmcp-completion-zsh/) - Generate the autocompletion script for zsh + +**Flags:** +- `-h, --help` - help for completion + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-deploy-package.md b/docs-site/content/kmcp/reference/cli/kmcp-deploy-package.md new file mode 100644 index 00000000..03299c75 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-deploy-package.md @@ -0,0 +1,45 @@ +--- +title: kmcp deploy package +description: Deploy an MCP server using a package manager to run Model Context Protocol servers. +weight: 90 +--- + +Deploy an MCP server using a package manager to run Model Context Protocol servers. + +This subcommand creates an MCPServer Custom Resource Definition (CRD) that runs +an MCP server using npx (for npm packages) or uvx (for Python packages). + +The deployment name, manager, and args are required. The package manager must be either 'npx' or 'uvx'. + +```bash +kmcp deploy package [flags] +``` + +**Flags:** +- `--args strings` - Arguments to pass to the package manager (e.g., package names) (required) +- `--deployment-name string` - Name for the deployment (required) +- `--dry-run` - Generate manifest without applying to cluster +- `--env strings` - Environment variables (KEY=VALUE) +- `-h, --help` - help for package +- `--image string` - Docker image to deploy (overrides default) +- `--manager string` - Package manager to use (npx or uvx) (required) +- `-n, --namespace string` - Kubernetes namespace +- `--no-inspector` - Do not start the MCP inspector after deployment +- `-o, --output string` - Output file for the generated YAML +- `--port int` - Container port (default: 3000) +- `--secrets strings` - List of Kubernetes secret names to mount +- `--transport string` - Transport type (stdio, http) + +**Global Flags:** +- `-v, --verbose` - verbose output + +## Example + +```bash +kmcp deploy package --deployment-name github-server --manager npx --args @modelcontextprotocol/server-github # Deploy GitHub MCP server + kmcp deploy package --deployment-name github-server --manager npx --args @modelcontextprotocol/server-github --dry-run # Print YAML without deploying + kmcp deploy package --deployment-name my-server --manager npx --args my-package --env "KEY1=value1,KEY2=value2" # Set environment variables + kmcp deploy package --deployment-name github-server --manager npx --args @modelcontextprotocol/server-github --secrets secret1,secret2 # Mount Kubernetes secrets + kmcp deploy package --deployment-name my-server --manager npx --args my-package --no-inspector # Deploy without starting inspector + kmcp deploy package --deployment-name my-server --manager uvx --args mcp-server-git # Use UV and write managed tools and installables to /tmp directories +``` diff --git a/docs-site/content/kmcp/reference/cli/kmcp-deploy.md b/docs-site/content/kmcp/reference/cli/kmcp-deploy.md new file mode 100644 index 00000000..abffbd63 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-deploy.md @@ -0,0 +1,63 @@ +--- +title: kmcp deploy +description: Deploy an MCP server to Kubernetes by generating MCPServer CRDs. +weight: 80 +--- + +Deploy an MCP server to Kubernetes by generating MCPServer CRDs. + +This command generates MCPServer Custom Resource Definitions (CRDs) based on: +- Project configuration from kmcp.yaml +- Docker image built with 'kmcp build --docker' +- Deployment configuration options + +The generated MCPServer will include: +- Docker image reference from the build +- Transport configuration (stdio/http) +- Port and command configuration +- Environment variables and secrets + +The command can also apply Kubernetes secret YAML files to the cluster before deploying the MCPServer. +The secrets will be referenced in the MCPServer CRD for mounting as volumes to the MCP server container. +Secret namespace will be overridden with the deployment namespace to avoid the need for reference grants +to enable cross-namespace references. + +```bash +kmcp deploy [flags] +``` + +**Subcommands:** +- [`kmcp deploy package`](../kmcp-deploy-package/) - Deploy an MCP server using a package manager (npx, uvx) + +**Flags:** +- `--args strings` - Command arguments +- `--command string` - Command to run (overrides project config) +- `--dry-run` - Generate manifest without applying to cluster +- `--env strings` - Environment variables (KEY=VALUE) +- `--environment string` - Target environment for deployment (e.g., staging, production) (default "staging") +- `-f, --file string` - Path to kmcp.yaml file (default: current directory) +- `--force` - Force deployment even if validation fails +- `-h, --help` - help for deploy +- `--image string` - Docker image to deploy (overrides build image) +- `-n, --namespace string` - Kubernetes namespace (default "default") +- `--no-inspector` - Do not start the MCP inspector after deployment +- `-o, --output string` - Output file for the generated YAML +- `--port int` - Container port (default: from project config) +- `--transport string` - Transport type (stdio, http) + +**Global Flags:** +- `-v, --verbose` - verbose output + +## Example + +```bash +kmcp deploy # Deploy with project name to cluster + kmcp deploy my-server # Deploy with custom name + kmcp deploy --namespace staging # Deploy to staging namespace + kmcp deploy --dry-run # Generate manifest without applying to cluster + kmcp deploy --image custom:tag # Use custom image + kmcp deploy --transport http # Use HTTP transport + kmcp deploy --output deploy.yaml # Save to file + kmcp deploy --file /path/to/kmcp.yaml # Use custom kmcp.yaml file + kmcp deploy --environment staging # Target environment for deployment (e.g., staging, production) +``` diff --git a/docs-site/content/kmcp/reference/cli/kmcp-init-go.md b/docs-site/content/kmcp/reference/cli/kmcp-init-go.md new file mode 100644 index 00000000..c09eb063 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-init-go.md @@ -0,0 +1,30 @@ +--- +title: kmcp init go +description: Initialize a new MCP server project using the mcp-go framework. +weight: 110 +--- + +Initialize a new MCP server project using the mcp-go framework. + +This command will create a new directory with a basic mcp-go project structure, +including a go.mod file, a main.go file, and an example tool. + +You must provide a valid Go module name for the project. + +```bash +kmcp init go [project-name] [flags] +``` + +**Flags:** +- `--go-module-name string` - The Go module name for the project (e.g., github.com/my-org/my-project) +- `-h, --help` - help for go + +**Global Flags:** +- `--author string` - Author name for the project +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-init-java.md b/docs-site/content/kmcp/reference/cli/kmcp-init-java.md new file mode 100644 index 00000000..919f23b7 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-init-java.md @@ -0,0 +1,27 @@ +--- +title: kmcp init java +description: Initialize a new MCP server project using the Java framework. +weight: 120 +--- + +Initialize a new MCP server project using the Java framework. + +This command will create a new directory with a basic Java MCP project structure, +including a pom.xml file, Maven project structure, and an example tool. + +```bash +kmcp init java [project-name] [flags] +``` + +**Flags:** +- `-h, --help` - help for java + +**Global Flags:** +- `--author string` - Author name for the project +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-init-python.md b/docs-site/content/kmcp/reference/cli/kmcp-init-python.md new file mode 100644 index 00000000..14d97c39 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-init-python.md @@ -0,0 +1,27 @@ +--- +title: kmcp init python +description: Initialize a new MCP server project using the fastmcp-python framework. +weight: 130 +--- + +Initialize a new MCP server project using the fastmcp-python framework. + +This command will create a new directory with a basic fastmcp-python project structure, +including a pyproject.toml file, a main.py file, and an example tool. + +```bash +kmcp init python [project-name] [flags] +``` + +**Flags:** +- `-h, --help` - help for python + +**Global Flags:** +- `--author string` - Author name for the project +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-init-typescript.md b/docs-site/content/kmcp/reference/cli/kmcp-init-typescript.md new file mode 100644 index 00000000..61e1d7aa --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-init-typescript.md @@ -0,0 +1,27 @@ +--- +title: kmcp init typescript +description: Initialize a new MCP server project using the TypeScript framework. +weight: 140 +--- + +Initialize a new MCP server project using the TypeScript framework. + +This command will create a new directory with a basic TypeScript MCP project structure, +including a package.json file, tsconfig.json, and an example tool. + +```bash +kmcp init typescript [project-name] [flags] +``` + +**Flags:** +- `-h, --help` - help for typescript + +**Global Flags:** +- `--author string` - Author name for the project +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-init.md b/docs-site/content/kmcp/reference/cli/kmcp-init.md new file mode 100644 index 00000000..f9fd3a22 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-init.md @@ -0,0 +1,33 @@ +--- +title: kmcp init +description: Initialize a new MCP server project with dynamic tool loading. +weight: 100 +--- + +Initialize a new MCP server project with dynamic tool loading. + +This command provides subcommands to initialize a new MCP server project +using one of the supported frameworks. + +```bash +kmcp init [project-name] [flags] +``` + +**Subcommands:** +- [`kmcp init go`](../kmcp-init-go/) - Initialize a new Go MCP server project +- [`kmcp init java`](../kmcp-init-java/) - Initialize a new Java MCP server project +- [`kmcp init python`](../kmcp-init-python/) - Initialize a new Python MCP server project +- [`kmcp init typescript`](../kmcp-init-typescript/) - Initialize a new TypeScript MCP server project + +**Flags:** +- `--author string` - Author name for the project +- `--description string` - Description for the project +- `--email string` - Author email for the project +- `--force` - Overwrite existing directory +- `-h, --help` - help for init +- `--namespace string` - Default namespace for project resources (default "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Run in non-interactive mode + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-install.md b/docs-site/content/kmcp/reference/cli/kmcp-install.md new file mode 100644 index 00000000..af0e293e --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-install.md @@ -0,0 +1,28 @@ +--- +title: kmcp install +description: Install the KMCP controller and its required Custom Resource Definitions (CRDs) +weight: 150 +--- + +Install the KMCP controller and its required Custom Resource Definitions (CRDs) +on a Kubernetes cluster. + +This command should be run once per cluster to set up the necessary infrastructure +for deploying MCP servers. + +It will install the following resources: +- MCPServer Custom Resource Definition +- ClusterRole and ClusterRoleBinding for RBAC +- The KMCP controller Deployment + +```bash +kmcp install [flags] +``` + +**Flags:** +- `-h, --help` - help for install +- `--namespace string` - Namespace for the KMCP controller (defaults to kmcp-system) (default "kmcp-system") +- `--version string` - Version of the controller to deploy (defaults to latest) + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/cli/kmcp-run.md b/docs-site/content/kmcp/reference/cli/kmcp-run.md new file mode 100644 index 00000000..650bc7b3 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-run.md @@ -0,0 +1,40 @@ +--- +title: kmcp run +description: Run an MCP server locally using the Model Context Protocol inspector. +weight: 160 +--- + +Run an MCP server locally using the Model Context Protocol inspector. + +By default, this command will: +1. Load the kmcp.yaml configuration from the project directory +2. Determine the framework type and create the appropriate mcp inspector configuration +3. Launch the MCP inspector, which will start the server when you click "Connect" + +If you want to run the server directly without the inspector, use the --no-inspector flag. +This will execute the server directly using the appropriate framework command. + +Supported frameworks: +- fastmcp-python: Requires uv to be installed +- mcp-go: Requires Go to be installed + +```bash +kmcp run [flags] +``` + +**Flags:** +- `-h, --help` - help for run +- `--no-inspector` - Run the server directly without launching the MCP inspector +- `-d, --project-dir string` - Project directory to use (default: current directory) +- `--transport string` - Transport mode (stdio or http) (default "stdio") + +**Global Flags:** +- `-v, --verbose` - verbose output + +## Example + +```bash +kmcp run --project-dir ./my-project # Run with inspector (default) + kmcp run --no-inspector # Run server directly without inspector + kmcp run --transport http # Run with HTTP transport +``` diff --git a/docs-site/content/kmcp/reference/cli/kmcp-secrets-sync.md b/docs-site/content/kmcp/reference/cli/kmcp-secrets-sync.md new file mode 100644 index 00000000..09159e16 --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-secrets-sync.md @@ -0,0 +1,35 @@ +--- +title: kmcp secrets sync +description: Sync secrets from a local .env file to a Kubernetes secret. +weight: 180 +--- + +Sync secrets from a local .env file to a Kubernetes secret. + +This command reads a .env file and the project's kmcp.yaml file to determine +the correct secret name and namespace for the specified environment. It then +creates or updates the Kubernetes secret directly in the cluster. + +The command will look for a ".env" file in the project root by default. + +```bash +kmcp secrets sync [environment] [flags] +``` + +**Flags:** +- `--dry-run` - Output the generated secret YAML instead of applying it +- `--from-file string` - Source .env file to sync from (default ".env") +- `-h, --help` - help for sync +- `-d, --project-dir string` - Project directory (default: current directory) + +**Global Flags:** +- `-v, --verbose` - verbose output + +## Example + +```bash +kmcp secrets sync staging # Sync secrets to the "staging" environment + kmcp secrets sync staging --from-file .env.staging # Sync secrets from a custom .env file + kmcp secrets sync staging --project-dir ./my-project # Sync secrets from a specific project directory + kmcp secrets sync production --dry-run # Perform a dry run to see the generated secret without applying it +``` diff --git a/docs-site/content/kmcp/reference/cli/kmcp-secrets.md b/docs-site/content/kmcp/reference/cli/kmcp-secrets.md new file mode 100644 index 00000000..00f5a85b --- /dev/null +++ b/docs-site/content/kmcp/reference/cli/kmcp-secrets.md @@ -0,0 +1,20 @@ +--- +title: kmcp secrets +description: Manage secrets for MCP server projects. +weight: 170 +--- + +Manage secrets for MCP server projects. + +```bash +kmcp secrets [flags] +``` + +**Subcommands:** +- [`kmcp secrets sync`](../kmcp-secrets-sync/) - Sync secrets to a Kubernetes environment from a local .env file + +**Flags:** +- `-h, --help` - help for secrets + +**Global Flags:** +- `-v, --verbose` - verbose output diff --git a/docs-site/content/kmcp/reference/kmcp-add-tool.md b/docs-site/content/kmcp/reference/kmcp-add-tool.md deleted file mode 100644 index 8a1a78a5..00000000 --- a/docs-site/content/kmcp/reference/kmcp-add-tool.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: kmcp add-tool -description: kmcp add-tool command -weight: 10 ---- - -Create a boilerplate for a sample `echo` tool in the `tools` directory of your MCP project and update all the MCP server dependencies to import that tool. You can use this boilerplate as the base to build your own tool. - -```bash -kmcp add-tool [tool-name] [flags] -``` - -**Flags:** -- `--description, -d` - Tool description -- `--force, -f` - Overwrite existing tool file -- `-h, --help` - Help for the command -- `--interactive, -i` - Interactive tool creation -- `--project-dir` - Project directory (default: current directory) - -**Global Flags:** -- `--verbose, -v` - Show detailed output - -## Example - -The following command creates a `mytool` MCP tool in the `my-mcp-server` MCP project. You can edit the file and adjust the code as needed. - -```sh -kmcp add-tool mytool --project-dir my-mcp-server -``` - diff --git a/docs-site/content/kmcp/reference/kmcp-build.md b/docs-site/content/kmcp/reference/kmcp-build.md deleted file mode 100644 index 216c32bb..00000000 --- a/docs-site/content/kmcp/reference/kmcp-build.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: kmcp build -description: kmcp build command -weight: 10 ---- - -Build a Docker image for your MCP server. You can later use this image to deploy your MCP server in a Kubernetes environment. - -```bash -kmcp build [flags] -``` - -**Flags:** -- `-h, --help` - Help for the command -- `--kind-load` - Load image onto a kind cluster (requires kind) -- `--kind-load-cluster` - Name of the kind cluster to load the image onto (default: current cluster context) -- `--platform` - Target platform (e.g., linux/amd64, linux/arm64) -- `--project-dir, -d` - Build directory (default: current directory) -- `--push` - Push the Docker image to a container registry -- `--tag, -t` - Docker image tag - -## Example - -The following command creates a Docker image for the `my-mcp-server` project on your local machine and tags the image as latest. The image is then loaded to a kind cluster named `kind`. - -```sh -kmcp build --project-dir my-mcp-server -t my-mcp-server:latest --kind-load-cluster kind -``` \ No newline at end of file diff --git a/docs-site/content/kmcp/reference/kmcp-completion.md b/docs-site/content/kmcp/reference/kmcp-completion.md deleted file mode 100644 index ec13618e..00000000 --- a/docs-site/content/kmcp/reference/kmcp-completion.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: kmcp completion -description: kmcp completion command -weight: 30 ---- - -Generate the autocompletion script for kmcp for the specified shell. See each sub-command's help for details on how to use the generated script. - -```bash -kmcp completion [flags] -``` - -**Subcommands:** -- `bash` - Generate the autocompletion script for bash -- `fish` - Generate the autocompletion script for fish -- `powershell` - Generate the autocompletion script for powershell -- `zsh` - Generate the autocompletion script for zsh - diff --git a/docs-site/content/kmcp/reference/kmcp-deploy.md b/docs-site/content/kmcp/reference/kmcp-deploy.md deleted file mode 100644 index b1f378c2..00000000 --- a/docs-site/content/kmcp/reference/kmcp-deploy.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: kmcp deploy -description: kmcp deploy command -weight: 10 ---- - -Deploy an MCP server to Kubernetes by generating the MCPServer CRDs. The command uses the `kmcp.yaml` file in your MCP project to spin up and deploy the MCP server in the environment that you specified. - -```bash -kmcp deploy [name] [flags] -``` - -**Subcommands**: - -* `package [flags]` - Deploys an MCP server instance from an existing npm package. - -**Package flags**: -- `--args` - Arguments to pass to the package manager, such as package names (required) -- `--deployment-name` - Name of the MCP server deployment -- `--manager` - Package manager to use (`npx` or `uvx`) (required) - -**Flags:** -- `--args` - Command arguments -- `--command` - Command to run (overrides project config) -- `--dry-run` - Generate manifest without applying to cluster -- `--env` - Environment variables (KEY=VALUE) -- `--environment` - Target environment for deployment (e.g., staging, production) (default: "staging") -- `--file, -f` - Path to kmcp.yaml file (default: current directory) -- `--force` - Force deployment even if validation fails -- `-h, --help` - Help for the command -- `--image` - Docker image to deploy (overrides build image) -- `--namespace, -n` - Kubernetes namespace (default: "default") -- `--no-inspector` - Do not start the MCP inspector tool when deploying the MCP server -- `--output, -o` - Output file for the generated YAML -- `--port` - Container port (default: from project config) -- `--target-port` - Target port for HTTP transport -- `--transport` - Transport type (stdio, http) - -**Global Flags:** -- `--verbose, -v` - Show detailed output - -## Example - -The following example spins up an MCP server in the staging environment with the configuration that is defined in the `my-mcp-server/kmcp.yaml` file. To spin up the server, you use the `my-mcp-server:latest` image. The command automatically opens the MCP inspector tool so that you can test your MCP server. - -```sh -kmcp deploy --environment staging --file my-mcp-server/kmcp.yaml --image my-mcp-server:latest -``` - diff --git a/docs-site/content/kmcp/reference/kmcp-help.md b/docs-site/content/kmcp/reference/kmcp-help.md deleted file mode 100644 index 29695c2a..00000000 --- a/docs-site/content/kmcp/reference/kmcp-help.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: kmcp help -description: kmcp help command -weight: 100 ---- - -Help provides help for any command in the `kmcp` CLI. - -```bash -kmcp help [command] [flags] -``` - diff --git a/docs-site/content/kmcp/reference/kmcp-init.md b/docs-site/content/kmcp/reference/kmcp-init.md deleted file mode 100644 index b3e03579..00000000 --- a/docs-site/content/kmcp/reference/kmcp-init.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: kmcp init -description: kmcp init command -weight: 10 ---- - -Create a scaffold for a new [FastMCP](https://github.com/jlowin/fastmcp) or [MCP Go](https://github.com/mark3labs/mcp-go) server project. - -```bash -kmcp init [subcommand] [project-name] [flags] -``` - -**Subcommands:** -- `python [project-name]` - Initialize a Python MCP server project using fastmcp-python -- `go [project-name]` - Initialize a Go MCP server project using mcp-go - -**Flags:** -- `--author` - Set project author -- `--description` - Set project description -- `--email` - Set author email -- `--force` - Overwrite existing directory -- `-h, --help` - Help for the command -- `--namespace` - Default namespace for project resources (default: "default") -- `--no-git` - Skip git initialization -- `--non-interactive` - Use defaults without prompts - -**Go-specific Flags:** -- `--go-module-name` - The Go module name for the project (e.g., github.com/my-org/my-project) - -**Global Flags:** -- `--verbose, -v` - Show detailed output - -## Example - -FastMCP: -```sh -kmcp init python my-mcp-server -``` - -MCP Go: -```sh -kmcp init go my-mcp-server --go-module-name my-mcp-server -``` diff --git a/docs-site/content/kmcp/reference/kmcp-install.md b/docs-site/content/kmcp/reference/kmcp-install.md deleted file mode 100644 index e19e8be4..00000000 --- a/docs-site/content/kmcp/reference/kmcp-install.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: kmcp install -description: kmcp install command -weight: 10 ---- - -Install the KMCP controller and its required Custom Resource Definitions (CRDs) -on a Kubernetes cluster. The KMCP contoller manages the lifecycle of MCPServer resources. - -The command installs the following resources: -* The MCPServer Custom Resource Definition to define your MCP server. -* The ClusterRole and ClusterRoleBinding to control RBAC permissions for the KMCP controller. -* The KMCP controller deployment that automatically manages the lifecycle of MCPServer resources. - -```bash -kmcp install [flags] -``` - -**Note**: Run this command once for each cluster to set up the necessary infrastructure -for deploying MCP servers. - -**Flags:** -- `-h, --help` - Help for the command -- `--namespace` - Namespace for the KMCP controller (defaults to kmcp-system) -- `--version` - Version of the controller to deploy (defaults to kmcp version) - -**Global Flags:** -- `--verbose, -v` - Show detailed output - diff --git a/docs-site/content/kmcp/reference/kmcp-run.md b/docs-site/content/kmcp/reference/kmcp-run.md deleted file mode 100644 index 26d08740..00000000 --- a/docs-site/content/kmcp/reference/kmcp-run.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: kmcp run -description: kmcp run command -weight: 10 ---- - -Run an MCP server on your local machine by using the Model Context Protocol inspector tool. - -**Note**: If you do not have the MCP inspector tool installed, run `npm install -g @modelcontextprotocol/inspector`. - -```bash -kmcp run [flags] -``` - -**Flags:** -- `-h, --help` - Help for the command -- `--no-inspector` - Run the server directly without launching the MCP inspector tool -- `--project-dir, -d` - Project directory to use (default: current directory) - -**Global Flags:** -- `--verbose, -v` - Show detailed output - -## Example - -The following command runs the MCP server that is defined in the `my-mcp-server` project on your local machine. -The command automatically builds the Docker image for your MCP server and opens the MCP inspector tool so that you can connect to your server. - -```sh -kmcp run --project-dir my-mcp-server -``` - -To learn how to use the MCP inspector tool to connect to an MCP server, check out the [FastMCP Python](/docs/kmcp/develop/fastmcp-python) or [MCP Go](/docs/kmcp/develop/mcp-go) guide. diff --git a/docs-site/content/kmcp/reference/kmcp-secrets.md b/docs-site/content/kmcp/reference/kmcp-secrets.md deleted file mode 100644 index 747579ac..00000000 --- a/docs-site/content/kmcp/reference/kmcp-secrets.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: kmcp secrets -description: kmcp secrets command -weight: 10 ---- - -Manage secrets for MCP server projects and apply them to a Kubernetes cluster. - -```bash -kmcp secrets [subcommand] [flags] -``` - -**Subcommands:** -- `sync [environment]` - Sync secrets to a Kubernetes environment from a local .env file. The environment is defined in the `kmcp.yaml` file. - -**Sync Flags:** -- `--dry-run` - Output the generated secret YAML instead of applying it -- `--from-file` - Source .env file to sync from (default: ".env") -- `-h, --help` - Help for the command -- `--project-dir, -d` - Project directory (default: current directory) - -**Global Flags:** -- `--verbose, -v` - Show detailed output - -## Example - -The following command reads the environment variables that are defined in the `.env.staging` file and puts them into a Kubernetes secret in your cluster. -The name and namespace for the secret are defined in the `staging` environment configuration of the `kmcp.yaml` file. - -```sh -kmcp secrets sync staging --from-file my-mcp-server/.env.staging --project-dir my-mcp-server -``` - -For more information, check out [Manage secrets for MCP servers](/docs/kmcp/secrets). \ No newline at end of file diff --git a/scripts/audit-cli-docs.py b/scripts/audit-cli-docs.py new file mode 100755 index 00000000..df76fc3e --- /dev/null +++ b/scripts/audit-cli-docs.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +""" +Audit generated CLI doc pages for common problems: + - unbalanced ``` code fences + - frontmatter that doesn't parse as valid YAML (e.g. an unescaped ':' in + the description turns it into a nested mapping and breaks Hugo) + - stray section-header lines (e.g. a bare "Flags:") that leaked into the + body, which usually means the --help parser missed a header variant on + that specific page + - empty pages / missing frontmatter + +Usage: python3 audit-cli-docs.py /tmp/kagent-cli-docs-test /tmp/kmcp-cli-docs-test +""" +import sys +from pathlib import Path + +try: + import yaml +except ImportError: + print("PyYAML not installed; run: pip3 install --user pyyaml", file=sys.stderr) + sys.exit(1) + +SUSPECT_HEADERS = { + "usage", "aliases", "examples", "example", + "available commands", "flags", "global flags", +} + + +def audit_file(path: Path) -> list[str]: + problems = [] + text = path.read_text() + + if not text.startswith("---\n"): + problems.append("missing frontmatter delimiter at top") + return problems + + parts = text.split("---\n", 2) + if len(parts) < 3: + problems.append("frontmatter block never closes with ---") + return problems + + fm_text, body = parts[1], parts[2] + try: + fm = yaml.safe_load(fm_text) + if not isinstance(fm, dict) or "title" not in fm or "description" not in fm: + problems.append(f"frontmatter parsed but missing title/description: {fm!r}") + except yaml.YAMLError as e: + problems.append(f"frontmatter is not valid YAML: {e}") + + fence_count = body.count("```") + if fence_count % 2 != 0: + problems.append(f"unbalanced code fences ({fence_count} occurrences of ```)") + + if not body.strip(): + problems.append("body is empty") + + for i, line in enumerate(body.splitlines(), start=1): + norm = line.strip().rstrip(":").lower() + if norm in SUSPECT_HEADERS: + problems.append(f"line {i}: stray section header leaked into body: {line.strip()!r}") + + return problems + + +def main() -> int: + if len(sys.argv) < 2: + print(__doc__) + return 1 + + total_files = 0 + total_problems = 0 + for dir_arg in sys.argv[1:]: + out_dir = Path(dir_arg) + for md_file in sorted(out_dir.glob("*.md")): + total_files += 1 + problems = audit_file(md_file) + if problems: + total_problems += len(problems) + print(f"\n{md_file}") + for p in problems: + print(f" - {p}") + + print(f"\nChecked {total_files} files, found {total_problems} issue(s).", file=sys.stderr) + return 1 if total_problems else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/generate-cli-docs.py b/scripts/generate-cli-docs.py new file mode 100755 index 00000000..8bdfe96f --- /dev/null +++ b/scripts/generate-cli-docs.py @@ -0,0 +1,331 @@ +#!/usr/bin/env python3 +""" +Generate Hugo markdown CLI reference docs from a Cobra binary's --help output. + +This walks the command tree by shelling out to ` --help` +recursively (the same approach used by the agentgateway/website +generate-agctl-ref.py script, referenced as prior art in +kagent-dev/website#262). It works for any Cobra CLI without needing the +binary's root command to be an importable Go symbol, so it needs zero +changes upstream in kagent or kmcp. + +Usage: + generate-cli-docs.py --binary /path/to/kagent --display-name kagent \ + --out-dir docs-site/content/kagent/resources/cli + +Output layout matches the existing kagent-dev/website convention: + -.md +e.g. kagent get agent -> kagent-get-agent.md + +Each page gets Hugo YAML frontmatter (title/description/weight) plus a body +with the command's description, usage, flags, global flags and examples +extracted straight from --help text. Root-level commands are also linked +from an updated _index.md so the section stays navigable as commands are +added or removed. +""" +from __future__ import annotations + +import argparse +import os +import re +import subprocess +import sys +from dataclasses import dataclass, field +from pathlib import Path + +# Cobra/pflag prints a flag's *resolved* runtime default in --help output +# (e.g. --config's default is computed via os.UserHomeDir() at run time). +# That bakes whoever's machine generated the docs into the public page — +# a contributor's home directory locally, a CI runner's later. Replace it +# with the portable "$HOME" placeholder wherever it appears, since the +# CLI's own Long description text already documents it that way (e.g. +# "config file (default is $HOME/.kagent/config.yaml)"). +_HOME = os.path.expanduser("~") + + +@dataclass +class CommandNode: + path: list[str] # e.g. ["get", "agent"] + short: str = "" + long: str = "" + usage_lines: list[str] = field(default_factory=list) + examples: str = "" + flags: list[tuple[str, str]] = field(default_factory=list) + global_flags: list[tuple[str, str]] = field(default_factory=list) + children: list[str] = field(default_factory=list) # child command names (in order) + child_short: dict[str, str] = field(default_factory=dict) + + +FLAG_LINE_RE = re.compile(r"^\s{2,}(-[^\s].*?)\s{2,}(.*)$") + + +def run_help(binary: str, path: list[str]) -> str: + result = subprocess.run( + [binary, *path, "--help"], + capture_output=True, + text=True, + timeout=30, + ) + # Cobra prints help to stdout on success and (for some versions) may + # also echo it to stderr on usage errors; stdout is authoritative here. + text = result.stdout + if _HOME and _HOME != "/" and _HOME in text: + text = text.replace(_HOME, "$HOME") + return text + + +def parse_flag_block(lines: list[str]) -> list[tuple[str, str]]: + """Parse a cobra flag block into (flag, description) pairs, joining + wrapped description lines onto the preceding flag.""" + flags: list[tuple[str, str]] = [] + for line in lines: + if not line.strip(): + continue + m = FLAG_LINE_RE.match(line) + if m: + flags.append((m.group(1).strip(), m.group(2).strip())) + elif flags: + # Continuation of the previous flag's description (wrapped line). + flag, desc = flags[-1] + flags[-1] = (flag, f"{desc} {line.strip()}") + return flags + + +def parse_help(text: str, path: list[str]) -> CommandNode: + node = CommandNode(path=path) + lines = text.splitlines() + + section = None + seen_examples = False + desc_lines: list[str] = [] + usage_lines: list[str] = [] + example_lines: list[str] = [] + flag_lines: list[str] = [] + global_flag_lines: list[str] = [] + child_lines: list[str] = [] + + for line in lines: + stripped = line.strip() + # Normalize away trailing colons *and* internal whitespace before + # comparing: real-world Cobra templates aren't consistent here. + # kmcp emits "Available Commands::" (doubled colon) on one command + # and "GlobalFlags:" (no space) on another, so match on the header + # text stripped of all whitespace and trailing colons rather than + # an exact string. + header = re.sub(r"\s+", "", stripped.rstrip(":")).lower() + if header == "usage": + section = "usage" + continue + if header == "aliases": + section = "skip" + continue + if header in ("examples", "example"): + # Some CLIs (kagent's `init`, at least) emit a second, malformed + # "Examples:" section after Usage/Flags with a single unindented + # line duplicating part of the first block. Treat only the + # first Examples section as authoritative and ignore any repeat + # rather than concatenating both into one confusing block. + section = "examples" if not seen_examples else "skip" + seen_examples = True + continue + if header == "availablecommands": + section = "children" + continue + if header == "flags": + section = "flags" + continue + if header == "globalflags": + section = "global_flags" + continue + if stripped.startswith("Use \"") or stripped.startswith("Additional help"): + section = "skip" + continue + + if section is None: + desc_lines.append(line) + elif section == "usage": + if stripped: + usage_lines.append(stripped) + elif section == "examples": + example_lines.append(line) + elif section == "children": + if stripped: + child_lines.append(line) + elif section == "flags": + flag_lines.append(line) + elif section == "global_flags": + global_flag_lines.append(line) + # "skip" section: ignore (aliases, trailing "Use ... --help" hint) + + node.long = "\n".join(desc_lines).strip() + node.short = node.long.splitlines()[0] if node.long else "" + node.usage_lines = usage_lines + node.examples = "\n".join(example_lines).strip() + node.flags = parse_flag_block(flag_lines) + node.global_flags = parse_flag_block(global_flag_lines) + + for line in child_lines: + m = re.match(r"^\s{2}(\S+)\s+(.*)$", line) + if m: + name, short = m.group(1), m.group(2).strip() + # Skip cobra's built-in "help" meta-command: its help text is + # generic boilerplate ("help provides help for any command") + # with no kagent/kmcp-specific content. "completion" is kept — + # unlike "help" it documents real per-shell subcommands + # (bash/zsh/fish/powershell) that are genuinely useful reference + # content, and the existing hand-written docs already covered it. + if name == "help": + continue + node.children.append(name) + node.child_short[name] = short + + return node + + +def discover_tree(binary: str, path: list[str]) -> dict[tuple[str, ...], CommandNode]: + """BFS the command tree, returning a map of path-tuple -> CommandNode.""" + nodes: dict[tuple[str, ...], CommandNode] = {} + queue: list[list[str]] = [path] + while queue: + cur = queue.pop(0) + text = run_help(binary, cur) + node = parse_help(text, cur) + nodes[tuple(cur)] = node + for child in node.children: + queue.append(cur + [child]) + return nodes + + +def slugify(display_name: str, path: list[str]) -> str: + parts = [display_name, *path] + return "-".join(parts) + + +def render_flags(flags: list[tuple[str, str]]) -> str: + if not flags: + return "" + lines = [f"- `{flag}` - {desc}" for flag, desc in flags] + return "\n".join(lines) + + +def render_page(display_name: str, node: CommandNode, weight: int) -> str: + full_use = " ".join([display_name, *node.path]) + title = full_use + description = node.short or f"{full_use} command" + + body_parts = [node.long or description, ""] + + if node.usage_lines: + body_parts.append("```bash") + body_parts.extend(node.usage_lines) + body_parts.append("```") + body_parts.append("") + + if node.children: + body_parts.append("**Subcommands:**") + for child in node.children: + child_full = " ".join([display_name, *node.path, child]) + # Link to the clean Hugo path, one level up ("../"), not a + # same-level relative path. Every generated page lives flat in + # one output directory, but Hugo serves each as its own + # pretty-URL "directory" (trailing slash) rather than a flat + # file. From inside that directory, a same-level relative link + # like "kagent-get-agent/" resolves to a *subdirectory* of the + # current page (.../kagent-get/kagent-get-agent/), not the + # intended sibling page — confirmed against the actual resolved + # URL, not just the markdown source. "../kagent-get-agent/" is + # required to reach the sibling correctly. _index.md's own + # links (in main(), below) do NOT need this prefix: _index.md + # is served at the section URL itself, not one level inside it. + body_parts.append(f"- [`{child_full}`](../{slugify(display_name, node.path + [child])}/) - {node.child_short[child]}") + body_parts.append("") + + if node.flags: + body_parts.append("**Flags:**") + body_parts.append(render_flags(node.flags)) + body_parts.append("") + + if node.global_flags: + body_parts.append("**Global Flags:**") + body_parts.append(render_flags(node.global_flags)) + body_parts.append("") + + if node.examples: + body_parts.append("## Example") + body_parts.append("") + body_parts.append("```bash") + body_parts.append(node.examples) + body_parts.append("```") + body_parts.append("") + + body = "\n".join(body_parts).strip() + "\n" + + frontmatter = ( + "---\n" + f"title: {title}\n" + f"description: {description}\n" + f"weight: {weight}\n" + "---\n\n" + ) + return frontmatter + body + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--binary", required=True, help="Path to the built CLI binary") + parser.add_argument("--display-name", required=True, help="Command name as users type it, e.g. kagent or kmcp") + parser.add_argument("--out-dir", required=True, help="Hugo content directory to write pages into") + args = parser.parse_args() + + binary = str(Path(args.binary).resolve()) + out_dir = Path(args.out_dir) + out_dir.mkdir(parents=True, exist_ok=True) + + nodes = discover_tree(binary, []) + + # Remove previously generated pages so removed commands don't linger. + for existing in out_dir.glob(f"{args.display_name}-*.md"): + existing.unlink() + + # Weight root command's direct children 10, 20, 30... in help order; + # nested subcommands inherit weight+1 under their parent for stable + # ordering without needing to renumber the whole tree on every change. + root = nodes[tuple()] + weight = 10 + index_lines = [ + "---", + "title: CLI docs", + f"description: Complete reference docs for the {args.display_name} CLI commands", + "weight: 1", + "---", + "", + f"Review the {args.display_name} CLI commands and learn how to use them effectively.", + "", + ] + + def write_subtree(path: list[str], weight_start: int) -> int: + w = weight_start + node = nodes[tuple(path)] + page = render_page(args.display_name, node, w) + filename = f"{slugify(args.display_name, path)}.md" + (out_dir / filename).write_text(page) + w += 10 + for child in node.children: + w = write_subtree(path + [child], w) + return w + + for child in root.children: + # Same clean-path fix as the Subcommands links in render_page: a + # raw ".md" href doesn't resolve through Hugo's link rewriting. + index_lines.append(f"- [`{args.display_name} {child}`]({slugify(args.display_name, [child])}/) - {root.child_short[child]}") + weight = write_subtree([child], weight) + + (out_dir / "_index.md").write_text("\n".join(index_lines) + "\n") + + total_pages = len(list(out_dir.glob(f"{args.display_name}-*.md"))) + print(f"Generated {total_pages} pages for {args.display_name} in {out_dir}", file=sys.stderr) + return 0 + + +if __name__ == "__main__": + sys.exit(main())