Skip to content

update readme #94

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

update readme #94

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 119 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,36 +21,97 @@
<img src="https://img.shields.io/discord/1346225185166065826?style=flat&label=Join%20Discord&color=6D28D9" alt="Discord">
</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>
</div>

---

# kmcp

**A development platform and control plane for the Model Context Protocol (MCP)**
## 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.

<img src="img/kmcp.png" alt="kmcp architecture" width="800">

## Why kmcp?

Building and deploying MCP servers today involves several challenges:

- **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

`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:

```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 pytohn my-weather-server
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
kmcp init pytohn my-weather-server
kmcp init python my-weather-server


Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps more of a CLI question: should we clarify what files/directories are generated, so the user is aware there are side effects to the initialization?

# 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.
### 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.

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

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.
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.

## Features (CLI Command Overview)
## Features

The `kmcp` CLI provides a set of commands to manage the entire lifecycle of your MCP server:

- `kmcp init`: Scaffolds a new MCP server project. Supported frameworks include [FastMCP](https://github.com/jlowin/fastmcp) for Python and the [official MCP Go SDK](https://github.com/mark3labs/mcp-go) for Go.
- `kmcp add-tool`: Adds a new tool to your project, automatically handling boilerplate and registration.
- `kmcp run`: Runs the MCP server in a local development environment.
- `kmcp build`: Builds a Docker image for your MCP server.
- `kmcp install`: Installs the `kmcp` controller and CRDs on a Kubernetes cluster.
- `kmcp deploy`: Deploys your MCP server to a Kubernetes cluster, placing it behind a pre-configured Transport Adapter.
- `kmcp secrets`: Manages secrets for your MCP server deployment in Kubernetes.
| 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

Expand Down Expand Up @@ -83,10 +144,29 @@ graph TD
E -- Contains --> I;
```

## Get started
### 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

- [Quick Start](https://kagent.dev/docs/kmcp/quickstart)
- [Installation Guide](https://kagent.dev/docs/kmcp/deploy/install-controller)
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.

## Use Cases

`kmcp` is designed for:

- **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

## Documentation

Expand All @@ -96,6 +176,15 @@ The kmcp documentation is available at [kagent.dev/docs/kmcp](https://kagent.dev

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Ways to Contribute

- 🐛 Report bugs and issues
- 💡 Suggest new features
- 📖 Improve documentation
- 🔧 Submit pull requests
- ⭐ Star the repository
- 💬 Help others in Discord

Thanks to all contributors!

<a href="https://github.com/kagent-dev/kmcp/graphs/contributors">
Expand Down Expand Up @@ -134,3 +223,16 @@ limitations under the License.
- [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)

---

<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>
</div>
Binary file added img/kmcp.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading