README.md: Iterate on UX, pkg/cli: add colors, improve help text (#97)

# Description
Propose a change to the landing page of the project to make it more user
friendly

# Context
## README
Changes are fairly self-explanatory. I'm certainly open to feedback on
the structure or syntax. The goal was to approach this with a more "show
-over- tell". So instead of telling people what the value is of the
project, show how they can access it. For the most part, this content
existed before.

## devel/ folder
There was some really useful content in the top level README, but I felt
that it kind of diluted the message in that readme. My proposal here is
to take the content and move it to a dedicated area, and link to it from
the README

## CLI
The CLI now has some color, and an improved help text. 

For posterity, I used https://carbon.now.sh to generate the image in the
README representing the CLI

---------

Signed-off-by: Sam Heilbron <samheilbron@gmail.com>
Signed-off-by: Sam Heilbron <SamHeilbron@gmail.com>
Co-authored-by: Peter Jausovec <peterj@users.noreply.github.com>

Author: sam-heilbron

.githooks/prepare-commit-msg

@@ -0,0 +1,22 @@
+#!/bin/sh
+
+# This script automatically adds a Signed-off-by trailer to each commit message, so that your commits
+# will adhere to the DCO (Developer Certificate of Origin) requirements.
+# To use, run `make init-git-hooks` or copy this file to .git/hooks/prepare-commit-msg in your copy of the repo.
+
+NAME=$(git config user.name)
+EMAIL=$(git config user.email)
+
+if [ -z "$NAME" ]; then
+    echo "empty git config user.name"
+    exit 1
+fi
+
+if [ -z "$EMAIL" ]; then
+    echo "empty git config user.email"
+    exit 1
+fi
+
+git interpret-trailers --if-exists doNothing --trailer \
+    "Signed-off-by: $NAME <$EMAIL>" \
+    --in-place "$1"

Makefile

@@ -70,6 +70,12 @@ all: build
 help: ## Display this help.
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
+##@ Git
+
+.PHONY: init-git-hooks
+init-git-hooks:  ## Use the tracked version of Git hooks from this repo
+	git config core.hooksPath .githooks
+
 ##@ Development
 
 .PHONY: manifests

README.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD033 -->
 <div align="center">
   <picture>
     <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/kagent-dev/kmcp/main/img/kmcp-logo-dark.svg" alt="kmcp" width="400">
@@ -22,217 +23,134 @@
     </a>
   </div>
   <h3>A development platform and control plane for the Model Context Protocol (MCP)</h3>
-  <p>Build, deploy, and manage MCP servers with a seamless workflow from development to production</p>
+  <p><i>MCP connectivity simplified, bring MCP service prototypes into production</i></p>
 </div>
+<!-- markdownlint-enable MD033 -->
 
 ---
+<!-- markdownlint-disable MD033 -->
+<table align="center">
+  <tr>
+    <td>
+      <a href="#getting-started"><b><i>Getting Started</i></b></a>
+    </td>
+    <td>
+      <a href="#from-prototype-to-production"><b><i>Prototype to Production</i><b></a>
+    </td>
+    <td>
+      <a href="#technical-details"><b><i>Technical Details</i></b></a>
+    </td>
+    <td>
+      <a href="#get-involved"><b><i>Get Involved</i></b></a>
+    </td>
+    <td>
+      <a href="#reference"><b><i>Reference</i></b></a>
+    </td>
+  </tr>
+</table>
+<!-- markdownlint-disable MD033 -->
 
-## Overview
-
-`kmcp` is a comprehensive toolkit for building, deploying, and managing Model Context Protocol (MCP) servers. It provides a command-line interface (CLI) for local development and a Kubernetes controller for production deployments, enabling a seamless transition from development to production.
+---
 
-Whether you're building AI agent tools, deploying production MCP infrastructure, or managing multiple MCP servers at scale, `kmcp` streamlines the entire lifecycle with familiar tooling and cloud-native deployment patterns.
+## Why kMCP?
 
-<img src="img/kmcp.png" alt="kmcp architecture" width="800">
+Prototyping MPC services in isolation is quick and fun, but but production adoption introduces many challenges:
 
-## Why kmcp?
+- **Ad-hoc scaffolding** - Configuring the MCP server, integrating it in Kubernetes, and operating it at Enterprise scale
+- **Transport fragmentation** – Supporting multiple protocols (HTTP, WebSocket, SSE, etc.) requires custom maintenance.
+- **Disconnected context** - Enforcing consistent security, observability, and governance for agent-to-tool communication
 
-Building and deploying MCP servers today involves several challenges:
+**_We believe teams who have build MCP services should not experience friction when bringing those services to production. kMCP is designed to make MCP connectivity simple._**
 
-- **Manual scaffolding**: Setting up project structure, dependencies, and boilerplate code for each new MCP server
-- **Inconsistent deployment**: No standardized way to deploy MCP servers to production environments
-- **Transport complexity**: Handling different transport protocols (HTTP, WebSocket, SSE) requires custom implementation
-- **Kubernetes integration**: Manually creating deployments, services, and configurations for each MCP server
-- **Dev-prod parity**: Different setups for local development versus production deployment
+## Getting Started
 
-`kmcp` solves these problems by providing:
-
-- ✨ **Rapid scaffolding** with support for FastMCP (Python) and MCP Go SDK
-- 🚀 **One-command deployment** to Kubernetes with pre-configured Transport Adapters
-- 🔄 **Consistent workflow** from local development to production
-- 🌐 **Built-in transport support** for HTTP, WebSocket, and Server-Sent Events
-- ☸️ **Kubernetes-native** using Custom Resource Definitions (CRDs)
-- 🔐 **Secrets management** integrated with Kubernetes secrets
-
-## Quick Start
-
-Get started with `kmcp` in under a minute:
+Install the kmcp CLI on your local machine.
 
 ```bash
-# Install kmcp CLI
 curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash
-
-# Create a new MCP server
-kmcp init python my-weather-server
-
-# Navigate to your project
-cd my-weather-server
-
-# Add a tool
-kmcp add-tool get_weather --description "Get current weather for a location"
-
-# Run locally for testing
-kmcp run
-
-# Build and deploy to Kubernetes (requires cluster access)
-kmcp build
-kmcp install  # Install controller (one-time setup)
-kmcp deploy
 ```
 
-Your MCP server is now running locally! Edit the generated tool in `src/tools/get_weather.py` to implement your logic.
-
-## Core Concepts
-
-`kmcp` is composed of three primary components that work together to provide a complete MCP server-management solution:
-
-### 1. The `kmcp` CLI
-
-The CLI is your primary tool for local development. It allows you to scaffold new MCP projects, manage tools, build container images, and run your MCP server locally for testing and development.
-
-### 2.  The Kubernetes Controller
-
-The `kmcp` controller runs in your Kubernetes cluster and manages the lifecycle of your MCP server deployments. It uses a Custom Resource Definition (CRD) to define MCP servers as native Kubernetes objects, allowing you to manage them with familiar `kubectl` commands.
-
-### 3. The Transport Adapter
-
-In a Kubernetes environment, `kmcp` deploys your MCP server behind a dedicated Transport Adapter. `kmcp` acts as a control plane for this adapter, configuring it to provide  features such as external traffic routing for your MCP server with support for multiple transport protocols without requiring any changes to your code.
+Verify that the kmcp CLI is installed.
 
-## Features
-
-The `kmcp` CLI provides a set of commands to manage the entire lifecycle of your MCP server:
-
-| Command | Description |
-|---------|-------------|
-| `kmcp init` | Scaffolds a new MCP server project with FastMCP (Python) or MCP Go SDK |
-| `kmcp add-tool` | Adds a new tool to your project with automatic boilerplate and registration |
-| `kmcp run` | Runs the MCP server locally for development and testing |
-| `kmcp build` | Builds a Docker image for your MCP server |
-| `kmcp install` | Installs the `kmcp` controller and CRDs on a Kubernetes cluster (one-time setup) |
-| `kmcp deploy` | Deploys your MCP server to Kubernetes behind a pre-configured Transport Adapter |
-| `kmcp secrets` | Manages secrets for your MCP server deployment in Kubernetes |
-
-
-## Architecture
-
-The following diagram illustrates the `kmcp` workflow, from local development to a production deployment in Kubernetes:
-
-```mermaid
-graph TD
-    subgraph Local Development
-        A[Developer] -- kmcp init --> B(MCP Project);
-        B -- kmcp add-tool --> B;
-        B -- kmcp run --> C{Local MCP Server};
-        A -- Edits Code --> B;
-    end
-
-    subgraph Production Deployment
-        B -- kmcp build --> D[Docker Image];
-        D -- kmcp deploy --> E(Kubernetes Cluster);
-    end
+```bash
+kmcp --help
+```
 
-    subgraph Kubernetes Cluster
-        F[kmcp Controller] -- Manages --> G(MCP Server CRD);
-        G -- Deploys --> H[Transport Adapter];
-        H -- Proxies Traffic --> I[MCP Server Pod];
-    end
+<img src="img/cli-help-nov-25.png" alt="kmcp cli help text" width="800">
 
-    A -- Interacts with --> C;
-    E -- Contains --> F;
-    E -- Contains --> G;
-    E -- Contains --> H;
-    E -- Contains --> I;
-```
+_You're ready to go! Continue on to [From Prototype to Production](#from-prototype-to-production) or explore our docs at [kagent.dev/docs/kmcp](https://kagent.dev/docs/kmcp)_
 
-### How It Works
+## From Prototype to Production
 
-1. **Local Development**: Developers use `kmcp init` to scaffold a new project and `kmcp add-tool` to add tools. The server runs locally with `kmcp run` for rapid iteration.
+<img src="img/kmcp.png" alt="kmcp architecture" width="800">
 
-2. **Build Phase**: `kmcp build` packages your MCP server into a Docker image, handling all dependencies and configuration automatically.
+MCP connectivity affects everyone in an organization. Below are some common quickstart journeys that you may experience:
 
-3. **Deployment**: `kmcp deploy` creates a Kubernetes custom resource that the controller watches. The controller then:
-   - Deploys your MCP server as a pod
-   - Configures and deploys a Transport Adapter as a sidecar or separate service
-   - Sets up networking and ingress rules
-   - Manages secrets and environment variables
+- [Your first MCP service prototype](https://kagent.dev/docs/kmcp/develop)
+- [AI/ML Engineer packaging an existing prototype](https://kagent.dev/docs/kmcp/deploy/server#option-1-deploy-an-mcp-server-with-npx-or-uvx)
+- [DevOps engineer building MCP infrastructure in Kubernetes](https://kagent.dev/docs/kmcp/deploy/server#option-2-build-and-deploy-an-mcp-server)
 
-4. **Production Runtime**: The Transport Adapter receives external requests, handles protocol translation, and routes them to your MCP server. The controller continuously monitors and manages the deployment.
+## Technical Details
 
-## Use Cases
+`kmcp` is a comprehensive toolkit for building, deploying, and managing Model Context Protocol (MCP) servers. For a more detailed breakdown of using kmcp in your workflow, check out our [achitecture overview](/devel/architecture/workflow.md).
 
-`kmcp` is designed for:
+### Core Components
 
-- **AI/ML Engineers**: Building custom tools and integrations for AI agents with rapid iteration and testing
-- **Platform Teams**: Managing multiple MCP servers across development, staging, and production environments
-- **DevOps Engineers**: Deploying and scaling MCP infrastructure using familiar Kubernetes patterns
-- **Enterprise Organizations**: Standardizing MCP server development and deployment across teams
-- **Startups**: Quickly prototyping and deploying AI-powered features without infrastructure overhead
+- **[CLI](/pkg/cli/README.md)** is your primary tool for development. It allows you to scaffold new MCP projects, manage tools, build container images, and run your MCP server locally for testing and development.
+- **Controller**: Manages the lifecycle of your MCP server deployments in your Kubernetes cluster. It uses a Custom Resource Definition (CRD) to define MCP servers as native Kubernetes objects, allowing you to manage them with familiar `kubectl` commands.
+- **Transport Adapater** - Fronts the MCP server and provides features such as external traffic routing for your MCP server with support for multiple transport protocols without requiring any changes to your code.
 
-## Documentation
+### Core Principles
 
-The kmcp documentation is available at [kagent.dev/docs/kmcp](https://kagent.dev/docs/kmcp).
+- ✨ **Rapid scaffolding** with support for FastMCP (Python) and MCP Go SDK
+- 🚀 **One-command deployment** to Kubernetes with pre-configured Transport Adapters
+- 🔄 **Consistent workflow** from local development to production
+- 🌐 **Built-in transport support** for HTTP, WebSocket, and Server-Sent Events
+- ☸️ **Kubernetes-native** using Custom Resource Definitions (CRDs)
+- 🔐 **Secrets management** integrated with Kubernetes secrets
 
-## 🤝 Contributing
+## Get Involved
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+_We welcome contributions! Contributors are expected to [respect the kagent Code of Conduct](https://github.com/kagent-dev/community/blob/main/CODE-OF-CONDUCT.md)_
 
-### Ways to Contribute
+There are many ways to get involved:
 
-- 🐛 Report bugs and issues
-- 💡 Suggest new features
-- 📖 Improve documentation
-- 🔧 Submit pull requests
+- 🐛 [Report bugs and issues](https://github.com/kagent-dev/kmcp/issues/)
+- 💡 [Suggest new features](https://github.com/kagent-dev/kmcp/issues/)
+- 📖 [Improve documentation](https://github.com/kagent-dev/website/)
+- 🔧 [Submit pull requests](/CONTRIBUTING.md)
 - ⭐ Star the repository
-- 💬 Help others in Discord
+- 💬 [Help others in Discord](https://discord.gg/Fu3k65f2k3)
+- 💬 [Join the kagent community meetings](https://calendar.google.com/calendar/u/0?cid=Y183OTI0OTdhNGU1N2NiNzVhNzE0Mjg0NWFkMzVkNTVmMTkxYTAwOWVhN2ZiN2E3ZTc5NDA5Yjk5NGJhOTRhMmVhQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20)
+- 🤝 [Share tips in the CNCF #kagent slack channel](https://cloud-native.slack.com/archives/C08ETST0076)
+- 🔒 [Report security concerns](SECURITY.md)
 
 Thanks to all contributors!
 
 <a href="https://github.com/kagent-dev/kmcp/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=kagent-dev/kmcp" />
-</a>
-
-## 📈 Star History
-
-<a href="https://www.star-history.com/#kagent-dev/kmcp&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kagent-dev/kmcp&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kagent-dev/kmcp&type=Date" />
-   <img alt="Star history of kagent-dev/kmcp over time" src="https://api.star-history.com/svg?repos=kagent-dev/kmcp&type=Date" />
- </picture>
+  <img alt="kmcp contributors" src="https://contrib.rocks/image?repo=kagent-dev/kmcp" />
 </a>
 
-## 📄 License
-
-Copyright 2025.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+## Reference
 
-    http://www.apache.org/licenses/LICENSE-2.0
+### Resources
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+- [kMCP documentation](https://kagent.dev/docs/kmcp)
 
-## 🔗 Resources
+### Ecosystem Resources
 
 - [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
 - [MCP Documentation](https://modelcontextprotocol.io/)
 - [Anthropic's MCP Announcement](https://www.anthropic.com/news/model-context-protocol)
 - [FastMCP Python Documentation](https://github.com/jlowin/fastmcp)
 - [MCP Go SDK](https://github.com/mark3labs/mcp-go)
 
---- 
+### License
+
+This project is licensed under the [Apache 2.0 License.](/LICENSE)
+
+---
 
 <div align="center">
-  <p>Built with ❤️ by the kagent team</p>
-  <p>
-    <a href="https://kagent.dev">Website</a> •
-    <a href="https://kagent.dev/docs/kmcp">Documentation</a> •
-    <a href="https://discord.gg/Fu3k65f2k3">Discord</a> •
-    <a href="https://github.com/kagent-dev/kmcp">GitHub</a>
-  </p>
+  <p>Built with ❤️ by the <a href="https://github.com/kagent-dev">kagent team</a> </p>
 </div>

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+The kmcp project and broader kagent community takes security seriously! We appreciate your efforts to disclose your findings responsibly and will make every effort to acknowledge your contributions.
+
+Please refer to the [Kagent Community Security Policy](https://github.com/kagent-dev/community/blob/main/SECURITY.md) for instructions around how security vulnerabilities are reported to the project, evaluated by the team, and eventually disclosed to the public.

devel/architecture/workflow.md

@@ -0,0 +1,44 @@
+# kMCP Workflow
+
+The following diagram illustrates the `kmcp` workflow, from local development to a production deployment in Kubernetes:
+
+```mermaid
+graph TD
+    subgraph Local Development
+        A[Developer] -- kmcp init --> B(MCP Project);
+        B -- kmcp add-tool --> B;
+        B -- kmcp run --> C{Local MCP Server};
+        A -- Edits Code --> B;
+    end
+
+    subgraph Production Deployment
+        B -- kmcp build --> D[Docker Image];
+        D -- kmcp deploy --> E(Kubernetes Cluster);
+    end
+
+    subgraph Kubernetes Cluster
+        F[kmcp Controller] -- Manages --> G(MCP Server CRD);
+        G -- Deploys --> H[Transport Adapter];
+        H -- Proxies Traffic --> I[MCP Server Pod];
+    end
+
+    A -- Interacts with --> C;
+    E -- Contains --> F;
+    E -- Contains --> G;
+    E -- Contains --> H;
+    E -- Contains --> I;
+```
+
+## How It Works
+
+1. **Local Development**: Developers use `kmcp init` to scaffold a new project and `kmcp add-tool` to add tools. The server runs locally with `kmcp run` for rapid iteration.
+
+2. **Build Phase**: `kmcp build` packages your MCP server into a Docker image, handling all dependencies and configuration automatically.
+
+3. **Deployment**: `kmcp deploy` creates a Kubernetes custom resource that the controller watches. The controller then:
+   - Deploys your MCP server as a pod
+   - Configures and deploys a Transport Adapter as a sidecar or separate service
+   - Sets up networking and ingress rules
+   - Manages secrets and environment variables
+
+4. **Production Runtime**: The Transport Adapter receives external requests, handles protocol translation, and routes them to your MCP server. The controller continuously monitors and manages the deployment.