From e96bab114ea1a58f3ea7bd5ab40d4645d456cd8f Mon Sep 17 00:00:00 2001 From: Shahovalov MIkhail Date: Tue, 14 Apr 2026 11:40:37 +0300 Subject: [PATCH] =?UTF-8?q?=D0=98=D0=BD=D0=B8=D1=86=D0=B8=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=D0=B7=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20Memory?= =?UTF-8?q?=20Bank:=20projectbrief,=20productContext,=20activeContext,=20s?= =?UTF-8?q?ystemPatterns,=20techContext,=20progress?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- memory-bank/activeContext.md | 142 +++++++++++++++++ memory-bank/productContext.md | 166 +++++++++++++++++++ memory-bank/progress.md | 153 ++++++++++++++++++ memory-bank/projectbrief.md | 63 ++++++++ memory-bank/systemPatterns.md | 292 ++++++++++++++++++++++++++++++++++ memory-bank/techContext.md | 271 +++++++++++++++++++++++++++++++ 6 files changed, 1087 insertions(+) create mode 100644 memory-bank/activeContext.md create mode 100644 memory-bank/productContext.md create mode 100644 memory-bank/progress.md create mode 100644 memory-bank/projectbrief.md create mode 100644 memory-bank/systemPatterns.md create mode 100644 memory-bank/techContext.md diff --git a/memory-bank/activeContext.md b/memory-bank/activeContext.md new file mode 100644 index 0000000..dcd477a --- /dev/null +++ b/memory-bank/activeContext.md @@ -0,0 +1,142 @@ +# Active Context — Текущее состояние работы + +## 📍 Где мы находимся + +### Состояние проекта + +**LazyBear MCP Server** находится на этапе **Development**. Сервер предоставляет MCP инструменты для работы с: +- ✅ **Jira** — Issues, JQL, комментарии +- ✅ **Confluence** — Страницы, пространства +- ✅ **Kubernetes** — Deployments, Pods, Services, Ingress +- ✅ **TUI** — Интерактивная консольная панель + +### Последнее обновление кода + +**Commit**: `d12e9873f0964f2c275a634cda80b161c83f9bbb` + +### Текущий фокус + +**Активная разработка**: Инициализация Memory Bank для поддержания документации между сессиями. + +**Следующие шаги**: +1. ✅ Создать Memory Bank структуру +2. 🔄 Продолжить документирование архитектуры и паттернов +3. ⏳ Обновлять Memory Bank после значимых изменений + +## 🔍 Важные решения + +### Архитектурные паттерны + +| Паттерн | Описание | Где используется | +|---------|----------|------------------| +| **Single HTTP Server** | Один транспорт MCP | Program.cs — один AddMcpServer | +| **Tool Registry** | Регистрация модулей | ToolRegistryService.RegisterModule | +| **Client Provider** | Factory для клиентов | K8sClientProvider, JiraClientProvider | +| **TUI First** | TUI как основной UI | RazorConsole в Program.cs | + +### Технические решения + +- **MCP Protocol 1.2.0** — HTTP transport +- **.NET 10 SDK** — Пин в global.json +- **ASP.NET Core 9** — HTTP server +- **RazorConsole** — TUI framework +- **Kubernetes Client** — Через kubeconfig + +### Конфигурация + +**appsettings.json**: +```json +{ + "Kubernetes": { + "KubeconfigPath": "", // Fallback к defaults + "DefaultNamespace": "default" + }, + "Jira": { + "Url": "", // Требуется для Jira tools + "Token": "", + "Project": "" + }, + "Confluence": { + "Url": "", + "Token": "", + "Username": "", + "SpaceKey": "" + } +} +``` + +## 🚧 Текущая работа + +### Что работает + +- ✅ MCP HTTP transport активен +- ✅ TUI запуск через RazorConsole +- ✅ Инструменты Jira/Confluence/Kubernetes зарегистрированы +- ✅ Локализация RU/EN (клавиша L) + +### Что в разработке/тестировании + +- 🔄 Memory Bank инициализация +- ⏳ Тестирование через MCP Inspector +- ⏳ Интеграция с IDE (Codex, VS Code) + +### Известные проблемы + +- Jira требует настройки `Jira:Url` +- Kubernetes: пустой `KubeconfigPath` использует fallback +- Razor Pages в `Pages/` не активирован (не используется) + +## 📋 Следующие действия + +### Приоритет 1: Конфигурация + +```bash +# Настроить Jira +Jira:Url=https://your-jira.url +Jira:Token=your-token +Jira:Project=LAZYBEAR + +# Настроить K8s +Kubernetes:KubeconfigPath=~/.kube/config +``` + +### Приоритет 2: Тестирование + +```bash +# Запустить сервер +dotnet run --project LazyBear.MCP + +# Открыть MCP Inspector +npx @modelcontextprotocol/inspector dotnet run --project LazyBear.MCP +``` + +### Приоритет 3: Документация + +- 📝 Обновлять activeContext.md после значимых изменений +- 📝 Добавлять секции в systemPatterns.md при введении новых паттернов + +## 💡 Выводы и наблюдения + +### Изученное о проекте + +1. **Проект уже полностью функционален** — все модули готовы +2. **TUI First подход** — основной UI консольный, HTTP в фоне +3. **Minimal API Style** — чистый код, DI через сервисы +4. **Локализация встроена** — RU/EN переключение через клавишу + +### Предпочтения проекта + +- **Комментарии и сообщения**: Русский язык +- **Код и переменные**: Английский язык +- **Style**: Clean code, minimal abstractions +- **Documentation**: Markdown в memory-bank/ + +### Важные уроки + +- MCP tools авт. регистрируются из assembly через `WithToolsFromAssembly()` +- IToolModule интерфейсы — способ добавлять новые инструменты +- RazorConsole управляет консолью, HTTP host работает в фоне + +--- + +*Файл автоматически обновляется при значимых изменениях проекта. Читать при начале новой сессии.* \ No newline at end of file diff --git a/memory-bank/productContext.md b/memory-bank/productContext.md new file mode 100644 index 0000000..ba2aab6 --- /dev/null +++ b/memory-bank/productContext.md @@ -0,0 +1,166 @@ +# Product Context — Зачем существует LazyBear MCP Server + +## Проблема, которую решает проект + +### Контекст пользователя + +DevOps инженер и разработчики ежедневно работают с: +- **Jira** — создание, отслеживание, обновление задач +- **Confluence** — документация, руководства, знания +- **Kubernetes** — управление контейнерами, деплоями, сетями + +### Точка боли + +**Ручная работа**: Каждый инструмент требует отдельного CLI вызова: +```bash +# Jira CLI +jira issue create --project LAZYBEAR ... + +# Confluence CLI +confluence create --space LAZYBEAR ... + +# Kubernetes +kubectl create deployment nginx --image=nginx:latest +kubectl scale deployment nginx --replicas=3 +``` + +**Неэффективно**: Много времени тратится на переключение контекста, ввод команд, копирование значений. + +**Нет единой точки управления**: Разрозненные инструменты, неясно что активно и где. + +### Решение + +**LazyBear MCP Server** объединяет все инструменты в один HTTP сервер: +- Один вызов от IDE вызывает нужное действие +- JSON-параметры вместо сложных CLI флага +- Визуальный мониторинг через TUI +- Локализация на русском языке + +### Пользовательский опыт + +**До интеграции**: +- 5-10 CLI команд для рутинных задач +- Переключение между терминалами и браузерами +- Потеря контекста между инструментами + +**После интеграции**: +- 1 JSON вызов от IDE решает задачу +- Единая консоль TUI показывает состояние кластера +- Русская локализация для команды RU +- Свободный фокус на логике работы + +## Целевой пользователь + +### Persona: DevOps Engineer + +**Характеристики**: +- Работает с Kubernetes кластерами +- Создает и обновляет Jira задачи +- Документирует процессы в Confluence +- Ценит автоматизацию + +**Цели**: +- Минимизировать ручной ввод +- Быстро реагировать на инциденты +- Поддерживать актуальную документацию + +**Боли**: +- Утомительный ручной ввод +- Потеря контекста между инструментами +- Недостаток visibility в работе инструментов + +### Persona: Developer + +**Характеристики**: +- Работает в IDE (Codex, VS Code) +- Использует AI-ассистенты +- Ценит быструю обратную связь + +**Цели**: +- Автоматизировать рутину через AI +- Быстрый доступ к информации о сервисах + +**Боли**: +- AI не знает состояние K8s/Jira без интеграции +- Потеря времени на setup команд + +## Успешные сценарии использования + +### Сценарий 1: Инцидент в Kubernetes + +``` +User (via AI): "В поде nginx-abc123 упал. Попробуй рестарт." +↓ +AI вызывает: k8sPodsTools/restartPod(name="nginx-abc123") +↓ +LazyBear вызывает K8s API +↓ +Получает результат +↓ +AI сообщает: "Под nginx-abc123 перезапущен" +``` + +### Сценарий 2: Создание задачи инцидента + +``` +User (via AI): "Создать Jira задачу на проблему с nginx" +↓ +AI вызывает: jiraTools/createIssue({ + project: "LAZYBEAR", + summary: "Нестабильность nginx", + description: "...", + type: "INCIDENT" +}) +↓ +Jira задача создана +``` + +### Сценарий 3: Мониторинг через TUI + +``` +User запускает dotnet run +↓ +TUI показывает: +- Список deployed деплоев +- Статус подов +- Последние events +- Кнопки действий +``` + +## Метрики успеха + +| Метрика | Цель | +|---------|------| +| Время на задачу (Jira) | -50% после интеграции | +| Время на задачу (K8s) | -70% после интеграции | +| Довольство пользователей | >4.5/5 | +| Количество инцидентов | Снизить на -30% | + +## Нестандартные требования + +### Локализация + +- **Первичный язык**: Русский (RU) +- **Вторичный язык**: Английский (EN) +- **Переключение**: Клавиша L в TUI + +### TUI First + +- Основной интерфейс — консольная панель +- HTTP MCP работает в фоне +- TUI владелец консоли + +### Swagger для API + +- `/swagger` для документации API +- Для разработчиков клиентов + +## Этические соображения + +- **Конфиденциальность**: Контенджер не получает реальные секреты +- **Transparency**: Все действия логируются +- **Fallback**: K8s config fallback к defaults + +--- + +*Документ описывает почему проект существует и как должен работать пользователь.* \ No newline at end of file diff --git a/memory-bank/progress.md b/memory-bank/progress.md new file mode 100644 index 0000000..60b5909 --- /dev/null +++ b/memory-bank/progress.md @@ -0,0 +1,153 @@ +# Progress — Состояние разработки + +## 📊 Что работает + +### Jira Integration + +- ✅ Создание Issues через JQL +- ✅ Поиск Issues по фильтру +- ✅ Обновление Issues (статус, приоритет) +- ✅ Работа с комментариями (добавление, получение) +- ✅ Создание ссылок Issue + +### Confluence Integration + +- ✅ CRUD операции над страницами +- ✅ Поиск страниц +- ✅ Перемещение страниц между пространствами +- ✅ Создание/ред. страниц + +### Kubernetes Integration + +- ✅ Создание/удаление Deployments +- ✅ Scale deployments (replicas) +- ✅ Работа с Services +- ✅ CRUD над Ingress ресурсами +- ✅ Мониторинг Pods +- ✅ Restart Pods +- ✅ Описание Deployments/Pods/Services + +### MCP Server + +- ✅ HTTP Transport MCP 1.2.0 +- ✅ TUI через RazorConsole +- ✅ Авто-регистрация инструментов +- ✅ Регистрация через IToolModule + +### TUI Dashboard + +- ✅ Интерактивная консольная панель +- ✅ Мониторинг Deployments +- ✅ Статус Pods +- ✅ Последние K8s events +- ✅ Кнопки действий + +### Локализация + +- ✅ Поддержка RU/EN языков +- ✅ Переключение клавишей L + +## 📋 Что осталось сделать + +### Known Issues + +| Проблема | Описание | Приоритет | +|----------|---------|----|-| +| Jira:Url config | Требуется настройка в appsettings.json | Medium | +| Kubernetes:KubeconfigPath | Может быть пустым (fallback) | Low | +| RazorPages не активен | `Pages/` существует, но не используется | Info | + +### Pending Features + +- [ ] Добавить тестирование (unit/integration) +- [ ] Document all tools в Swagger +- [ ] Добавить webhook для событий K8s +- [ ] Добавить AI-ассистента для анализа логов +- [ ] Добавить экспорт логов в файлы + +### Upcoming Tasks + +1. **Конфигурация**: Настроить Jira/K8s connection в appsettings.json +2. **Тестирование**: Написать CLI тесты для инструментов +3. **Документация**: Добавить секции в systemPatterns.md при необходимости +4. **Monitoring**: Добавить metrics endpoint для Prometheus + +## 🐛 Известные проблемы + +### Jira Integration + +- `Jira:Url` обязателен в appsettings.json, иначе инициализация провайдера упадет +- `Jira:Token` — требуется авторизация через token +- `Jira:Project` — для создания Issues нужно указать project key + +### Kubernetes Integration + +- `Kubernetes:KubeconfigPath` может быть пустым: + 1. Используется default kubeconfig + 2. Или в-cluster config (если в K8s) +- `Kubernetes:DefaultNamespace` — default namespace для запросов + +### Confluence Integration + +- `Confluence:Url` — URL Confluence сервера +- `Confluence:Token` — API token для авторизации +- `Confluence:SpaceKey` — для некоторых операций требуется space + +### TUI + +- TUI запускается первым и владеет консолью +- HTTP host работает параллельно +- Если пользователь закрывает TUI, HTTP продолжает работать + +### Localization + +- Переключение языков клавишей L в TUI +- UI компоненты поддерживают оба языка +- Тексты берутся из `LocalizationService` + +## 📈 Метрики + +| Метрика | Значение | Цель | +|---------|---------|-----|-| +| Jira задачи создано | TBD | 100+/день | +| K8s операции выполнено | TBD | 50+/день | +| Incidents resolved | TBD | Минимизировать | +| User satisfaction | TBD | >4.5/5 | + +## 📅 Эволюция решений + +### Версия 1.0.0 (текущая) + +- Полный стек инструментов Jira/Confluence/K8s +- TUI мониторинг +- HTTP MCP transport +- Локализация RU/EN + +### Версия 1.1.0 (planned) + +- Тесты для инструментов +- Prometheus metrics +- Webhook события + +### Версия 1.2.0 (future) + +- AI-ассистент для анализа логов +- Export reports в PDF/CSV +- Multi-cluster поддержка + +## ⏩ Текущий статус + +**Состояние**: Development + +**Последний commit**: `d12e9873f0964f2c275a634cda80b161c83f9bbb` + +**Что работает**: Все основные функциональности готовы + +**Что делать дальше**: +1. Настроить Jira/K8s connection (appsettings.json) +2. Тестировать через MCP Inspector +3. Обновлять Memory Bank при значимых изменениях + +--- + +*Файл описывает что работает, что осталось, известные проблемы и прогресс разработки. Обновлять после значимых изменений проекта.* \ No newline at end of file diff --git a/memory-bank/projectbrief.md b/memory-bank/projectbrief.md new file mode 100644 index 0000000..fcebe60 --- /dev/null +++ b/memory-bank/projectbrief.md @@ -0,0 +1,63 @@ +# Project Brief — LazyBear MCP Server + +## Обзор проекта + +**LazyBear MCP Server** — .NET 10 сервер Model Context Protocol (MCP) для автоматизации работы с Jira, Confluence и Kubernetes. + +## Цель проекта + +Предоставить единый HTTP-сервер MCP, который: +- Интегрируется с IDE (Codex, VS Code, OpenCode) через MCP протокол +- Предоставляет инструменты для управления Jira задачами (JQL, комментарии, обновления) +- Работает с Confluence страницами и пространствами +- Управляет Kubernetes ресурсами (deployments, pods, services, ingress) +- Предоставляет интерактивную TUI панель для мониторинга кластера + +## Ключевые требования + +### Функциональные требования + +1. **MCP Protocol 1.2.0** — HTTP transport по стандарту Model Context Protocol +2. **Jira Integration** — Создание, поиск, обновление Issues, работа с комментариями +3. **Confluence Integration** — Управление страницами, поиск, перемещение +4. **Kubernetes Management** — CRUD операции над deployments, pods, services, ingress +5. **TUI Dashboard** — Интерактивная консольная панель с RazorConsole +6. **Localization** — Поддержка RU/EN языков в интерфейсе + +### Технические требования + +- **.NET 10 SDK** — SDK зафиксирован в global.json +- **ASP.NET Core 9** — Для HTTP transport +- **Razor Pages** — UI компоненты (активируется при необходимости) +- **Kubernetes Client** — Подключение к K8s API через kubeconfig +- **SQLite/SQL Server** — Опциональная база данных +- **Swagger UI** — `/swagger` endpoint для просмотра API + +## Основные ограничения + +- Jira: требуется настроить `Jira:Url` в appsettings.json +- Kubernetes: `Kubernetes:KubeconfigPath` может быть пустым (используются fallback) +- Конфиденциальность: никогда не хранить реальные секреты, токены, kubeconfig в коде + +## Архитектурные принципы + +1. **Single HTTP Server** — Один транспорт MCP для всех инструментов +2. **Tool Registry Pattern** — Регистрация модулей инструментов через IToolModule +3. **Client Provider Pattern** — Factory для создания K8s/Jira/Confluence клиентов +4. **TUI First** — TUI как основной интерфейс, HTTP MCP в фоне +5. **Minimal API Style** — Clean code, разделение ответственности + +## Даты и версии + +- **Текущая версия**: 1.0.0 +- **Состояние**: Development +- **Комит**: `d12e9873f0964f2c275a634cda80b161c83f9bbb` + +## Репо (Git) + +- **Remote**: `https://git.shahovalov.ru/mikhail/LazyBearWorks.git` +- **Branch**: main (предположительно) + +--- + +*Документ создан для инициализации Memory Bank. Источник правды: код и конфигурация проекта.* \ No newline at end of file diff --git a/memory-bank/systemPatterns.md b/memory-bank/systemPatterns.md new file mode 100644 index 0000000..a2b5b50 --- /dev/null +++ b/memory-bank/systemPatterns.md @@ -0,0 +1,292 @@ +# System Patterns — Архитектура и паттерны + +## 🏗️ Система архитектуры + +``` +┌─────────────────────────────────────────────────────────┐ +│ HTTP Transport Layer │ +│ ModelContextProtocol 1.2.0 HTTP │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ Application Layer (TUI + MCP) │ +│ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐│ +│ │ RazorConsole │ │ McpWeb │ │ ToolRegistry││ +│ │ App.razor │ │ Hosted │ │ Service ││ +│ └───────────────┘ └───────────────┘ └──────────────┘│ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ Services Layer (IToolModule) │ +│ ┌──────────┐ ┌───────────────┐ ┌────────────────────┐ │ +│ │JiraTools │ │ConfluenceTools│ │KubernetesTools │ │ +│ └──────────┘ └───────────────┘ └────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ External API Layer │ +│ ┌──────────┐ ┌───────────────┐ ┌────────────────────┐ │ +│ │ Jira API │ │Confluence API │ │ K8s API │ │ +│ └──────────┘ └───────────────┘ └────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +## Ключевые архитектурные компоненты + +### 1. HTTP Transport Layer + +**File**: `LazyBear.MCP/Program.cs` + +```csharp +var host = Host.CreateDefaultBuilder(args) + .ConfigureServices(services => + { + // MCP-провайдеры + services.AddSingleton(); + services.AddSingleton(); + services.AddSingleton(); + + // Модули инструментов + services.AddSingleton(); + services.AddSingleton(); + services.AddSingleton(); + + // HTTP MCP endpoint в фоне + services.AddHostedService(); + }) + .Build(); +``` + +**Ответственность**: Регистрация HTTP MCP transport и инструментов + +### 2. TUI Layer (RazorConsole) + +**File**: `LazyBear.MCP/Program.cs` (RazorConsole конфиг) + +```csharp +.host.UseRazorConsole(hostBuilder => +{ + hostBuilder.ConfigureServices(services => + { + services.AddSingleton(); + services.AddSingleton(); + // ... TUI сервисы + }); +}); +``` + +**Ответственность**: Консольный интерфейс мониторинга K8s + +### 3. Tool Registry Pattern + +**File**: `LazyBear.MCP/Services/ToolRegistryService.cs` (предположительно) + +```csharp +public class ToolRegistryService +{ + public void RegisterModule(IToolModule module) + { + // Регистрация модуля инструментов + // Модуль появляется в TUI и MCP tools + } +} +``` + +**Ответственность**: Централизованная регистрация инструментов + +**Register в Program.cs**: +```csharp +var registry = host.Services.GetRequiredService(); +foreach (var module in host.Services.GetServices()) +{ + registry.RegisterModule(module); +} +``` + +### 4. Client Provider Pattern + +**Files**: +- `LazyBear.MCP/Services/Kubernetes/K8sClientProvider.cs` +- `LazyBear.MCP/Services/Jira/JiraClientProvider.cs` +- `LazyBear.MCP/Services/Confluence/ConfluenceClientProvider.cs` + +```csharp +public class K8sClientProvider +{ + private readonly IConfiguration _config; + + public KubernetesClientFactory GetClientFactory() + { + // Fallback: explicit kubeconfig → default → in-cluster + var kubeconfigPath = _config["Kubernetes:KubeconfigPath"] + ?? Environment.GetEnvironmentVariable("KUBECONFIG") + ?? string.Empty; + + return new KubernetesClientFactory(kubeconfigPath); + } +} +``` + +**Ответственность**: Создание клиентов внешних API с fallback стратегией + +## Паттерны взаимодействия + +### Pattern 1: Initialize Flow + +``` +Клиент MCP + ↓ [RPC: initialize] +MCP Transport + ↓ +Application (ToolRegistry) + ↓ +Tool Module (Jira/K8s/Confluence) + ↓ +External API (Jira API / K8s API) + ↓ +Ответ через MCP transport +``` + +### Pattern 2: Tools Flow + +``` +Клиент MCP + ↓ [RPC: tool/name] +ToolRegistry.FindTool() + ↓ +ToolModule.Execute() + ↓ +External API + ↓ +Результат → MCP response +``` + +### Pattern 3: Health Check Flow + +``` +HTTP /health + ↓ +McpWebHostedService + ↓ +Лiveness probe статус + ↓ +JSON response +``` + +## DI Container Setup + +```csharp +services.AddSingleton<...>(...) + ↓ +HostedService (McpWeb) + ↓ +RazorConsole (TUI) + ↓ +RunAsync() +``` + +**Примечание**: TUI запускается первым и владеет консолью, HTTP host работает параллельно в фоне. + +## Критические пути реализации + +### Путь 1: Создание Jira задачи + +``` +jiraTools/createIssue(params) + ↓ +JiraToolModule.Execute() + ↓ +JiraClientProvider.GetClient() + ↓ +Jira API REST + ↓ +Ответ с issue key +``` + +### Путь 2: Создание K8s Deployment + +``` +k8sDeploymentTools/createDeployment(params) + ↓ +KubernetesToolModule.Execute() + ↓ +K8sClientProvider.GetClientFactory().CreateClient() + ↓ +K8s API V1/Deployments + ↓ +Ответ с deployment name +``` + +### Путь 3: Мониторинг через TUI + +``` +RazorConsole Render() + ↓ +GetDeployments() → GetPods() → GetEvents() + ↓ +App.razor (RazorConsole) + ↓ +Console.Output +``` + +## Компонентные контракты + +### IToolModule + +```csharp +public interface IToolModule +{ + string Name { get; } + Task ExecuteAsync(IToolContext context, string toolName, object? arguments); +} +``` + +**Ответственность**: Определение одного модуля инструментов (Jira/Confluence/K8s) + +### IToolContext + +Контекст выполнения инструмента: +- MCP connection info +- Tool registry +- DI services +- Logging provider + +### K8sClientFactory + +```csharp +public class KubernetesClientFactory +{ + public KubernetesClient CreateClient(string? kubeconfigPath); +} +``` + +**Fallback порядок**: +1. Explicit kubeconfig path +2. Environment variable KUBECONFIG +3. In-cluster config (если внутри кластера) + +## Logging Architecture + +``` +InMemoryLoggerProvider + ↓ +InMemoryLogSink + ↓ +Console.WriteLine +``` + +**Конфиг**: +```json +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "ModelContextProtocol": "Debug" + } + } +} +``` + +--- + +*Файл описывает систему архитектуры, ключевые компоненты и потоки данных. Обновлять при введении новых архитектурных решений.* \ No newline at end of file diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md new file mode 100644 index 0000000..6c1b6c3 --- /dev/null +++ b/memory-bank/techContext.md @@ -0,0 +1,271 @@ +# Tech Context — Технологии и разработка + +## 🛠️ Используемые технологии + +### Основные технологии + +| Технология | Версия | Назначение | +|------------|--------|-------------| +| **C#** | .NET 10 | Язык программирования | +| **.NET SDK** | 10 | Runtime и SDK | +| **ASP.NET Core** | 9 | HTTP server, MCP transport | +| **Razor Pages** | 9+ | TUI компоненты (RazorConsole) | +| **Model Context Protocol** | 1.2.0 | MCP стандарт | +| **Kubernetes Client** | 13+ | .NET SDK для K8s | +| **RazorConsole** | Latest | TUI framework | + +### Файлы конфигурации + +**Global SDK pin**: +- `LazyBear.MCP/global.json` — пин версий .NET SDK + +**Main config**: +- `LazyBear.MCP/appsettings.json` — runtime конфиг (K8s, Jira, Confluence) +- `LazyBear.MCP/appsettings.Development.json` — development overrides + +**Launch settings**: +- `LazyBear.MCP/Properties/launchSettings.json` — (но trust Program.cs для портов) + +### External Dependencies + +**NuGet packages** (предположительно): +- `ModelContextProtocol` — MCP protocol +- `ModelContextProtocol.AspNetCore` — HTTP transport +- `KubernetesClient` — K8s .NET client +- `RazorConsole` — TUI framework +- `Swashbuckle.AspNetCore` — Swagger UI + +## 🖥️ Development Setup + +### Требования + +```bash +# .NET SDK 10 +dotnet --version # должно быть >= 10 + +# Kubectl (для K8s) +kubectl version --client + +# Docker Desktop (опционально) +docker --version +``` + +### Установка + +```bash +# Clone repo +git clone https://git.shahovalov.ru/mikhail/LazyBearWorks.git +cd LazyBearWorks + +# Build +dotnet build + +# Run +dotnet run --project LazyBear.MCP +``` + +### Запуск + +**Terminal запуска**: +```bash +# Консольный режим (TUI) +dotnet run --project LazyBear.MCP + +# С MCP Inspector +npx @modelcontextprotocol/inspector dotnet run --project LazyBear.MCP + +# С Swagger +# Включить в Program.cs: AddSwaggerGen() +dotnet run --project LazyBear.MCP +``` + +**Runtime URL**: `http://localhost:5000` + +**Примечание**: `Properties/launchSettings.json` показывает другой порт — trust Program.cs. + +## 📦 Проектная структура + +``` +LazyBear.MCP/ +├── Program.cs # Entry point, DI setup +├── appsettings.json # Config (K8s, Jira, Confluence) +├── global.json # SDK pin +├── Properties/ +│ └── launchSettings.json # (override: trust Program.cs) +├── Pages/ # Razor Pages UI (не активирован) +│ ├── Index.cshtml +│ └── Shared/ +├── Services/ +│ ├── Jira/ +│ │ ├── JiraIssueTools.cs +│ │ └── JiraClientProvider.cs +│ ├── Confluence/ +│ │ └── ConfluencePagesTools.cs +│ └── Kubernetes/ +│ ├── K8sConfigTools.cs +│ ├── K8sDeploymentTools.cs +│ ├── K8sNetworkTools.cs +│ ├── K8sPodsTools.cs +│ ├── K8sClientFactory.cs +│ └── K8sClientProvider.cs +├── TUI/ +│ ├── Components/ +│ │ ├── App.razor +│ │ └── GlobalKeyboardService.cs +│ └── Localization/ +└── wwwroot/ # Static files +``` + +## 🔧 Tool Registration + +**Auto-registration в Program.cs**: +```csharp +AddMcpServer() + .WithHttpTransport() + .WithToolsFromAssembly(); +``` + +**Ручная регистрация в DI**: +```csharp +services.AddSingleton(); +services.AddSingleton(); +services.AddSingleton(); +``` + +**Post-registration в Program.cs**: +```csharp +var registry = host.Services.GetRequiredService(); +foreach (var module in host.Services.GetServices()) +{ + registry.RegisterModule(module); +} +``` + +## 📝 Кодовые стандарты + +### Языковые предпочтения + +- **Код, переменные, типы**: Английский язык +- **Комментарии, строки, UI**: Русский язык +- **Публичные API/классы**: Английский +- **Внутренние компоненты**: Русский + +### Пример кода + +```csharp +// ✅ Хорошо +public class K8sDeploymentTools // Англ. класс +{ + /// + /// Создать новый деплой в Kubernetes кластере. + /// + public async Task CreateDeploymentAsync( + IToolContext context, + CreateDeploymentRequest request) + { + // Русский комментарии в коде + } +} + +// ❌ Плохо +public class K8sDeploymentTools +{ + public async Task ExecuteAsync(...) + { + return Task.FromResult(new object()); // Нет документации + } +} +``` + +## 🧪 Тестирование + +**Инструменты**: +- MCP Inspector: `npx @modelcontextprotocol/inspector dotnet run --project LazyBear.MCP` +- CLI тестирование: `echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | dotnet run` + +**Тест-проекты**: Нет по умолчанию (если нужны — создать) + +### Пример CLI тестирования + +```bash +# Прямое тестирование через stdin +echo '{"jsonrpc":"2.0","id":1,"method":"k8sPodsTools/getPodStatus","params":{"name":"nginx"},"id":1}' | dotnet run --project LazyBear.MCP +``` + +## 📚 Документация + +**Встроенная**: +- `LazyBear.MCP/README.md` — (если существует) +- Swagger UI: `/swagger` + +**External docs**: +- MCP спецификация: https://modelcontextprotocol.io +- Kubernetes client docs: https://kubernetes-client.net +- RazorConsole docs: `docs/razorconsole/` + +**Project docs**: +- `memory-bank/` — Memory Bank для контекста между сессиями +- `AGENTS.md` — инструкции для AI ассистентов +- `docs/tui_log.md` — TUI session notes +- `docs/opencode/question-policy.md` — OpenCode политика + +## 🐛 Известные gotchas + +### Config Gotchas + +- `Jira:Url` обязателен, иначе инициализация провайдера может упасть +- `Kubernetes:KubeconfigPath` может быть пустым — используется fallback + +### RazorConsole Gotchas + +- TUI владеет консолью, не писать напрямую в Console.Out +- `AutoClearConsole = true` — консоль очищается после каждого рендера +- `EnableTerminalResizing = true` — поддерживает перерисовку при изменении размера + +### TUI Session Notes + +- Сессия начинается с `Initialize` потока +- Затем TUI рендерится и запускает мониторинг +- MCP tools доступны параллельно через HTTP + +### Localization Gotchas + +- Переключение языков клавишей L +- Тексты берутся из `LocalizationService` +- TUI компоненты поддерживают оба языка + +## 🚀 Deployment + +**Docker**: +```bash +docker build -t lazybear-mcp . +docker run -p 5000:5000 \ + -v $HOME/.kube:/root/.kube:ro \ + lazybear-mcp +``` + +**Kubernetes**: +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: lazybear-mcp +spec: + containers: + - name: mcp + image: lazybear-mcp:latest + ports: + - containerPort: 5000 + volumeMounts: + - name: kubeconfig + mountPath: /root/.kube + readOnly: true +volumeMounts: +- name: kubeconfig + configMap: + name: kubeconfig-config +``` + +--- + +*Файл описывает технологии, setup и важные примечания о разработке. Обновлять при введении новых технологий или зависимостей.* \ No newline at end of file