initial commit

03-CRD/MCPServer.md

@@ -0,0 +1,104 @@
+# MCPServer
+
+#sympozium #crd #mcp
+
+## Definicja
+
+`MCPServer` zarządza lifecycle **serwerów MCP (Model Context Protocol)** w klastrze. Wspiera stdio (z HTTP adapterem), HTTP i external transport.
+
+**Plik:** `api/v1alpha1/mcpserver_types.go`
+
+## Spec
+
+```yaml
+apiVersion: sympozium.ai/v1alpha1
+kind: MCPServer
+metadata:
+  name: github-mcp
+spec:
+  transportType: stdio|http
+
+  # Dla external/pre-existing serwerów (bez deploymentu):
+  url: "http://external-mcp.example.com/mcp"
+
+  # Dla managed serwerów:
+  deployment:
+    image: ghcr.io/my-org/github-mcp:v1
+    cmd: "/usr/bin/github-mcp-server"
+    args: ["--stdio"]
+    port: 8080
+    env:
+      LOG_LEVEL: info
+    secretRefs:
+      - name: github-token
+    resources:
+      requests:
+        cpu: "100m"
+        memory: "128Mi"
+    serviceAccountName: github-mcp-sa
+
+  toolsPrefix: gh               # Prefix unikający kolizji
+  timeout: 30
+  replicas: 1
+  toolsAllow: [create_issue]    # Whitelist narzędzi
+  toolsDeny: [delete_repo]      # Blacklist narzędzi
+```
+
+## Dwa tryby
+
+### Managed (z deployment spec)
+Controller tworzy Deployment + Service:
+- stdio → HTTP adapter automatycznie
+- Probing narzędzi po starcie
+- Lifecycle zarządzany przez controller
+
+### External (z URL)
+Tylko referencja do istniejącego serwera:
+- Brak deploymentu
+- Probing narzędzi pod podanym URL
+- Użytkownik zarządza lifecycle
+
+## Tool Discovery
+
+Po starcie MCPServer, controller:
+1. Probeuje endpoint MCP
+2. Odkrywa dostępne narzędzia
+3. Aplikuje `toolsAllow` / `toolsDeny` filtry
+4. Zapisuje listę narzędzi w `status.tools`
+5. Prefiksuje nazwy: `gh_create_issue`, `gh_list_repos`
+
+## Status
+
+```yaml
+status:
+  ready: true
+  url: "http://github-mcp.sympozium-system.svc:8080"
+  toolCount: 12
+  tools: [create_issue, list_repos, ...]
+```
+
+## Integracja z agentem
+
+```
+SympoziumInstance → mcpServers: [{name: github-mcp, toolsPrefix: gh}]
+    ↓
+AgentRun tworzony → Reconciler:
+  1. Rozwiązuje MCPServer CR → pobiera URL ze status
+  2. Tworzy MCP ConfigMap z konfiguracją serwerów
+  3. Dodaje mcp-bridge sidecar do poda
+    ↓
+Agent w podzie:
+  - mcp-bridge sidecar tłumaczy tool calls → MCP protocol
+  - Narzędzia widoczne jako prefixed: gh_create_issue, gh_list_repos
+```
+
+## Tool namespacing
+
+Prefiksy zapobiegają kolizjom gdy wiele MCP serwerów jest aktywnych:
+- `gh_create_issue` (GitHub MCP)
+- `jira_create_ticket` (Jira MCP)
+- `slack_send_message` (Slack MCP)
+
+---
+
+Powiązane: [[MCP Servers - Model Context Protocol]] | [[SympoziumInstance]] | [[Przepływ danych i IPC]]