agent-tools

OCI packaging CLI and MCP tool servers for the AgentOps platform.

This repository contains MCP tool servers that AI agents consume at runtime and a CLI for packaging and pushing them as OCI artifacts to container registries. All servers are compiled Go binaries implementing the MCP stdio transport, compatible with the Fantasy runtime and any MCP-aware client.

Architecture

              BUILD / PUSH TIME                           DEPLOY / RUNTIME
             (this repository)                          (agentops-core operator)

 MCP Server Source                  OCI Registry                Agent Pod
 ┌─────────────────────┐     ┌──────────────────────┐    ┌──────────────────────┐
 │ servers/kube-explore/│     │ ghcr.io/myorg/       │    │                      │
 │   main.go            │────>│   agent-tools/       │    │  init container      │
 │   manifest.json      │     │   kube-explore:0.2.0 │───>│    pulls OCI layer   │
 │                      │     │                      │    │    extracts to       │
 │ servers/git/         │     │   agent-tools/       │    │      /tools/         │
 │   main.go            │────>│     git:0.2.0        │───>│                      │
 └─────────────────────┘     └──────────────────────┘    └──────────────────────┘

Repository Structure

agent-tools/
  cmd/agent-tools/        # CLI binary
    main.go               #   Root command + version
    push.go               #   Push command (validate, package, push)
  internal/oci/           # OCI packaging engine
    pusher.go             #   Validation, manifest building, ORAS push
    archive.go            #   tar+gzip archive creation
    credentials.go        #   Docker config credential loading
    reference.go          #   OCI reference parsing
  servers/                # MCP tool servers
    kube-explore/         #   Intent-based Kubernetes discovery
    kubectl/              #   kubectl CLI (readonly + readwrite modes)
    flux/                 #   Flux CD GitOps (readonly + readwrite modes)
    git/                  #   Git operations
    github/               #   GitHub API
    gitlab/               #   GitLab API
  Makefile                # Build, test, push workflows
  .github/workflows/      # CI + Release pipelines

CLI

Installation

Download a pre-built binary from the releases page, or build from source:

make build

Usage

agent-tools push [directory] -t <oci-ref>

Flag	Short	Description
`--tag`	`-t`	Required. Full OCI reference (e.g. `ghcr.io/myorg/agent-tools/kube-explore:0.2.0`)
`--plain-http`		Use HTTP instead of HTTPS for the registry

Authentication is loaded from ~/.docker/config.json.

Example

# Build the server binary
cd servers/kube-explore
CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o dist/bin/kube-explore .
cp manifest.json dist/

# Push to registry
agent-tools push ./dist/ -t ghcr.io/myorg/agent-tools/kube-explore:0.2.0

Or use the Makefile:

make build-server SERVER=kube-explore
make push-server SERVER=kube-explore TAG=0.2.0

Pushed artifacts can be referenced in Agent CRDs:

spec:
  toolRefs:
    - name: kube-explore
      ref: ghcr.io/myorg/agent-tools/kube-explore:0.2.0

OCI Artifact Format

Field	Value
Artifact Type	`application/vnd.agents.io.mcp-tool.v1`
Layer Media Type	`application/vnd.agents.io.mcp-tool.code.v1.tar+gzip`
Config Media Type	`application/vnd.agents.io.mcp-tool.config.v1+json`

Source Validation

Directories must contain:

manifest.json -- server metadata
bin/ directory with at least one executable

MCP Servers

All servers are compiled Go binaries implementing the MCP stdio transport. Each is a separate Go module with its own go.mod and includes a manifest.json:

{
  "name": "kube-explore",
  "command": "kube-explore",
  "transport": "stdio",
  "description": "Intent-based Kubernetes discovery & operations"
}

Server	Tools Provided
`servers/kube-explore`	`kube_find`, `kube_health`, `kube_inspect`, `kube_topology`, `kube_diff`, `kube_logs`, `kube_exec`, `kube_apply`
`servers/kubectl`	readonly: `kubectl_get`, `kubectl_describe`, `kubectl_logs`, `kubectl_top`, `kubectl_events`, `kubectl_api_resources`, `kubectl_explain` -- readwrite (MODE=readwrite): + `kubectl_exec`, `kubectl_apply`, `kubectl_delete`, `kubectl_run`, `kubectl_cp`, `kubectl_rollout`, `kubectl_scale`, `kubectl_label`, `kubectl_annotate`
`servers/flux`	readonly: `flux_get`, `flux_check`, `flux_stats`, `flux_logs`, `flux_events`, `flux_trace`, `flux_tree`, `flux_diff`, `flux_export`, `flux_debug`, `flux_version` -- readwrite (MODE=readwrite): + `flux_reconcile`, `flux_suspend`, `flux_resume`, `flux_delete`
`servers/git`	`git_status`, `git_diff`, `git_log`, `git_add`, `git_commit`, `git_push`, `git_pull`, `git_branch`, `git_branch_list`, `git_show`, `git_clone`, `git_clone_or_pull`
`servers/github`	`github_get_repo`, `github_list_prs`, `github_get_pr`, `github_get_pr_diff`, `github_create_pr`, `github_add_pr_comment`, `github_list_issues`, `github_get_issue`, `github_add_issue_comment`, `github_list_branches`, `github_get_check_runs`, `github_get_workflow_runs`
`servers/gitlab`	`gitlab_get_project`, `gitlab_list_mrs`, `gitlab_get_mr`, `gitlab_get_mr_diff`, `gitlab_create_mr`, `gitlab_add_mr_note`, `gitlab_list_issues`, `gitlab_get_issue`, `gitlab_add_issue_note`, `gitlab_get_pipeline`

kube-explore

Intent-based Kubernetes discovery server designed to answer complex questions in a single call.

Fuzzy matching -- Accepts partial names, label selectors, and status keywords (failing, crash, oom, pending, etc.)
Parallel scanning -- Searches across all namespaces concurrently
Relationship traversal -- Walks owner references and discovers related resources (Services, Ingresses, PVCs, ConfigMaps)
Native AgentOps CRD support -- Understands agents, agentruns, channels, and mcpservers resources
Deep inspection -- kube_inspect returns logs, events, owner chain, and related resources in one response
Cluster health -- kube_health provides a full cluster health snapshot

kubectl

General-purpose kubectl MCP server with two operating modes:

MODE=readonly (default) -- Safe observability tools only. The agent can inspect, query, and diagnose but cannot modify anything.
MODE=readwrite -- All readonly tools plus mutating operations (exec, apply, delete, scale, etc.).

Readonly tools

Tool	Description
`kubectl_get`	Get resources with selectors, output formats, all-namespaces
`kubectl_describe`	Detailed resource information including events/conditions
`kubectl_logs`	Pod logs with tail, since, previous, container selection
`kubectl_top`	CPU/memory usage for pods and nodes
`kubectl_events`	Cluster events filtered by namespace, resource, or type
`kubectl_api_resources`	List available API resource types
`kubectl_explain`	Describe resource type fields

Readwrite tools (MODE=readwrite only)

Tool	Description
`kubectl_exec`	Execute commands in running containers (with timeout)
`kubectl_apply`	Apply YAML/JSON manifests (supports dry-run)
`kubectl_delete`	Delete resources by name or selector (supports force)
`kubectl_run`	Run one-off pods with a command
`kubectl_cp`	Copy files to/from containers
`kubectl_rollout`	Rollout management: status, history, undo, restart
`kubectl_scale`	Scale deployments, replicasets, statefulsets
`kubectl_label`	Add/update/remove labels
`kubectl_annotate`	Add/update/remove annotations

Usage

# Readonly (safe for any agent)
spec:
  toolRefs:
    - name: kubectl
      ref: ghcr.io/myorg/agent-tools/kubectl:0.3.0

# Readwrite (agent can modify cluster state)
spec:
  toolRefs:
    - name: kubectl
      ref: ghcr.io/myorg/agent-tools/kubectl:0.3.0
      env:
        - name: MODE
          value: readwrite

flux

Flux CD GitOps MCP server with two operating modes:

MODE=readonly (default) -- Observe and diagnose Flux resources without modifying anything.
MODE=readwrite -- All readonly tools plus reconcile, suspend, resume, and delete.

Readonly tools

Tool	Description
`flux_get`	Get Flux resources: all, helmreleases, kustomizations, sources, alerts, receivers, images
`flux_check`	Check Flux prerequisites and controller health
`flux_stats`	Resource reconciliation statistics
`flux_logs`	Controller logs with kind/name/level/since filtering
`flux_events`	Flux events filtered by namespace or resource
`flux_trace`	Trace a Kubernetes object to its Flux source
`flux_tree`	Show kustomization resource tree with status
`flux_diff`	Diff kustomization against live cluster state
`flux_export`	Export Flux resources as YAML manifests
`flux_debug`	Debug helmrelease or kustomization (computed values, rendered manifests)
`flux_version`	Show CLI and controller versions

Readwrite tools (MODE=readwrite only)

Tool	Description
`flux_reconcile`	Trigger reconciliation (with optional --with-source)
`flux_suspend`	Suspend reconciliation for a resource
`flux_resume`	Resume a suspended resource
`flux_delete`	Delete a Flux resource

Usage

# Readonly
spec:
  toolRefs:
    - name: flux
      ref: ghcr.io/myorg/agent-tools/flux:0.4.0

# Readwrite
spec:
  toolRefs:
    - name: flux
      ref: ghcr.io/myorg/agent-tools/flux:0.4.0
      env:
        - name: MODE
          value: readwrite

Development

Requirements

Go 1.26+
Access to an OCI-compliant registry (e.g. ghcr.io)
Docker credentials configured in ~/.docker/config.json

Makefile Targets

make build                            # Build CLI binary
make test                             # Run tests
make vet                              # Run go vet
make fmt                              # Format code

make build-server SERVER=kube-explore   # Build a single MCP server
make build-servers                      # Build all MCP servers

make push-server SERVER=kube-explore TAG=0.2.0  # Push a single server
make push-servers TAG=0.2.0                      # Push all servers

make docker-build SERVER=kube-explore   # Build Docker image for a server

make clean                            # Remove binaries and dist/ dirs

Adding a New Server

Create a directory under servers/ with its own go.mod
Implement an MCP server using github.com/modelcontextprotocol/go-sdk with stdio transport

Add a manifest.json:

{
  "name": "my-server",
  "command": "my-server",
  "transport": "stdio",
  "description": "What this server does"
}

Build and push:

make build-server SERVER=my-server
make push-server SERVER=my-server TAG=0.1.0

CI/CD

CI (`.github/workflows/ci.yaml`)

Runs on push/PR to main or dev:

build-and-test -- go build, go vet, go test
validate-packages -- Checks every servers/*/ has a manifest.json

Release (`.github/workflows/release.yaml`)

Triggered by v* tags:

cli-release -- Cross-compiles for linux/darwin amd64/arm64, uploads to GitHub Release
server-packages -- Pushes each servers/*/ as an OCI artifact to ghcr.io/{owner}/agent-tools/{name}:{version} (+ latest)

Images

Image	Source	Purpose
`ghcr.io/samyn92/agent-tools/kube-explore`	`servers/kube-explore/Dockerfile`	Kube-explore MCP server
`ghcr.io/samyn92/agent-tools/kubectl`	`servers/kubectl/Dockerfile`	kubectl MCP server (readonly/readwrite)
`ghcr.io/samyn92/agent-tools/flux`	OCI artifact	Flux CD MCP server (readonly/readwrite)

Related Repositories

Repository	Purpose
agentops-core	Kubernetes operator that pulls and mounts these OCI artifacts
agentops-runtime-fantasy	Fantasy SDK agent runtime (Go, Charm Fantasy SDK)
agent-channels	Channel bridge images (GitLab, webhook, etc.)
agent-console	Web console
agent-factory	Helm chart

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

agent-tools

Architecture

Repository Structure

CLI

Installation

Usage

Example

OCI Artifact Format

Source Validation

MCP Servers

kube-explore

kubectl

Readonly tools

Readwrite tools (MODE=readwrite only)

Usage

flux

Readonly tools

Readwrite tools (MODE=readwrite only)

Usage

Development

Requirements

Makefile Targets

Adding a New Server

CI/CD

CI (`.github/workflows/ci.yaml`)

Release (`.github/workflows/release.yaml`)

Images

Related Repositories

About

Uh oh!

Releases 15

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github/workflows		.github/workflows
cmd/agent-tools		cmd/agent-tools
internal/oci		internal/oci
servers		servers
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

agent-tools

Architecture

Repository Structure

CLI

Installation

Usage

Example

OCI Artifact Format

Source Validation

MCP Servers

kube-explore

kubectl

Readonly tools

Readwrite tools (MODE=readwrite only)

Usage

flux

Readonly tools

Readwrite tools (MODE=readwrite only)

Usage

Development

Requirements

Makefile Targets

Adding a New Server

CI/CD

CI (.github/workflows/ci.yaml)

Release (.github/workflows/release.yaml)

Images

Related Repositories

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

CI (`.github/workflows/ci.yaml`)

Release (`.github/workflows/release.yaml`)

Packages