LazyBearWorks/memory-bank/techContext.md

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
Qdrant.Client	Latest	Векторный поиск,知识库

Файлы конфигурации

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

Требования

# .NET SDK 10
dotnet --version  # должно быть >= 10

# Kubectl (для K8s)
kubectl version --client

# Docker Desktop (опционально)
docker --version

Установка

# Clone repo
git clone https://git.shahovalov.ru/mikhail/LazyBearWorks.git
cd LazyBearWorks

# Build
dotnet build

# Run
dotnet run --project LazyBear.MCP

Запуск

Terminal запуска:

# Консольный режим (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
│   ├── Qdrant/
│   │   ├── QdrantClientProvider.cs
│   │   ├── QdrantKnowledgeTools.cs
│   │   └── QdrantToolModule.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:

AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

Ручная регистрация в DI:

services.AddSingleton<IToolModule, JiraToolModule>();
services.AddSingleton<IToolModule, KubernetesToolModule>();
services.AddSingleton<IToolModule, ConfluenceToolModule>();

Post-registration в Program.cs:

var registry = host.Services.GetRequiredService<ToolRegistryService>();
foreach (var module in host.Services.GetServices<IToolModule>())
{
    registry.RegisterModule(module);
}

📝 Кодовые стандарты

Языковые предпочтения

• Код, переменные, типы: Английский язык
• Комментарии, строки, UI: Русский язык
• Публичные API/классы: Английский
• Внутренние компоненты: Русский

Пример кода

// ✅ Хорошо
public class K8sDeploymentTools  // Англ. класс
{
    /// <summary>
    /// Создать новый деплой в Kubernetes кластере.
    /// </summary>
    public async Task<CreateDeploymentResult> CreateDeploymentAsync(
        IToolContext context, 
        CreateDeploymentRequest request)
    {
        // Русский комментарии в коде
    }
}

// ❌ Плохо
public class K8sDeploymentTools
{
    public async Task<object> 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 тестирования

# Прямое тестирование через 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
• Qdrant:Url обязателен для векторного поиска, если используется
• Qdrant:ApiKey опционален, но рекомендуется для безопасного доступа

Qdrant Gotchas

• Косинусная метрика — default для векторного поиска
• Размер вектора должен быть фиксированным при создании коллекции

RazorConsole Gotchas

• TUI владеет консолью, не писать напрямую в Console.Out
• AutoClearConsole = true — консоль очищается после каждого рендера
• EnableTerminalResizing = true — поддерживает перерисовку при изменении размера

TUI Session Notes

• Сессия начинается с Initialize потока
• Затем TUI рендерится и запускает мониторинг
• MCP tools доступны параллельно через HTTP

Localization Gotchas

• Переключение языков клавишей L
• Тексты берутся из LocalizationService
• TUI компоненты поддерживают оба языка

🚀 Deployment

Docker:

docker build -t lazybear-mcp .
docker run -p 5000:5000 \
  -v $HOME/.kube:/root/.kube:ro \
  lazybear-mcp

Kubernetes:

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 и важные примечания о разработке. Обновлять при введении новых технологий или зависимостей.