Update README.md

Following details are added to the README.md file:
- Table of contents
- `How to connect to the MCP Server` section is updated to use go run github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest instead of local binary
- `Tools available in MCP Server` is added providing details about the tools available

The generation of the `Tools available in MCP Server` section is automated and a make target is added to update the section.
The package naming of the different layers are also made consistent so that the automation can pick the correct names.
A github workflow is added to check if the section needs update or not.

Additionaly, `both` mode is now renamed to a more intuitive `dual` mode.

Assisted-by: Cursor

Signed-off-by: arkadeepsen <arsen@redhat.com>

Author: arkadeepsen

.github/workflows/readme-tools.yml

@@ -0,0 +1,34 @@
+name: README tools check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  readme-tools:
+    name: README tools section up to date
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: false
+
+      - name: Update README tools section
+        run: make update-readme-tools
+
+      - name: Check for changes
+        run: |
+          if ! git diff --exit-code README.md; then
+            echo "::error::README.md tools section is out of date. Run 'make update-readme-tools' and commit the changes."
+            exit 1
+          fi

Makefile

@@ -61,6 +61,10 @@ else
 	echo "linter can only be run within a container since it needs a specific golangci-lint version"; exit 1
 endif
 
+.PHONY: update-readme-tools
+update-readme-tools:
+	go run ./hack/gen-readme-tools.go
+
 .PHONY: lint-fix
 lint-fix:
 ifeq ($(CONTAINER_RUNNABLE), 0)

README.md

@@ -1,21 +1,49 @@
 # ovn-kubernetes-mcp
-Repo hosting the Model Context Protocol Server for troubleshooting OVN-Kubernetes
 
-## How to connect to the MCP Server
+Repo hosting the Model Context Protocol Server for troubleshooting OVN-Kubernetes.
 
-For connecting to the MCP server, the following steps are required:
+## Table of Contents
 
-```shell
-make build
-```
+- [Operating Modes](#operating-modes)
+- [How to connect to the MCP Server](#how-to-connect-to-the-mcp-server)
+  - [Command-line options](#command-line-options)
+  - [Live Cluster Mode](#live-cluster-mode)
+  - [Offline Mode](#offline-mode)
+  - [Dual Mode](#dual-mode)
+  - [Local development](#local-development)
+- [Tools available in MCP Server](#tools-available-in-mcp-server)
+  - [Live Cluster Mode](#live-cluster-mode-1)
+  - [Offline Mode](#offline-mode-1)
+
+---
 
-The server supports 3 operating modes:
-- `live-cluster` (default): Connect to a live Kubernetes cluster for real-time debugging
-- `offline`: Offline troubleshooting without requiring cluster access
-- `both`: In this mode, tools from both `live-cluster` and `offline` modes will be available.
+## Operating Modes
+
+| Mode                     | Description |
+|--------------------------|-------------|
+| `live-cluster` (default) | Connect to a live Kubernetes cluster for real-time debugging (requires kubeconfig). |
+| `offline`                | Analyze sosreports and must-gathers without cluster access. |
+| `dual`                   | Exposes tools from dual live-cluster and offline modes (requires kubeconfig for live-cluster tools). |
+
+---
+
+## How to connect to the MCP Server
+
+To use the MCP server, ensure you have [Go](https://go.dev/) installed with a version greater than or equal to the version specified in the `go.mod` file.
 
 The server currently supports 2 transport modes: `stdio` and `http`.
 
+### Command-line options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--mode` | `live-cluster` | Server mode: `live-cluster`, `offline`, or `dual`. |
+| `--transport` | `stdio` | Transport: `stdio` or `http`. |
+| `--port` | `8080` | Port for HTTP transport. |
+| `--kubeconfig` | (none) | Path to kubeconfig file. Required for `live-cluster` and `dual`. |
+| `--pwru-image` | `docker.io/cilium/pwru:v1.0.10` | Container image for the **pwru** network tool (kernel packet tracing). |
+| `--tcpdump-image` | `nicolaka/netshoot:v0.13` | Container image for the **tcpdump** network tool (packet capture). |
+
 ### Live Cluster Mode
 
 For `stdio` mode, the server can be run and connected to by using the following configuration in an MCP host (Cursor, Claude, etc.):
@@ -24,8 +52,10 @@ For `stdio` mode, the server can be run and connected to by using the following
 {
   "mcpServers": {
     "ovn-kubernetes": {
-      "command": "/PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server",
+      "command": "go",
       "args": [
+        "run",
+        "github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest",
         "--kubeconfig",
         "/PATH-TO-THE-KUBECONFIG-FILE"
       ]
@@ -37,7 +67,7 @@ For `stdio` mode, the server can be run and connected to by using the following
 For `http` mode, the server should be started separately:
 
 ```shell
-./PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server --transport http --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE
+go run github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest --transport http --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE
 ```
 
 The following configuration should be used in an MCP host (Cursor, Claude, etc.) to connect to the server:
@@ -62,8 +92,13 @@ For `stdio` mode:
 {
   "mcpServers": {
     "ovn-kubernetes": {
-      "command": "/PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server",
-      "args": ["--mode", "offline"]
+      "command": "go",
+      "args": [
+        "run",
+        "github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest",
+        "--mode",
+        "offline"
+      ]
     }
   }
 }
@@ -72,25 +107,27 @@ For `stdio` mode:
 For `http` mode:
 
 ```shell
-./PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server --transport http --mode offline
+go run github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest --transport http --mode offline
 ```
 
-> NOTE: For must-gather tools to be added, availability of [`omc`](https://github.com/gmeghnag/omc) binary is mandatory. Otherwise, the must-gather tools will not be added to the MCP server. Additionally, if [`ovsdb-tool`](https://www.openvswitch.org/support/dist-docs/ovsdb-tool.1.txt) binary is not available, then some of the must-gather tools, which use `ovsdb-tool` binary, will not be added to the MCP server.
+> **Note:** Must-gather tools require the [`omc`](https://github.com/gmeghnag/omc) binary. Some must-gather tools also require the [`ovsdb-tool`](https://www.openvswitch.org/support/dist-docs/ovsdb-tool.1.txt) binary; if it is not available, those tools are not registered.
 
-### Both Mode
+### Dual Mode
 
-For using both [live-cluster](#live-cluster-mode) (needs kubeconfig) and [offline](#offline-mode) tools, use `--mode both`:
+For using dual [live-cluster](#live-cluster-mode) (needs kubeconfig) and [offline](#offline-mode) tools, use `--mode dual`:
 
 For `stdio` mode:
 
 ```json
 {
   "mcpServers": {
     "ovn-kubernetes": {
-      "command": "/PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server",
+      "command": "go",
       "args": [
+        "run",
+        "github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest",
         "--mode",
-        "both",
+        "dual",
         "--kubeconfig",
         "/PATH-TO-THE-KUBECONFIG-FILE"
       ]
@@ -102,5 +139,92 @@ For `stdio` mode:
 For `http` mode:
 
 ```shell
-./PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server --transport http --mode both --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE
+go run github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest --transport http --mode dual --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE
 ```
+
+### Local development
+
+When developing or building locally, run `make build` and use the binary path as the command.
+
+- Use `--mode <live-cluster|offline|dual>` to choose the mode.
+- For `live-cluster` or `dual`, add `--kubeconfig /path/to/kubeconfig`.
+- For `offline`, omit `--kubeconfig`.
+
+**stdio:**
+
+```json
+{
+  "mcpServers": {
+    "ovn-kubernetes": {
+      "command": "/PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server",
+      "args": [
+        "--mode",
+        "<live-cluster|offline|dual>",
+        "--kubeconfig",
+        "/PATH-TO-THE-KUBECONFIG-FILE"
+      ]
+    }
+  }
+}
+```
+
+**http:**
+
+```shell
+/PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server --transport http --mode <live-cluster|offline|dual> --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE
+```
+
+For `offline` mode, omit the `--kubeconfig` argument in dual examples above.
+
+---
+
+<!-- TOOLS_SECTION_START -->
+## Tools available in MCP Server
+
+### Live Cluster Mode
+
+Available when running with `--mode live-cluster` or `--mode dual` (and with a valid kubeconfig).
+
+| Category      | Tool | Description |
+|---------------|------|-------------|
+| **Kubernetes** | `pod-logs` | Get container logs from a pod in the Kubernetes cluster. |
+| | `resource-get` | Get a specific Kubernetes resource by name. |
+| | `resource-list` | List Kubernetes resources of a specific kind. |
+| **Ovn** | `ovn-show` | Display a comprehensive overview of OVN configuration from either the Northbound or Southbound database. |
+| | `ovn-get` | Query records from an OVN database table with flexible filtering. |
+| | `ovn-lflow-list` | List logical flows from the OVN Southbound database. |
+| | `ovn-trace` | Trace a packet through the OVN logical network. |
+| **Ovs** | `ovs-list-br` | List all OVS bridges on a specific pod. |
+| | `ovs-list-ports` | List all ports on a specific OVS bridge. |
+| | `ovs-list-ifaces` | List all interfaces on a specific OVS bridge. |
+| | `ovs-vsctl-show` | Display a comprehensive overview of OVS configuration. |
+| | `ovs-ofctl-dump-flows` | Dump OpenFlow flows from a specific OVS bridge. |
+| | `ovs-appctl-dump-conntrack` | Dump connection tracking entries from OVS datapath. |
+| | `ovs-appctl-ofproto-trace` | Trace a packet through the OpenFlow pipeline. |
+| **Kernel** | `get-conntrack` | get-conntrack allows to interact with the connection tracking system of a Kubernetes node. |
+| | `get-iptables` | get-iptables allows to interact with kernel to list packet filter rules. |
+| | `get-nft` | get-nft allows to interact with kernel to list packet filtering and classification rules. |
+| | `get-ip` | get-ip allows to interact with kernel to list routing, network devices, interfaces. |
+| **Network Tools** | `tcpdump` | Capture network packets on a node or inside a pod with strict safety controls. |
+| | `pwru` | Trace packets through the Linux kernel networking stack using eBPF. |
+
+### Offline Mode
+
+Available when running with `--mode offline` or `--mode dual`. No cluster access required.
+
+| Category       | Tool | Description |
+|----------------|------|-------------|
+| **Sosreport** | `sos-list-plugins` | List enabled sosreport plugins with their command counts. |
+| | `sos-list-commands` | List all commands collected by a specific sosreport plugin. |
+| | `sos-search-commands` | Search for commands across all plugins by pattern. |
+| | `sos-get-command` | Get command output using filepath from manifest. |
+| | `sos-search-pod-logs` | Search Kubernetes pod container logs. |
+| **Must Gather** | `must-gather-get-resource` | Get a specific Kubernetes resource from a must-gather archive. |
+| | `must-gather-list-resources` | List Kubernetes resources of a specific kind from a must-gather archive. |
+| | `must-gather-pod-logs` | Get container logs from a pod in a must-gather archive. |
+| | `must-gather-ovnk-info` | Get OVN-Kubernetes networking information from a must-gather archive. |
+| | `must-gather-list-northbound-databases` | List OVN Northbound database files available in a must-gather archive. |
+| | `must-gather-list-southbound-databases` | List OVN Southbound database files available in a must-gather archive. |
+| | `must-gather-query-database` | Query an OVN database from a must-gather archive using ovsdb-tool. |
+
+<!-- TOOLS_SECTION_END -->

cmd/ovnk-mcp-server/main.go

@@ -14,7 +14,7 @@ import (
 	kernelmcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/kernel/mcp"
 	kubernetesmcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/kubernetes/mcp"
 	mustgathermcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/must-gather/mcp"
-	nettoolsmcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/nettools/mcp"
+	nettoolsmcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/network-tools/mcp"
 	ovnmcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/ovn/mcp"
 	ovsmcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/ovs/mcp"
 	sosreportmcp "github.com/ovn-kubernetes/ovn-kubernetes-mcp/pkg/sosreport/mcp"
@@ -84,11 +84,11 @@ func main() {
 		setupLiveCluster(serverCfg, ovnkMcpServer)
 	case "offline":
 		setupOffline(ovnkMcpServer)
-	case "both":
+	case "dual":
 		setupLiveCluster(serverCfg, ovnkMcpServer)
 		setupOffline(ovnkMcpServer)
 	default:
-		log.Fatalf("Invalid mode: %s. Valid modes are: live-cluster, offline, both", serverCfg.Mode)
+		log.Fatalf("Invalid mode: %s. Valid modes are: live-cluster, offline, dual", serverCfg.Mode)
 	}
 
 	// Create a context that can be cancelled to shutdown the server.
@@ -143,7 +143,7 @@ func main() {
 
 func parseFlags() *MCPServerConfig {
 	cfg := &MCPServerConfig{}
-	flag.StringVar(&cfg.Mode, "mode", "live-cluster", "Mode of debugging: live-cluster or offline or both")
+	flag.StringVar(&cfg.Mode, "mode", "live-cluster", "Mode of debugging: live-cluster or offline or dual")
 	flag.StringVar(&cfg.Transport, "transport", "stdio", "Transport to use: stdio or http")
 	flag.StringVar(&cfg.Port, "port", "8080", "Port to use")
 	flag.StringVar(&cfg.Kubernetes.Kubeconfig, "kubeconfig", "", "Path to the kubeconfig file")