Skip to content

Commit 1a5bf83

Browse files
crivetimihaicrivetimihai
committed
pre-commit checks
Signed-off-by: Mihai Criveti <[email protected]>
1 parent 15675ab commit 1a5bf83

File tree

4 files changed

+216
-10
lines changed

4 files changed

+216
-10
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
TODO.md
12
minikube-*
23
.htpasswd
34
.env.gcr

‎README.md

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -119,16 +119,17 @@ mcpgateway # login to http://127.0.0.1:4444
119119
# Optional: run in background with configured password/key and listen to all IPs
120120
BASIC_AUTH_PASSWORD=password JWT_SECRET_KEY=my-test-key mcpgateway --host 0.0.0.0 --port 4444 & bg
121121

122-
# List all options
123-
mcpgateway --help
122+
# List version / help
123+
mcpgateway --help; mcpgateway --version
124124

125-
# Generate your JWT token from the key
126-
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)
125+
# Generate your JWT token from the key and list it
126+
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key); echo $MCPGATEWAY_BEARER_TOKEN
127127

128128
# Run a local MCP Server (github) listening on SSE http://localhost:8000/sse
129129
pip install uvenv
130130
npx -y supergateway --stdio "uvenv run mcp-server-git" # requires node.js and npx
131131
# or time: npx -y supergateway --stdio "uvenv run mcp_server_time -- --local-timezone=Europe/Dublin" --port 8002
132+
# or: python3 -m mcpgateway.translate --stdio "uvenv run mcp-server-git" --port 8000
132133

133134
#--------------------------------------------
134135
# Register the MCP Server with the gateway and test it
@@ -170,7 +171,7 @@ curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/s
170171

171172
# To stop the running process, you can either:
172173
fg # Return the process to foreground, you can not Ctrl + C, or:
173-
pkill mcpgateway
174+
pkill mcpgateway; # ps -ef | grep mcpgateway | awk '{print $2}' | xargs
174175

175176
# Optionally, test the stdio wrapper to mirror tools from the gateway:
176177
# This lets you connect to the gateway with tools that don't support SSE:
@@ -196,7 +197,7 @@ docker run -d --name mcpgateway \
196197
-e BASIC_AUTH_PASSWORD=changeme \
197198
-e AUTH_REQUIRED=true \
198199
-e DATABASE_URL=sqlite:///./mcp.db \
199-
ghcr.io/ibm/mcp-context-forge:latest
200+
ghcr.io/ibm/mcp-context-forge:0.1.1
200201

201202
docker logs mcpgateway
202203
```
@@ -205,7 +206,7 @@ You can now access the UI at [http://localhost:4444/admin](http://localhost:4444
205206

206207
> 💡 You can also use `--env-file .env` if you have a config file already. See the provided [.env.example](.env.example)
207208
> 💡 To access local tools, consider using `--network=host`
208-
> 💡 Consider using a stable / release version of the image, ex: `ghcr.io/ibm/mcp-context-forge:v0.1.1`
209+
> 💡 Consider using a stable / release version of the image, ex: `ghcr.io/ibm/mcp-context-forge:v0.1.1` rather than `latest`
209210
210211
### Optional: Mount a local volume for persistent SQLite storage
211212

@@ -215,6 +216,8 @@ You can now access the UI at [http://localhost:4444/admin](http://localhost:4444
215216

216217
### Generate a token for API access
217218

219+
A JWT token is required to access all API endpoints. This can be generated with the provided CLI, specifying a username, secret (that matches the one defined in `.env` for the gateway) and expiration time (in seconds).
220+
218221
```bash
219222
export MCPGATEWAY_BEARER_TOKEN=$(docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 100800 --secret my-test-key)
220223
echo ${MCPGATEWAY_BEARER_TOKEN}
@@ -233,7 +236,7 @@ curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
233236

234237
### Running the MCP Gateway stdio wrapper
235238

236-
The `mcpgateway.wrapper` lets you connect to the gateway over **stdio**, while retaining authentication using the JWT token when the wrapper connect to a remote gateway. You should run this from a MCP client. You can test this from a shell with:
239+
The `mcpgateway.wrapper` lets you connect to the gateway over **stdio**, while retaining authentication using the JWT token when the wrapper connect to a remote gateway. You should run this from a MCP client (ex: defined in the `json` configuration of Claude/Copilot, etc). You can test this from a shell with:
237240

238241
```bash
239242
# Set environment variables
@@ -257,7 +260,7 @@ docker run --rm -i \
257260
-e MCP_SERVER_CATALOG_URLS=http://host.docker.internal:4444/servers/1 \
258261
-e MCP_TOOL_CALL_TIMEOUT=120 \
259262
-e MCP_WRAPPER_LOG_LEVEL=DEBUG \
260-
ghcr.io/ibm/mcp-context-forge:latest \
263+
ghcr.io/ibm/mcp-context-forge:0.1.1 \
261264
python3 -m mcpgateway.wrapper
262265
```
263266

@@ -339,7 +342,7 @@ docker run -i --rm \
339342
-e MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1 \
340343
-e MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
341344
-e MCP_TOOL_CALL_TIMEOUT=120 \
342-
ghcr.io/ibm/mcp-context-forge:latest \
345+
ghcr.io/ibm/mcp-context-forge:0.1.1 \
343346
python3 -m mcpgateway.wrapper
344347
```
345348

‎docs/docs/deployment/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ nav:
77
- openshift.md
88
- minikube.md
99
- helm.md
10+
- argocd.md
1011
- google-cloud-run.md
1112
- ibm-code-engine.md
1213
- aws.md

‎docs/docs/deployment/argocd.md

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# 🚢 Deploying the MCP Gateway Stack with **Argo CD**
2+
3+
This guide shows how to operate the **MCP Gateway Stack** with a *Git‑Ops* workflow powered by [Argo CD](https://argo-cd.readthedocs.io). Once wired up, every commit to the repository becomes an automatic deployment (or rollback) to your Kubernetes cluster.
4+
5+
> 🌳 Git source of truth:
6+
> `https://github.com/IBM/mcp-context-forge`
7+
>
8+
> * **App manifests:** `k8s/` (Kustomize‑ready)
9+
> * **Helm chart (optional):** `charts/mcp-stack`
10+
11+
---
12+
13+
## 📋 Prerequisites
14+
15+
| Requirement | Notes |
16+
| ----------------- | ---------------------------------------------------------------- |
17+
| Kubernetes ≥ 1.23 | Local (Minikube/kind) or managed (EKS, AKS, GKE, etc.) |
18+
| Argo CD ≥ 2.7 | Server & CLI (this guide installs server into the cluster) |
19+
| kubectl | Configured to talk to the target cluster |
20+
| Git access | The cluster must be able to pull the repo (public or deploy‑key) |
21+
22+
---
23+
24+
## 🛠 Step 1 – Install Argo CD (once per cluster)
25+
26+
```bash
27+
# Namespace + core components
28+
kubectl create namespace argocd
29+
kubectl apply -n argocd \
30+
-f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
31+
32+
# Wait for the server component
33+
kubectl -n argocd rollout status deploy/argocd-server
34+
```
35+
36+
### Install the CLI
37+
38+
```bash
39+
# macOS
40+
brew install argocd
41+
42+
# Linux (single‑binary)
43+
curl -sSL -o /tmp/argocd \
44+
https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
45+
sudo install -m 555 /tmp/argocd /usr/local/bin/argocd
46+
```
47+
48+
Verify:
49+
50+
```bash
51+
argocd version --client
52+
```
53+
54+
---
55+
56+
## 🔐 Step 2 – Initial Login
57+
58+
Forward the API/UI to your workstation (leave running):
59+
60+
```bash
61+
kubectl -n argocd port-forward svc/argocd-server 8083:443
62+
```
63+
64+
Fetch the one‑time admin password and log in:
65+
66+
```bash
67+
PASS="$(kubectl -n argocd get secret argocd-initial-admin-secret \
68+
-o jsonpath='{.data.password}' | base64 -d)"
69+
argocd login localhost:8083 \
70+
--username admin --password "$PASS" --insecure
71+
```
72+
73+
Open the web UI → [http://localhost:8083](http://localhost:8083) (credentials above).
74+
75+
---
76+
77+
## 🚀 Step 3 – Bootstrap the Application
78+
79+
Create an Argo CD *Application* that tracks the **`k8s/`** folder from the main branch:
80+
81+
```bash
82+
APP=mcp-gateway
83+
REPO=https://github.com/IBM/mcp-context-forge.git
84+
85+
argocd app create "$APP" \
86+
--repo "$REPO" \
87+
--path k8s \
88+
--dest-server https://kubernetes.default.svc \
89+
--dest-namespace default \
90+
--sync-policy automated \
91+
--revision main
92+
```
93+
94+
Trigger the first sync:
95+
96+
```bash
97+
argocd app sync "$APP"
98+
```
99+
100+
Argo CD will apply all manifests and keep them in the *Synced* 🌿 / *Healthy* 💚 state.
101+
102+
---
103+
104+
## ✅ Step 4 – Verify Deployment
105+
106+
```bash
107+
kubectl get pods,svc,ingress
108+
argocd app list
109+
argocd app get mcp-gateway
110+
```
111+
112+
If using the sample Ingress:
113+
114+
```bash
115+
curl http://gateway.local/health
116+
```
117+
118+
Otherwise, port‑forward:
119+
120+
```bash
121+
kubectl port-forward svc/mcp-context-forge 8080:80 &
122+
curl http://localhost:8080/health
123+
```
124+
125+
---
126+
127+
## 🔄 Day‑2 Operations
128+
129+
### Sync after a new commit
130+
131+
```bash
132+
argocd app sync mcp-gateway
133+
```
134+
135+
### View diff before syncing
136+
137+
```bash
138+
argocd app diff mcp-gateway
139+
```
140+
141+
### Roll back to a previous revision
142+
143+
```bash
144+
argocd app history mcp-gateway
145+
argocd app rollback mcp-gateway <REVISION>
146+
```
147+
148+
### Disable / enable auto‑sync
149+
150+
```bash
151+
# Pause auto‑sync
152+
a rgocd app set mcp-gateway --sync-policy none
153+
# Re‑enable
154+
argocd app set mcp-gateway --sync-policy automated
155+
```
156+
157+
---
158+
159+
## 🧹 Uninstall
160+
161+
```bash
162+
# Delete the application (leaves cluster objects intact)
163+
argocd app delete mcp-gateway --yes
164+
165+
# Remove Argo CD completely\ nkubectl delete ns argocd
166+
```
167+
168+
---
169+
170+
## 🧰 Makefile Shortcuts
171+
172+
The repository ships with ready‑made targets:
173+
174+
| Target | Action |
175+
| --------------------------- | ---------------------------------------------------------------------- |
176+
| `make argocd-install` | Installs Argo CD server into the current cluster |
177+
| `make argocd-forward` | Port‑forwards UI/API on [http://localhost:8083](http://localhost:8083) |
178+
| `make argocd-app-bootstrap` | Creates & auto‑syncs the *mcp‑gateway* application |
179+
| `make argocd-app-sync` | Forces a manual sync |
180+
181+
Run `make help` to list them all.
182+
183+
---
184+
185+
## 🧯 Troubleshooting
186+
187+
| Symptom | Fix |
188+
| ------------------ | ------------------------------------------------------------------------------------------------- |
189+
| `ImagePullBackOff` | Check image name / pull secret & that the repo is public or credentials are configured in Argo CD |
190+
| `SyncFailed` | `argocd app logs mcp-gateway` for details; often due to immutable fields |
191+
| Web UI 404 | Ensure `argocd-forward` is still running, or expose via Ingress/LoadBalancer |
192+
| RBAC denied | Argo CD needs ClusterRoleBinding for non‑default namespaces – see docs |
193+
194+
---
195+
196+
## 📚 Further Reading
197+
198+
* Argo CD Docs – [https://argo-cd.readthedocs.io](https://argo-cd.readthedocs.io)
199+
* GitOps Pattern – [https://www.weave.works/technologies/gitops/](https://www.weave.works/technologies/gitops/)
200+
* Kustomize – [https://kubectl.docs.kubernetes.io/references/kustomize/](https://kubectl.docs.kubernetes.io/references/kustomize/)
201+
* Helm + Argo CD – [https://argo-cd.readthedocs.io/en/stable/user-guide/helm/](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/)

0 commit comments

Comments
 (0)