Merge pull request #60 from StacklokLabs/update-readme

JAORMX · web-flow · commit 0c2d60fff472 · 2025-06-30T22:36:28.000+03:00
Update README
diff --git a/README.md b/README.md
@@ -4,7 +4,9 @@
   <img src="docs/assets/mkp-logo.png" width="400" alt="MKP Logo">
 </p>
 
-MKP is a Model Context Protocol (MCP) server for Kubernetes that allows LLM-powered applications to interact with Kubernetes clusters. It provides tools for listing and applying Kubernetes resources through the MCP protocol.
+MKP is a Model Context Protocol (MCP) server for Kubernetes that allows
+LLM-powered applications to interact with Kubernetes clusters. It provides tools
+for listing and applying Kubernetes resources through the MCP protocol.
 
 ## Features
 
@@ -20,33 +22,39 @@ MKP is a Model Context Protocol (MCP) server for Kubernetes that allows LLM-powe
 
 ## Why MKP?
 
-MKP offers several key advantages as a Model Context Protocol server for Kubernetes:
+MKP offers several key advantages as a Model Context Protocol server for
+Kubernetes:
 
 ### Native Go Implementation
+
 - Built with the same language as Kubernetes itself
 - Excellent performance characteristics for server applications
 - Strong type safety and concurrency support
 - Seamless integration with Kubernetes libraries
 
 ### Direct API Integration
+
 - Uses Kubernetes API machinery directly without external dependencies
 - No reliance on kubectl, helm, or other CLI tools
 - Communicates directly with the Kubernetes API server
 - Reduced overhead and improved reliability
 
 ### Universal Resource Support
+
 - Works with any Kubernetes resource type through the unstructured client
 - No hardcoded resource schemas or specialized handlers needed
 - Automatically supports Custom Resource Definitions (CRDs)
 - Future-proof for new Kubernetes resources
 
 ### Minimalist Design
+
 - Focused on core Kubernetes resource operations
 - Clean, maintainable codebase with clear separation of concerns
 - Lightweight with minimal dependencies
 - Easy to understand, extend, and contribute to
 
 ### Production-Ready Architecture
+
 - Designed for reliability and performance in production environments
 - Proper error handling and resource management
 - Built-in rate limiting to protect against excessive API calls
@@ -63,22 +71,22 @@ MKP offers several key advantages as a Model Context Protocol server for Kuberne
 
 1. Clone the repository:
 
-```bash
-git clone https://github.com/StacklokLabs/mkp.git
-cd mkp
-```
+   ```bash
+   git clone https://github.com/StacklokLabs/mkp.git
+   cd mkp
+   ```
 
 2. Install dependencies:
 
-```bash
-task install
-```
+   ```bash
+   task install
+   ```
 
 3. Build the server:
 
-```bash
-task build
-```
+   ```bash
+   task build
+   ```
 
 ## Usage
 
@@ -97,6 +105,7 @@ KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig
 ```
 
 To run the server on a specific port:
+
 ```bash
 MCP_PORT=9091 task run
 ```
@@ -110,6 +119,7 @@ The MKP server provides the following MCP tools:
 Get a Kubernetes resource or its subresource.
 
 Parameters:
+
 - `resource_type` (required): Type of resource to get (clustered or namespaced)
 - `group`: API group (e.g., apps, networking.k8s.io)
 - `version` (required): API version (e.g., v1, v1beta1)
@@ -160,6 +170,7 @@ Example of getting logs from a specific container with parameters:
 ```
 
 Available parameters for pod logs:
+
 - `container`: Specify which container to get logs from
 - `previous`: Get logs from previous container instance (true/false)
 - `sinceSeconds`: Only return logs newer than a relative duration in seconds
@@ -168,16 +179,21 @@ Available parameters for pod logs:
 - `limitBytes`: Maximum number of bytes to return
 - `tailLines`: Number of lines to return from the end of the logs
 
-By default, pod logs are limited to the last 100 lines and 32KB to avoid overwhelming the LLM's context window. These defaults can be overridden using the parameters above.
+By default, pod logs are limited to the last 100 lines and 32KB to avoid
+overwhelming the LLM's context window. These defaults can be overridden using
+the parameters above.
 
 Available parameters for regular resources:
-- `resourceVersion`: When specified, shows the resource at that particular version
+
+- `resourceVersion`: When specified, shows the resource at that particular
+  version
 
 #### list_resources
 
 Lists Kubernetes resources of a specific type.
 
 Parameters:
+
 - `resource_type` (required): Type of resource to list (clustered or namespaced)
 - `group`: API group (e.g., apps, networking.k8s.io)
 - `version` (required): API version (e.g., v1, v1beta1)
@@ -204,7 +220,9 @@ Example:
 Applies (creates or updates) a Kubernetes resource.
 
 Parameters:
-- `resource_type` (required): Type of resource to apply (clustered or namespaced)
+
+- `resource_type` (required): Type of resource to apply (clustered or
+  namespaced)
 - `group`: API group (e.g., apps, networking.k8s.io)
 - `version` (required): API version (e.g., v1, v1beta1)
 - `resource` (required): Resource name (e.g., deployments, services)
@@ -264,10 +282,13 @@ Example:
 
 #### post_resource
 
-Posts to a Kubernetes resource or its subresource, particularly useful for executing commands in pods.
+Posts to a Kubernetes resource or its subresource, particularly useful for
+executing commands in pods.
 
 Parameters:
-- `resource_type` (required): Type of resource to post to (clustered or namespaced)
+
+- `resource_type` (required): Type of resource to post to (clustered or
+  namespaced)
 - `group`: API group (e.g., apps, networking.k8s.io)
 - `version` (required): API version (e.g., v1, v1beta1)
 - `resource` (required): Resource name (e.g., deployments, services)
@@ -300,11 +321,16 @@ Example of executing a command in a pod:
 ```
 
 The `body` for pod exec supports the following fields:
-- `command` (required): Command to execute, either as a string or an array of strings
-- `container` (optional): Container name to execute the command in (defaults to the first container)
-- `timeout` (optional): Timeout in seconds (defaults to 15 seconds, maximum 60 seconds)
+
+- `command` (required): Command to execute, either as a string or an array of
+  strings
+- `container` (optional): Container name to execute the command in (defaults to
+  the first container)
+- `timeout` (optional): Timeout in seconds (defaults to 15 seconds, maximum 60
+  seconds)
 
 Note on timeouts:
+
 - Default timeout: 15 seconds if not specified
 - Maximum timeout: 60 seconds (any larger value will be capped)
 - Commands that exceed the timeout will be terminated and return a timeout error
@@ -332,16 +358,20 @@ The response includes stdout, stderr, and any error message:
 
 ### MCP Resources
 
-The MKP server provides access to Kubernetes resources through MCP resources. The resource URIs follow these formats:
+The MKP server provides access to Kubernetes resources through MCP resources.
+The resource URIs follow these formats:
 
 - Clustered resources: `k8s://clustered/{group}/{version}/{resource}/{name}`
-- Namespaced resources: `k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}`
+- Namespaced resources:
+  `k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}`
 
 ### Configuration
 
 #### Controlling Resource Discovery
 
-By default, MKP serves all Kubernetes resources as MCP resources, which provides useful context for LLMs. However, in large clusters with many resources, this can consume significant context space in the LLM.
+By default, MKP serves all Kubernetes resources as MCP resources, which provides
+useful context for LLMs. However, in large clusters with many resources, this
+can consume significant context space in the LLM.
 
 You can disable this behavior by using the `--serve-resources` flag:
 
@@ -353,11 +383,16 @@ You can disable this behavior by using the `--serve-resources` flag:
 ./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false
 ```
 
-Even with resource discovery disabled, the MCP tools (`get_resource`, `list_resources`, `apply_resource`, `delete_resource`, and `post_resource`) remain fully functional, allowing you to interact with your Kubernetes cluster.
+Even with resource discovery disabled, the MCP tools (`get_resource`,
+`list_resources`, `apply_resource`, `delete_resource`, and `post_resource`)
+remain fully functional, allowing you to interact with your Kubernetes cluster.
 
 #### Enabling Write Operations
 
-By default, MKP operates in read-only mode, meaning it does not allow write operations on the cluster, i.e. the `apply_resource`, `delete_resource`, and `post_resource` tools will not be available. You can enable write operations by using the `--read-write` flag:
+By default, MKP operates in read-only mode, meaning it does not allow write
+operations on the cluster, i.e. the `apply_resource`, `delete_resource`, and
+`post_resource` tools will not be available. You can enable write operations by
+using the `--read-write` flag:
 
 ```bash
 # Run with write operations enabled
@@ -369,13 +404,18 @@ By default, MKP operates in read-only mode, meaning it does not allow write oper
 
 ### Rate Limiting
 
-MKP includes a built-in rate limiting mechanism to protect the server from excessive API calls, which is particularly important when used with AI agents. The rate limiter uses a token bucket algorithm and applies different limits based on the operation type:
+MKP includes a built-in rate limiting mechanism to protect the server from
+excessive API calls, which is particularly important when used with AI agents.
+The rate limiter uses a token bucket algorithm and applies different limits
+based on the operation type:
 
 - Read operations (list_resources, get_resource): 120 requests per minute
 - Write operations (apply_resource, delete_resource): 30 requests per minute
 - Default for other operations: 60 requests per minute
 
-Rate limits are applied per client session, ensuring fair resource allocation across multiple clients. The rate limiting feature can be enabled or disabled via the command line flag:
+Rate limits are applied per client session, ensuring fair resource allocation
+across multiple clients. The rate limiting feature can be enabled or disabled
+via the command line flag:
 
 ```bash
 # Run with rate limiting enabled (default)
@@ -413,21 +453,26 @@ task deps
 
 ## Running as an MCP Server with ToolHive
 
-MKP can be run as a Model Context Protocol (MCP) server using [ToolHive](https://github.com/stacklok/toolhive), which simplifies the deployment and management of MCP servers.
+MKP can be run as a Model Context Protocol (MCP) server using
+[ToolHive](https://github.com/stacklok/toolhive), which simplifies the
+deployment and management of MCP servers.
 
 ### Prerequisites
 
-1. Install ToolHive by following the [installation instructions](https://github.com/stacklok/toolhive#installation).
+1. Install ToolHive by following the
+   [installation instructions](https://docs.stacklok.com/toolhive/guides-cli/install).
 2. Ensure you have Docker or Podman installed on your system.
-3. Configure your Kubernetes credentials (kubeconfig) for the cluster you want to interact with.
+3. Configure your Kubernetes credentials (kubeconfig) for the cluster you want
+   to interact with.
 
 ### Running MKP with ToolHive (Recommended)
 
-The easiest way to run MKP is using the packaged version available in ToolHive's registry:
+The easiest way to run MKP is using the packaged version available in ToolHive's
+registry:
 
 ```bash
-# Enable auto-discovery to automatically configure supported clients
-thv config auto-discovery true
+# Register a supported client so ToolHive can auto-configure your environment
+thv client setup
 
 # Run the MKP server (packaged as 'k8s' in ToolHive)
 # Mount your kubeconfig so the server can access your Kubernetes cluster
@@ -440,18 +485,21 @@ thv list
 thv registry info k8s
 ```
 
-This will mount your Kubernetes credentials and make the server available to your MCP-compatible clients.
+This will mount your Kubernetes credentials and make the server available to
+your MCP-compatible clients.
 
 ### Advanced Usage with Custom Configuration
 
-For advanced users who need custom configuration, you can also run MKP using the container image directly:
+For advanced users who need custom configuration, you can also run MKP using the
+container image directly:
 
 ```bash
 # Run the MKP server using the published container image
 thv run --name mkp --transport sse --target-port 8080 --volume $HOME/.kube:/home/nonroot/.kube:ro ghcr.io/stackloklabs/mkp/server:latest
 ```
 
 This command:
+
 - Names the server instance "mkp"
 - Uses the SSE transport protocol
 - Mounts your local kubeconfig into the container (read-only)
@@ -471,7 +519,8 @@ To verify that the MKP server is running:
 thv list
 ```
 
-This will show all running MCP servers managed by ToolHive, including the MKP server.
+This will show all running MCP servers managed by ToolHive, including the MKP
+server.
 
 To stop the MKP server:
 
@@ -493,17 +542,18 @@ thv rm k8s
 thv rm mkp
 ```
 
-
 ## Contributing
 
-We welcome contributions to this MCP server! If you'd like to contribute, please review
-the [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get started.
+We welcome contributions to this MCP server! If you'd like to contribute, please
+review the [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get
+started.
 
 If you run into a bug or have a feature request, please
-[open an issue](https://github.com/StacklokLabs/mkp/issues) in the
-repository or join us in the `#mcp-servers` channel on our
+[open an issue](https://github.com/StacklokLabs/mkp/issues) in the repository or
+join us in the `#mcp-servers` channel on our
 [community Discord server](https://discord.gg/stacklok).
 
 ## License
 
-This project is licensed under the Apache v2 License - see the LICENSE file for details.
+This project is licensed under the Apache v2 License - see the LICENSE file for
+details.
