talkops-traefik-mcp-server 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. talkops_traefik_mcp_server-0.1.0/.gitignore +7 -0
  2. talkops_traefik_mcp_server-0.1.0/.pyre_configuration +15 -0
  3. talkops_traefik_mcp_server-0.1.0/Dockerfile +99 -0
  4. talkops_traefik_mcp_server-0.1.0/PKG-INFO +501 -0
  5. talkops_traefik_mcp_server-0.1.0/README.md +471 -0
  6. talkops_traefik_mcp_server-0.1.0/docker-entrypoint.sh +19 -0
  7. talkops_traefik_mcp_server-0.1.0/docs/PROMPT_REFERENCE.md +487 -0
  8. talkops_traefik_mcp_server-0.1.0/docs/TRAEFIK_HEADER_CANARY_TEST_GUIDE.md +76 -0
  9. talkops_traefik_mcp_server-0.1.0/docs/TRAEFIK_NGINX_MIGRATION_TEST_GUIDE.md +316 -0
  10. talkops_traefik_mcp_server-0.1.0/docs/TRAEFIK_REAL_WORLD_SCENARIO.md +309 -0
  11. talkops_traefik_mcp_server-0.1.0/docs/TRAEFIK_SHADOW_LAUNCH_TEST_GUIDE.md +139 -0
  12. talkops_traefik_mcp_server-0.1.0/docs/TRAEFIK_TCP_ROUTING_TEST_GUIDE.md +169 -0
  13. talkops_traefik_mcp_server-0.1.0/docs/TRAEFIK_TRAFFIC_MANAGEMENT_TEST_GUIDE.md +238 -0
  14. talkops_traefik_mcp_server-0.1.0/docs/WORKFLOW_JOURNEYS.md +550 -0
  15. talkops_traefik_mcp_server-0.1.0/pyproject.toml +54 -0
  16. talkops_traefik_mcp_server-0.1.0/scripts/test_traffic_middleware.py +114 -0
  17. talkops_traefik_mcp_server-0.1.0/tests/__init__.py +1 -0
  18. talkops_traefik_mcp_server-0.1.0/tests/test_gateway_api_migrator.py +256 -0
  19. talkops_traefik_mcp_server-0.1.0/tests/test_migration_agent_intelligence.py +155 -0
  20. talkops_traefik_mcp_server-0.1.0/tests/test_migration_gaps.py +346 -0
  21. talkops_traefik_mcp_server-0.1.0/tests/test_migration_output_contract.py +382 -0
  22. talkops_traefik_mcp_server-0.1.0/tests/test_nginx_migration_apply_gateway_api.py +126 -0
  23. talkops_traefik_mcp_server-0.1.0/tests/test_rollback.py +266 -0
  24. talkops_traefik_mcp_server-0.1.0/tests/test_servers_transport_service.py +151 -0
  25. talkops_traefik_mcp_server-0.1.0/tests/test_shadow_mode.py +147 -0
  26. talkops_traefik_mcp_server-0.1.0/tests/test_traefik_middleware_builders.py +187 -0
  27. talkops_traefik_mcp_server-0.1.0/tests/test_weighted_route_header_cookie_match.py +94 -0
  28. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/__init__.py +0 -0
  29. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/config.py +98 -0
  30. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/exceptions/__init__.py +0 -0
  31. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/exceptions/custom.py +373 -0
  32. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/main.py +40 -0
  33. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/migration_nginx/__init__.py +25 -0
  34. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/migration_nginx/analyzer.py +369 -0
  35. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/migration_nginx/generator.py +391 -0
  36. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/migration_nginx/migration_plan.py +171 -0
  37. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/migration_nginx/migrator_gateway_api.py +454 -0
  38. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/migration_nginx/migrator_traefik.py +1016 -0
  39. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/migration_nginx/scanner.py +386 -0
  40. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/resources/__init__.py +53 -0
  41. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/resources/anomaly_resources.py +177 -0
  42. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/resources/base.py +31 -0
  43. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/resources/metrics_resources.py +95 -0
  44. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/resources/migration_resources.py +325 -0
  45. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/resources/registry.py +37 -0
  46. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/resources/traffic_resources.py +144 -0
  47. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/server/__init__.py +0 -0
  48. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/server/bootstrap.py +62 -0
  49. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/server/core.py +51 -0
  50. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/server/middleware.py +126 -0
  51. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/services/__init__.py +0 -0
  52. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/services/nginx_migration_service.py +880 -0
  53. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/services/traefik_generator_service.py +412 -0
  54. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/services/traefik_service.py +2563 -0
  55. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/__init__.py +69 -0
  56. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/base.py +68 -0
  57. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/generators/__init__.py +0 -0
  58. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/generators/traefik_generators.py +365 -0
  59. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/migration/__init__.py +0 -0
  60. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/migration/nginx_migration_tools.py +216 -0
  61. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/registry.py +84 -0
  62. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/traefik/__init__.py +11 -0
  63. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/traefik/backend_endpoints_tools.py +154 -0
  64. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/traefik/middleware_management.py +866 -0
  65. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/traefik/tcp_tools.py +214 -0
  66. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/tools/traefik/traffic_routing.py +213 -0
  67. talkops_traefik_mcp_server-0.1.0/traefik_mcp_server/traefik_middleware_builders.py +232 -0
  68. talkops_traefik_mcp_server-0.1.0/uv.lock +1452 -0
@@ -0,0 +1,7 @@
1
+ .venv/
2
+ .env
3
+ __pycache__/
4
+ .vscode/
5
+ .idea/
6
+ .pytest_cache/
7
+ references/
@@ -0,0 +1,15 @@
1
+ {
2
+ "source_directories": [
3
+ "traefik_mcp_server",
4
+ "tests",
5
+ "scripts"
6
+ ],
7
+ "search_path": [
8
+ ".venv/lib/python3.12/site-packages"
9
+ ],
10
+ "exclude": [
11
+ ".*/venv/.*",
12
+ ".*/\\.venv/.*",
13
+ ".*/build/.*"
14
+ ]
15
+ }
@@ -0,0 +1,99 @@
1
+ # Use Python 3.12 slim as base image
2
+ FROM python:3.12-slim AS uv
3
+
4
+ # Install the project into `/app`
5
+ WORKDIR /app
6
+
7
+ # Enable bytecode compilation
8
+ ENV UV_COMPILE_BYTECODE=1
9
+
10
+ # Copy from the cache instead of linking since it's a mounted volume
11
+ ENV UV_LINK_MODE=copy
12
+
13
+ # Prefer the system python
14
+ ENV UV_PYTHON_PREFERENCE=only-system
15
+
16
+ # Run without updating the uv.lock file like running with `--frozen`
17
+ # NOTE: Removed --frozen because the package might not be fully locked yet
18
+ ENV UV_FROZEN=false
19
+
20
+ # Copy the required files first
21
+ COPY pyproject.toml ./
22
+
23
+ # Python optimization and uv configuration
24
+ ENV PIP_NO_CACHE_DIR=1 \
25
+ PIP_DISABLE_PIP_VERSION_CHECK=1
26
+
27
+ # Install system dependencies and Python package manager
28
+ RUN apt-get update && \
29
+ apt-get install -y --no-install-recommends \
30
+ build-essential \
31
+ gcc \
32
+ libffi-dev \
33
+ libssl-dev \
34
+ curl && \
35
+ rm -rf /var/lib/apt/lists/*
36
+
37
+ # Install uv package manager
38
+ RUN pip install uv
39
+
40
+ # Create virtual environment and install the project's dependencies
41
+ RUN uv venv /app/.venv
42
+ RUN --mount=type=cache,target=/root/.cache/uv \
43
+ uv sync --python 3.12 --no-install-project --no-dev --no-editable
44
+
45
+ # Then, add the rest of the project source code and install it
46
+ COPY . /app
47
+ RUN --mount=type=cache,target=/root/.cache/uv \
48
+ uv sync --python 3.12 --no-dev --no-editable
49
+
50
+ # Make the directory just in case it doesn't exist
51
+ RUN mkdir -p /root/.local
52
+
53
+ # Final stage - runtime image
54
+ FROM python:3.12-slim
55
+
56
+ # Place executables in the environment at the front of the path and include other binaries
57
+ ENV PATH="/app/.venv/bin:$PATH" \
58
+ PYTHONUNBUFFERED=1
59
+
60
+ # Install runtime dependencies and create application user
61
+ RUN apt-get update && \
62
+ apt-get install -y --no-install-recommends ca-certificates curl lsof && \
63
+ rm -rf /var/lib/apt/lists/* && \
64
+ update-ca-certificates && \
65
+ groupadd -r app && \
66
+ useradd -r -g app -d /app -s /bin/bash app
67
+
68
+ # Install kubectl (latest stable)
69
+ RUN curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" \
70
+ && install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl \
71
+ && rm kubectl
72
+
73
+ # Copy application artifacts from build stage
74
+ COPY --from=uv --chown=app:app /app/.venv /app/.venv
75
+ COPY --from=uv --chown=app:app /root/.local /root/.local
76
+
77
+ # Copy scripts and make them executable
78
+ COPY ./docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
79
+ RUN chmod +x /usr/local/bin/docker-entrypoint.sh
80
+
81
+ # Run as non-root
82
+ USER app
83
+
84
+ # Expose port
85
+ EXPOSE 8769
86
+
87
+ # Set working directory
88
+ WORKDIR /app
89
+
90
+ # Default environment variables
91
+ ENV MCP_SERVER_NAME=traefik-mcp-server
92
+ ENV MCP_SERVER_VERSION=0.1.0
93
+ ENV MCP_TRANSPORT=http
94
+ ENV MCP_HOST=0.0.0.0
95
+ ENV MCP_PORT=8769
96
+ ENV MCP_PATH=/mcp
97
+ ENV K8S_KUBECONFIG=/app/.kube/config
98
+
99
+ ENTRYPOINT ["docker-entrypoint.sh"]
@@ -0,0 +1,501 @@
1
+ Metadata-Version: 2.4
2
+ Name: talkops-traefik-mcp-server
3
+ Version: 0.1.0
4
+ Summary: A Model Context Protocol (MCP) server for Traefik traffic management — routing, middleware, mirroring, and NGINX migration.
5
+ Project-URL: Homepage, https://talkops.ai
6
+ Project-URL: Repository, https://github.com/talkops-ai/talkops-mcp
7
+ Project-URL: Documentation, https://github.com/talkops-ai/talkops-mcp/tree/main/src/traefik-mcp-server
8
+ Project-URL: Issues, https://github.com/talkops-ai/talkops-mcp/issues
9
+ Project-URL: Changelog, https://github.com/talkops-ai/talkops-mcp/releases
10
+ Author-email: TalkOps <contact@talkops.ai>
11
+ License: Apache-2.0
12
+ Keywords: ai,devops,kubernetes,mcp,model-context-protocol,routing,traefik,traffic-management
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: System Administrators
16
+ Classifier: License :: OSI Approved :: Apache Software License
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Classifier: Topic :: System :: Systems Administration
22
+ Requires-Python: >=3.12
23
+ Requires-Dist: fastmcp
24
+ Requires-Dist: kubernetes
25
+ Requires-Dist: pydantic
26
+ Requires-Dist: pyyaml
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=8; extra == 'dev'
29
+ Description-Content-Type: text/markdown
30
+
31
+ <p align="center">
32
+ <img src="https://raw.githubusercontent.com/traefik/traefik/master/docs/content/assets/img/traefik.logo.png" alt="Traefik MCP Server" width="140" onError="this.style.display='none'"/>
33
+ </p>
34
+
35
+ <h1 align="center">Traefik MCP Server</h1>
36
+
37
+ <p align="center">
38
+ An MCP server that gives AI assistants the power to easily manage Kubernetes traffic for you—safely routing requests, adding instant protections like rate limits, and automatically upgrading outdated NGINX setups into modern Traefik configurations.
39
+ </p>
40
+
41
+ <p align="center">
42
+ <a href="https://github.com/talkops-ai/talkops-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" alt="License"/></a>
43
+ <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?style=flat-square&logo=python&logoColor=white" alt="Python 3.10+"/></a>
44
+ <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-4A90D9.svg?style=flat-square" alt="MCP"/></a>
45
+ <a href="https://traefik.io/"><img src="https://img.shields.io/badge/Traefik-v2.10%2B-24A1C1.svg?style=flat-square&logo=traefik&logoColor=white" alt="Traefik"/></a>
46
+ <a href="https://discord.gg/tSN2Qn9uM8"><img src="https://img.shields.io/badge/Discord-Join%20Us-5865F2.svg?style=flat-square&logo=discord&logoColor=white" alt="Discord"/></a>
47
+ </p>
48
+
49
+ <p align="center">
50
+ <a href="#getting-started">Quick Start</a> · <a href="https://github.com/talkops-ai/talkops-mcp">Docs</a> · <a href="https://github.com/talkops-ai/talkops-mcp/issues/new?template=bug_report.md">Report Bug</a> · <a href="https://github.com/talkops-ai/talkops-mcp/issues/new?template=feature_request.md">Request Feature</a>
51
+ </p>
52
+
53
+ ---
54
+
55
+ ## Why Traefik MCP Server?
56
+
57
+ **The problem:** Managing Kubernetes traffic can be incredibly frustrating. Between brittle Ingress YAML files, messy NGINX annotations, and digging through documentation to figure out complex `Middleware` configurations, even a simple task like adding a rate limiter can feel overwhelming. If you want an AI assistant to do this for you, it usually struggles because it doesn't have a safe, structured way to interact with Traefik's custom resources natively.
58
+
59
+ **The solution:** The Traefik MCP Server gives AI assistants (like Claude or Cline) direct tools to manage your Kubernetes traffic for you safely and automatically. Instead of writing endless YAML by hand, your AI can now confidently control how your apps are routed.
60
+
61
+ Here's exactly what your AI assistant can now do for you:
62
+
63
+ 1. **Automated NGINX-to-Traefik Migrations (with AI Problem-Solving):** Moving away from NGINX? The AI scans your old Ingress files, analyzes the messy annotations (like CORS, sticky sessions, or custom auth), and automatically converts them into modern Traefik resources. If the AI detects a legacy configuration that breaks the migration, it can use built-in "Supervised Autonomy" to intelligently bypass the broken rule and build a custom workaround on the fly.
64
+ 2. **Effortless Traffic Splitting & Shadow Testing:** Need to test a new version of your app? Ask your AI to split traffic (e.g., 90% stable, 10% canary) or set up a "Shadow Launch" where live production traffic is copied to your new app for silent testing without users ever knowing.
65
+ 3. **Instant App Protections:** You no longer need to write complex `Middleware` YAML manually. Simply tell the AI, "Add a rate limit and a circuit breaker to the frontend," and it will instantly build and attach those network security protections.
66
+ 4. **Deep Network Insights:** Your AI gains advanced "Micro-Observability." It instantly knows exactly what percentage of traffic is hitting which container, what security middlewares are active, and if there are any immediate routing connection errors globally.
67
+
68
+ ---
69
+
70
+ ## Key Features
71
+
72
+ **Edge Routing**
73
+ - Read robust K8s Service definitions instantly
74
+ - Establish exact weighted percentages (e.g. 90/10) directly targeting K8s objects dynamically
75
+ - Deploy secure `IngressRoute` rules seamlessly
76
+
77
+ **Middleware Generation**
78
+ - Automatically format and enforce `RateLimit` limitations per second
79
+ - Construct `Retry` and `CircuitBreaker` logic gracefully across target connections
80
+ - Attach independent modules onto active data plane networks effortlessly
81
+
82
+ **Legacy Extrication & Supervised Autonomy**
83
+ - Scan legacy environments retrieving `Ingress` specs safely
84
+ - Unpack annotations transforming behaviors into isolated CRDs
85
+ - Setup side-by-side verification tests safely
86
+ - Agentic Overrides explicitly bypassing breaking legacy configs securely via AI logic
87
+
88
+ **Advanced TCP & HTTP Routing**
89
+ - Route standard TCP streams natively bypassing HTTP abstraction logic (Postgres, Redis)
90
+ - Deploy simple non-weighted `IngressRoute` rules seamlessly
91
+
92
+ **Deep Network Audits**
93
+ - Access specific path definitions validating backend availability metrics
94
+ - Identify traffic anomalies natively
95
+
96
+ **Multi-Cluster Capability**
97
+ - Navigate strictly mapped Kubernetes context securely
98
+
99
+ **Built-in Guidance**
100
+ - Access specialized instructions executing migrations natively
101
+
102
+ ---
103
+
104
+ ## Architecture
105
+
106
+ The server translates high-level MCP execution requests smoothly crossing directly into the Python Kubernetes sub-layer.
107
+
108
+ ```
109
+ ┌─────────────────────────┐
110
+ │ MCP Client │
111
+ │ (Claude, Cline, Agent) │
112
+ └──────────┬──────────────┘
113
+ │
114
+ ┌──────────▼──────────────┐
115
+ │ FastMCP Server Core │
116
+ │ (HTTP / stdio) │
117
+ └──────────┬──────────────┘
118
+ │
119
+ ┌─────────────────────────┬─────────────────────────┐
120
+ │ │
121
+ ┌─────▼─────┐ ┌─────▼─────┐
122
+ │ Tools │ │ Resources │
123
+ │ │ │ │
124
+ │ Weights │ │ traefik://│
125
+ │ NGINX Conv│ │ │
126
+ │ Rate Limits│ │ │
127
+ │ Splitting │ │ │
128
+ │ │ │ │
129
+ └─────┬─────┘ └─────┬─────┘
130
+ │ │
131
+ └─────────────────────────┬─────────────────────────┘
132
+ │
133
+ ┌─────────▼──────────┐
134
+ │ Service Layer │
135
+ │ │
136
+ │ traefik_service.py │
137
+ │ generator_service │
138
+ └─────────┬──────────┘
139
+ │
140
+ ┌─────────▼──────────┐
141
+ │ Python K8s Client │
142
+ │ (API interaction) │
143
+ └────────────────────┘
144
+ ```
145
+
146
+ **How it works in practice:**
147
+
148
+ 1. An AI assistant accesses the server securely (HTTP or stdio).
149
+ 2. The AI evaluates current constraints natively via API reads.
150
+ 3. Upon intent (e.g., "Add a rate limit"), the AI hits specific execution tools mapping inputs dynamically.
151
+ 4. Business layers patch the controller logically via the `KUBECONFIG`.
152
+ 5. Traffic flows immediately transition.
153
+
154
+ ---
155
+
156
+ ## Table of Contents
157
+
158
+ - [Why Traefik MCP Server?](#why-traefik-mcp-server)
159
+ - [Key Features](#key-features)
160
+ - [Architecture](#architecture)
161
+ - [Tech Stack](#tech-stack)
162
+ - [Getting Started](#getting-started)
163
+ - [Configuration](#configuration)
164
+ - [Available Tools](#available-tools)
165
+ - [Available Resources](#available-resources)
166
+ - [Usage](#usage)
167
+ - [Project Structure](#project-structure)
168
+ - [Roadmap](#roadmap)
169
+ - [Contributing](#contributing)
170
+ - [FAQ](#faq)
171
+ - [Troubleshooting](#troubleshooting)
172
+ - [Security Considerations](#security-considerations)
173
+ - [License](#license)
174
+ - [Contact](#contact)
175
+ - [Acknowledgments](#acknowledgments)
176
+
177
+ ---
178
+
179
+ ## Tech Stack
180
+
181
+ | Category | Technologies |
182
+ |----------|-------------|
183
+ | **Language** | Python 3.10+ |
184
+ | **MCP Framework** | [FastMCP](https://github.com/jlowin/fastmcp) |
185
+ | **Protocol** | [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) |
186
+ | **Kubernetes** | Traefik CRDs · kubectl · Python K8s Client |
187
+ | **Transport** | HTTP · stdio |
188
+ | **Infrastructure** | Docker · [uv](https://github.com/astral-sh/uv) |
189
+
190
+ ---
191
+
192
+ ## Getting Started
193
+
194
+ ### Prerequisites
195
+
196
+ - **Docker** (recommended) or **Python 3.10+** (for local dev)
197
+ - **Access to a Kubernetes cluster** with a valid kubeconfig
198
+ - **Traefik Ingress Controller** installed on the target cluster
199
+
200
+ ### Quick Start with Docker (recommended)
201
+
202
+ Pull the image and run it directly:
203
+
204
+ ```bash
205
+ docker run --rm -it \
206
+ -p 8769:8769 \
207
+ -v ~/.kube/config:/app/.kube/config:ro \
208
+ talkopsai/traefik-mcp-server:latest
209
+ ```
210
+
211
+ That's it. The server is now listening on `http://localhost:8769/mcp`.
212
+
213
+ Point your MCP client at it:
214
+
215
+ ```json
216
+ {
217
+ "mcpServers": {
218
+ "traefik": {
219
+ "url": "http://localhost:8769/mcp",
220
+ "description": "MCP Server for managing Traefik Edge Routing and Middlewares"
221
+ }
222
+ }
223
+ }
224
+ ```
225
+
226
+ ### From Source (Python)
227
+
228
+ For development or if you want to run without Docker:
229
+
230
+ 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) for dependency management.
231
+
232
+ 2. Clone and set up:
233
+
234
+ ```bash
235
+ git clone https://github.com/talkops-ai/talkops-mcp.git
236
+ cd talkops-mcp/src/traefik-mcp-server
237
+ uv venv
238
+ source .venv/bin/activate
239
+ uv pip install -e ".[dev]"
240
+ ```
241
+
242
+ 3. Run the server:
243
+
244
+ ```bash
245
+ uv run traefik-mcp-server
246
+ ```
247
+
248
+ Or, with the venv already activated: `traefik-mcp-server`.
249
+
250
+ 4. Run tests (activate the venv first so `pytest` uses the project environment):
251
+
252
+ ```bash
253
+ cd talkops-mcp/src/traefik-mcp-server
254
+ source .venv/bin/activate
255
+ pytest tests/
256
+ ```
257
+
258
+ ---
259
+
260
+ ## Configuration
261
+
262
+ All configuration is via environment variables.
263
+
264
+ When running in Docker, pass overrides with `-e`:
265
+
266
+ ```bash
267
+ docker run --rm -it \
268
+ -p 8769:8769 \
269
+ -v ~/.kube/config:/app/.kube/config:ro \
270
+ -e K8S_CONTEXT=production-cluster \
271
+ -e MCP_LOG_LEVEL=DEBUG \
272
+ talkopsai/traefik-mcp-server:latest
273
+ ```
274
+
275
+ ### Server Configuration
276
+
277
+ | Variable | Default | Description |
278
+ |----------|-------------|-------------|
279
+ | `MCP_SERVER_NAME` | `traefik-mcp-server`| Server name identifier |
280
+ | `MCP_SERVER_VERSION` | `0.1.0` | Server version string |
281
+ | `MCP_TRANSPORT` | `http` | Transport mode: `http` or `stdio` |
282
+ | `MCP_HOST` | `0.0.0.0` | Host address for HTTP server |
283
+ | `MCP_PORT` | `8769` | Port for HTTP server |
284
+ | `MCP_PATH` | `/mcp` | MCP endpoint path |
285
+ | `MCP_LOG_LEVEL` | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
286
+ | `MCP_LOG_FORMAT` | `json` | Log format: `json` or `text` |
287
+
288
+ ### Edge & Kubernetes
289
+
290
+ | Variable | Default | Description |
291
+ |----------|-------------|-------------|
292
+ | `K8S_KUBECONFIG` | `/app/.kube/config` | Path to kubeconfig file |
293
+ | `K8S_CONTEXT` | *(empty)* | Specific K8s context to force |
294
+ | `K8S_IN_CLUSTER` | `false` | True if running natively inside a pod |
295
+ | `MCP_ALLOW_WRITE` | `true` | Must be `true` for mutating cluster operations (e.g. `traefik_nginx_migration` with `action=apply`) |
296
+
297
+ ### Write Access Control
298
+
299
+ `MCP_ALLOW_WRITE=true` (default) allows in-cluster **apply** for the NGINX migration pipeline. If false, mutating actions are blocked and YAML-only **migrate** still works. Inventory and analysis: MCP resources `traefik://migration/nginx-ingress-scan` and `traefik://migration/nginx-ingress-analyze`.
300
+
301
+ **RBAC (typical):** read paths need `get/list/watch` on **ingresses** and `get/list` on **pods** (controller detection). Apply paths additionally need `create/patch/update` on **middlewares** and **serverstransports** (`traefik.io/v1alpha1`), and `patch` on **ingresses** and **services** in target namespaces.
302
+
303
+ ---
304
+
305
+ ## Available Tools
306
+
307
+ ### Edge Routing & Traffic Splitting
308
+ | Tool | Description |
309
+ |------|-------------|
310
+ | `traefik_manage_weighted_routing` | Create, update, or delete weighted routes. Use `action` (create/update/delete) with route_name, hostname, stable_weight, canary_weight as needed. |
311
+ | `traefik_manage_simple_route` | Direct K8s Service IngressRoute: `action=create|delete` (upsert on create). |
312
+
313
+ ### Native Middlewares & Resiliency
314
+ | Tool | Description |
315
+ |------|-------------|
316
+ | `traefik_manage_middleware` | Create, update, or delete Traefik `Middleware` CRDs. `action=create` upserts. **`middleware_type`**: `rate_limit`, `circuit_breaker`, `strip_prefix`, `redirect_scheme`, `inflight_req`, `headers`, `ip_allowlist`, `ip_denylist`, `forward_auth`, `buffering`, `replace_path`, `replace_path_regex`, `add_prefix`. Parameter matrix: [`docs/MIDDLEWARE_TOOLS.md`](docs/MIDDLEWARE_TOOLS.md). |
317
+ | `traefik_manage_traffic_mirroring` | Shadow traffic: `action=enable|disable|update` (mirror percent, optional attach/restore to WRR) |
318
+ | `traefik_manage_route_middlewares` | Attach or detach middlewares on an IngressRoute (action=attach \| detach) |
319
+
320
+ ### Backend TLS, timeouts & sticky sessions
321
+ | Tool | Description |
322
+ |------|-------------|
323
+ | `traefik_manage_servers_transport` | Create/update or delete Traefik **ServersTransport** CRDs (`action=create\|delete`): backend dial/response timeouts, `insecureSkipVerify`. Link Services with `traefik.ingress.kubernetes.io/service.serverstransport`. |
324
+ | `traefik_configure_service_affinity` | **Enable** or **disable** Traefik sticky-cookie annotations on a Kubernetes **Service** (`action=enable\|disable`), matching NGINX migration semantics. |
325
+
326
+ ### Generators
327
+ | Tool | Description |
328
+ |------|-------------|
329
+ | `traefik_generate_routing_manifest` | Generate TraefikService, IngressRoute, TCP manifests, etc. Use `manifest_type` (traefik_service, ingress_for_traefik_service, ingress_for_services, mirroring, ingress_route_tcp, middleware_tcp). Header/cookie routing is applied live via `traefik_manage_weighted_routing` (create). For **full** NGINX Ingress → Traefik translation (annotations, middlewares), use **`traefik_nginx_migration`** — not ad-hoc YAML snippets. |
330
+
331
+ ### NGINX Migrations
332
+ | Tool | Description |
333
+ |------|-------------|
334
+
335
+ | `traefik_nginx_migration` | **Migrate + revert**: `action=apply|generate|revert`. Apply/generate NGINX→Traefik bundle; revert undoes one Ingress. Optional **`migration_plan`**: per-Ingress overrides ([`docs/TICKET_MIGRATION_AGENT_INTELLIGENCE.md`](docs/TICKET_MIGRATION_AGENT_INTELLIGENCE.md), [test guide](docs/TRAEFIK_NGINX_MIGRATION_TEST_GUIDE.md)). Inventory: `traefik://migration/nginx-ingress-scan`; analysis: `traefik://migration/nginx-ingress-analyze` / `read_resource traefik://migration/nginx-runbook`. `action=apply` requires `MCP_ALLOW_WRITE=true`. Spec [`docs/ING_SWITCH_MCP_IMPLEMENTATION.md`](docs/ING_SWITCH_MCP_IMPLEMENTATION.md), tracker [`docs/ING_SWITCH_MIGRATION_TASK_TRACKER.md`](docs/ING_SWITCH_MIGRATION_TASK_TRACKER.md), audit [`docs/ING_SWITCH_MIGRATION_AUDIT.md`](docs/ING_SWITCH_MIGRATION_AUDIT.md). Reference code: [`docs/ing-switch/`](docs/ing-switch/). |
336
+
337
+ #### What the client receives (`traefik_nginx_migration`)
338
+ - For `action=apply`: Status on applied resources (Middlewares created, Ingresses patched).
339
+ - For `action=generate`: Agent guidelines and confirmation of generated artifacts.
340
+ - For `action=revert`: JSON status for the single-Ingress rollback.
341
+ - Guidance linking back to read-only MCP resources (`nginx-runbook`) for viewing full YAML.
342
+
343
+ ---
344
+
345
+ ## Available Resources
346
+
347
+ | Resource URI | Description |
348
+ |--------------|-------------|
349
+ | `traefik://traffic/routes/list` | Reads all dynamic `TraefikServices` operating globally in the cluster |
350
+ | `traefik://traffic/{namespace}/{route_name}/distribution`| Precise read-only overview of active rules (Weights, Attached Middlewares) |
351
+ | `traefik://metrics/{namespace}/{service}/summary`| Retrieve instantaneous 5xx/4xx error bounds and P99 latency maps |
352
+ | `traefik://metrics/prometheus/status`| Confirm metrics backend connectivity |
353
+ | `traefik://anomalies/detected` | Observe real-time flagged connection errors flagged natively |
354
+ | `traefik://anomalies/history/{namespace}` | Audit log covering historical anomaly detection |
355
+ | `traefik://migration/nginx-to-traefik` | Base status overview of active proxy migrations |
356
+ | `traefik://migration/nginx-to-traefik/{phase}`| Targeted analytics per migration phase (e.g., phase1, phase3) |
357
+ | `traefik://migration/nginx-ingress-scan` | **Live** Ingress inventory: **`paths`** + **`nginxAnnotations`** (`traefik.mcp/nginx-ingress-scan/2`) |
358
+ | `traefik://migration/nginx-ingress-scan/{namespace}` | Same digest scoped to one namespace |
359
+ | `traefik://migration/nginx-ingress-analyze` | Full NGINX→Traefik **compatibility** analysis, cluster-wide (`traefik.mcp/nginx-ingress-analyze/1`) |
360
+ | `traefik://migration/nginx-ingress-analyze/{namespace}` | Same analysis scoped to one namespace |
361
+
362
+ ---
363
+
364
+ ## Usage
365
+
366
+ Supported workflows with prompt examples and links to detailed guides:
367
+
368
+ | Workflow | Prompt Example | Documentation |
369
+ |----------|----------------|---------------|
370
+ | **Traffic Flow (Weighted Canary)** | `"Create a 90/10 weighted canary route 'api-route' in production for api.example.com."` | [TRAFFIC_MANAGEMENT_TEST_GUIDE.md](docs/TRAEFIK_TRAFFIC_MANAGEMENT_TEST_GUIDE.md) |
371
+ | **Header-Based Canary** | `"Route only traffic with the header 'X-Canary: true' to the canary pod."` | [HEADER_CANARY_TEST_GUIDE.md](docs/TRAEFIK_HEADER_CANARY_TEST_GUIDE.md) |
372
+ | **Traffic Mirroring (Shadow Launch)** | `"Mirror 20% of production traffic to the new service without affecting user responses."` | [SHADOW_LAUNCH_TEST_GUIDE.md](docs/TRAEFIK_SHADOW_LAUNCH_TEST_GUIDE.md) |
373
+ | **TCP Routing & Middlewares** | `"Create a TCP route for Postgres on port 5432 with an IP Allowlist middleware."` | [TCP_ROUTING_TEST_GUIDE.md](docs/TRAEFIK_TCP_ROUTING_TEST_GUIDE.md) |
374
+ | **NGINX to Traefik Migration** | `"Run the NGINX to Traefik migration for the 'ecommerce' namespace to translate annotations."` | [NGINX_MIGRATION_TEST_GUIDE.md](docs/TRAEFIK_NGINX_MIGRATION_TEST_GUIDE.md) |
375
+ | **Agentic Override (Supervised Autonomy)**| `"Apply the migration but ignore the 'auth-url' annotation and inject my 'custom-auth' middleware."`| [WORKFLOW_JOURNEYS.md](docs/WORKFLOW_JOURNEYS.md) |
376
+ | **Instant App Protection** | `"Add a rate limit of 100 rps and a 5xx circuit breaker to the frontend route."` | [PROMPT_REFERENCE.md](docs/PROMPT_REFERENCE.md) |
377
+
378
+ See [WORKFLOW_JOURNEYS.md](docs/WORKFLOW_JOURNEYS.md) for the full workflow reference and [PROMPT_REFERENCE.md](docs/PROMPT_REFERENCE.md) for natural-language prompts.
379
+
380
+ ---
381
+
382
+ ## Project Structure
383
+
384
+ ```text
385
+ traefik-mcp-server/
386
+ ├── traefik_mcp_server/ # Main package
387
+ │ ├── tools/ # MCP Tools
388
+ │ │ ├── traffic.py # Route manipulation
389
+ │ │ ├── middleware.py # Protection logic
390
+ │ │ └── migrations/ # NGINX translation engines
391
+ │ ├── resources/ # MCP Resources
392
+ │ │ ├── traffic_resources.py
393
+ │ │ └── anomaly_resources.py
394
+ │ ├── services/ # Business logic
395
+ │ │ ├── traefik_service.py # Traefik native K8s wrapper
396
+ │ │ └── generator_service.py # YAML conversion logic
397
+ │ ├── server/ # FastMCP server setup
398
+ │ ├── exceptions/ # Error definitions
399
+ │ ├── config.py # Environment parsing
400
+ │ └── main.py # Entry point
401
+ ├── tests/ # Test suites natively
402
+ ├── Dockerfile # Containerization
403
+ ├── docker-entrypoint.sh # System load sequence
404
+ ├── pyproject.toml # Package definitions mapping Python 3.10
405
+ └── README.md # This documentation
406
+ ```
407
+
408
+ ---
409
+
410
+ ## Roadmap
411
+
412
+ **Shipped:**
413
+
414
+ - [x] Full CRD support for `IngressRoute` and `TraefikService`
415
+ - [x] Powerful weighted network routing generators and Simple IngressRoutes
416
+ - [x] TCP Routing and global Traffic Mirroring (Shadow Launch) capabilities
417
+ - [x] NGINX to Traefik automated conversion pipelines with AI Agentic Overrides
418
+ - [x] Context APIs fetching network configuration distribution
419
+
420
+ **Coming next:**
421
+
422
+ - [ ] Direct GatewayAPI (v1beta1) HTTPRoute translation
423
+ - [ ] Automated internal TLS bindings directly onto routes natively
424
+
425
+ See [open issues](https://github.com/talkops-ai/talkops-mcp/issues) for the full list of proposed feature sets proactively tracked transparently!
426
+
427
+ ---
428
+
429
+ ## Contributing
430
+
431
+ Contributions are welcome. The process is straightforward:
432
+
433
+ 1. Fork the repo
434
+ 2. Create a branch (`git checkout -b feature/NetworkFix`)
435
+ 3. Make your changes and commit
436
+ 4. Push and open a PR
437
+
438
+ If you're considering something bigger, open an issue first so we can align on the approach natively via discussions.
439
+
440
+ ---
441
+
442
+ ## FAQ
443
+
444
+ <details>
445
+ <summary><b>Which MCP clients work with this?</b></summary>
446
+ Any HTTP transport compatible client including Claude specifically mapping locally into <code>http://localhost:8769/mcp</code>.
447
+ </details>
448
+
449
+ <details>
450
+ <summary><b>Does this control pod orchestrations natively?</b></summary>
451
+ No. This orchestrates Edge proxies efficiently checking bounds physically. Orchestration logic mapping scaling metrics requires companion access using <b>Argo Rollout MCP Server</b> proactively!
452
+ </details>
453
+
454
+ <details>
455
+ <summary><b>Are execution patterns simulated locally?</b></summary>
456
+ Tools executed natively run valid mutation calls updating Traefik controllers directly dynamically across mapped structures locally natively across contexts perfectly!
457
+ </details>
458
+
459
+ ---
460
+
461
+ ## Troubleshooting
462
+
463
+ ### Timeouts or Networking Errors
464
+
465
+ 1. Verify execution bindings hitting correct IPs correctly directly. Verify context topologies mapping explicitly. Set your MCP HTTP timeouts longer directly resolving initial load bounds cleanly optimally properly globally.
466
+
467
+ ### Migration Blocks
468
+
469
+ Examine exact resource naming mappings checking old annotations perfectly.
470
+
471
+ ---
472
+
473
+ ## Security Considerations
474
+
475
+ - **Never hardcode generic authentication** directly into `BasicAuth` middleware rules.
476
+ - **Ensure network topologies securely match bounds.**
477
+ - **Execute tools locally checking variables prior securely natively.**
478
+
479
+ ---
480
+
481
+ ## License
482
+
483
+ Apache 2.0 — see [LICENSE](../../LICENSE).
484
+
485
+ ---
486
+
487
+ ## Contact
488
+
489
+ **TalkOps AI** — [github.com/talkops-ai](https://github.com/talkops-ai)
490
+
491
+ **Project:** [github.com/talkops-ai/talkops-mcp](https://github.com/talkops-ai/talkops-mcp)
492
+
493
+ **Discord:** [Join the community](https://discord.gg/tSN2Qn9uM8)
494
+
495
+ ---
496
+
497
+ ## Acknowledgments
498
+
499
+ - [Model Context Protocol](https://modelcontextprotocol.io/) properly enabling agent capabilities.
500
+ - [FastMCP](https://github.com/jlowin/fastmcp) wrapper layer implementations directly securely natively!
501
+ - [Traefik Labs](https://traefik.io/) explicitly providing amazing proxies properly globally!