convez.ai
MCP ServerDevOps & InfraestruturaAvançado
no0ktheali3n

MCP Toolbox

no0ktheali3n/mcp-toolbox

Servidores MCP modulares para agentes Kubernetes e sistemas externos

Ver no GitHub
InicialPluginScore · de 0 a 100

Coleção modular de servidores MCP especializados para integração com agentes agentic, cobrindo operações Kubernetes, sistemas externos (Gitea e registros OCI) e consultas meteorológicas. Cada servidor é versionado independentemente, permitindo evolução sem acoplamento de breaking changes entre componentes.

Instalação

$npx convez-ai no0ktheali3n/mcp-toolbox

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Automação de operações Kubernetes e SRE com agentes autônomos
  • Diagnóstico e remediação de falhas em clusters via IA
  • Integração cruzada entre Kubernetes, registros OCI e repositórios Git
  • Construção de agentes especializados em operações de infraestrutura

Veredito

Projeto robusto e bem arquitetado para equipes DevOps/SRE que já usam MCP e agentes agentic. A modularidade e o versionamento independente são pontos fortes, mas requer expertise substancial em Kubernetes, MCP e integração de agentes para explorar plenamente.

README

A tradução para o português deste README ainda está na fila.

MCP Toolbox

A collection of Model Context Protocol (MCP) servers that extend agentic AI runtimes with specialized tools. Each server is self-contained in its own directory, versioned independently, and deployable on its own.

Overview

MCP Toolbox hosts a collection of Model Context Protocol servers that domain-specialized agent / persona projects consume — Kubernetes operations + external-systems (Gitea + OCI registry) access, plus a reference weather server kept from the repo's original template. Each server evolves on its own tag cadence so a breaking change in one doesn't drag the others along.

Project Structure

mcp-toolbox/
├── k8s/        # mcp-k8s — Kubernetes operations MCP server
├── external/   # mcp-external — Gitea + OCI registry MCP server
├── weather/    # reference National Weather Service MCP server (kept from template)
└── README.md   # this file

Servers at a glance

ServerPathTransportPortTool countLatest tag
mcp-k8sk8s/streamable-http800025 (discovery / diagnosis / remediation / logs)v2.3.0
mcp-externalexternal/streamable-http800210 (4 OCI registry + 5 Gitea + detector_submit_rca)external-v0.2.1
Weatherweather/stdio—2 (alerts, forecast)— (reference)

Tag conventions:

  • v* (e.g. v2.3.0) → mcp-k8s milestones
  • external-v* (e.g. external-v0.2.1) → mcp-external milestones
  • Active development branch: v2.0-dev. Milestones are tagged off this branch.

mcp-k8s (k8s/)

Kubernetes operations MCP server. Designed to back any domain-specialized SRE / operations agent (Agent Zero or any runtime that speaks streamable-http MCP). 25 tools span:

  • Discovery — get_cluster_summary, search_resources, list_*
  • Diagnosis — event + log access (get_events, get_pod_logs, get_resource_yaml), pod-detail / container-state inspection
  • Remediation (guarded) — patch_resource_limits, restart_deployment, restart_container, restart_pod, scale_deployment, rollback_deployment
  • Log query (Loki) — query_loki, search_logs via the Kubernetes API service-proxy (no direct network path required)

All mutation tools run through a configurable denylist (MCP_K8S_DENYLIST) so operators can restrict what the agent is allowed to change per environment.

See k8s/README.md for the full catalog, dev workflow, kubeconfig setup, and the mutation-denylist contract.

mcp-external (external/)

External-systems MCP server. Lets the agent cross out of Kubernetes to diagnose cross-system failures (image tag-format mismatches, invalid Helm values per schema, etc.). Currently read-only; write tools are scoped for post-PoC.

  • OCI registry — harbor_list_tags, harbor_check_tag, harbor_list_projects, harbor_get_repository_info
  • Gitea — gitea_get_file_content, gitea_get_chart_metadata, gitea_get_recent_commits, gitea_list_branches, gitea_search_code

Validated end-to-end against Scenario 1 (image tag-format mismatch between registry and Helm chart) at external-v0.2.1.

See external/README.md for env-var configuration, the Gitea token bootstrap sequence, and the streamable-http / dual-repo workflow.

Weather (weather/)

Reference server kept from the repo's original template. Integrates with the US National Weather Service API — get_alerts(state) and get_forecast(latitude, longitude). Useful as a minimal MCP example and for Claude Desktop demos over stdio transport. NWS-only, so US locations only.

Installation

Prerequisites

  • Python 3.12+
  • uv package manager
  • Docker (for mcp-k8s and mcp-external — both run containerized)
  • A running Kubernetes cluster for mcp-k8s (k3d recommended for dev)
  • Running Gitea + OCI registry for mcp-external (a lightweight registry:2 + joxit/docker-registry-ui pairing is documented in the Persona stack's k8/docker/registry/ compose file)
  • Claude Desktop (only for stdio/weather)

Setup

git clone https://github.com/no0ktheali3n/mcp-toolbox.git
cd mcp-toolbox

Each server has its own build/run instructions — see the subfolder READMEs.

Transport notes

  • mcp-k8s and mcp-external use streamable-http transport and run inside Docker. Consumed by Agent Zero (or any streamable-http-capable MCP client) over http://<host>:<port>/mcp.
  • Weather uses stdio transport and is consumed by Claude Desktop via the claude_desktop_config.json pattern below.

Claude Desktop (stdio) — weather

Add to claude_desktop_config.json (on Windows at %AppData%\Roaming\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/absolute/path/to/mcp-toolbox/weather",
        "run",
        "weather.py"
      ]
    }
  }
}

Restart Claude Desktop, confirm weather appears under connectors, and verify that get_alerts + get_forecast are enabled.

Agent Zero (streamable-http) — mcp-k8s + mcp-external

Agent Zero discovers MCP servers over HTTP. Typical container-to-container URLs on the shared traefik-proxy Docker network used by the Persona stack:

http://mcp-k8s:8000/mcp
http://mcp-external:8002/mcp

Subfolder READMEs cover the full Agent Zero config block.

Development

Testing with MCP Inspector

# Weather (stdio)
npx @modelcontextprotocol/inspector uv run weather/weather.py

# mcp-k8s (HTTP)
npx @modelcontextprotocol/inspector --transport sse http://localhost:8000/mcp

# mcp-external (HTTP)
npx @modelcontextprotocol/inspector --transport sse http://localhost:8002/mcp

FastMCP CLI for iterative dev:

cd weather && fastmcp dev weather.py

Adding a new server

  1. Create a new directory: mcp-toolbox/<server-name>/
  2. Implement the server using FastMCP (tool decorators + transport choice)
  3. Add a subfolder README.md covering purpose, tool surface, env-var config, and dev loop
  4. Add the server to this README's "Servers at a glance" table
  5. Test with MCP Inspector before integrating with any agent runtime

Dual-repo workflow (mcp-k8s / mcp-external)

The Persona stack ships a dev copy of each server inside the persona repo (persona/k8/docker/mcp-k8s/, persona/k8/docker/mcp-external/) so the MCP server runs on the same Docker network as Agent Zero and the detector during integrated testing. This repo is the authoritative source — Persona-side edits get mirrored back here at each milestone. Don't let the two copies drift. See external/README.md "Dual-repo note" and k8s/README.md for the exact mirror commands.

Technology stack

  • MCP SDK — Model Context Protocol implementation
  • FastMCP — high-level Python framework for MCP servers
  • Transports — stdio (weather / Claude Desktop) and streamable-http (mcp-k8s / mcp-external / Agent Zero)
  • Package management — uv
  • Python — 3.12+

Consumers

These servers are designed for any agent runtime that speaks streamable-http MCP. The reference consumer pattern is an Agent Zero deployment running a domain-specialized agent (e.g. an SRE expert) that loads mcp-k8s for in-cluster diagnosis + remediation and mcp-external for source-of-truth lookups against Gitea + OCI registries during incident triage.

Additional MCP servers covering other domains (ticketing, databases, build / CI, cloud-vendor APIs) can land alongside as peer top-level directories with their own tag cadence.

Resources

License

MIT — see LICENSE.

Acknowledgments


Last updated: 2026-04-23 Latest tags: v2.3.0 (mcp-k8s) · external-v0.2.1 (mcp-external)

Ver o original no GitHub

Bom para

Relacionados