283 lines
8.6 KiB
Markdown
283 lines
8.6 KiB
Markdown
# 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
|
||
|
||
### Требования
|
||
|
||
```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
|
||
│ ├── 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**:
|
||
```csharp
|
||
AddMcpServer()
|
||
.WithHttpTransport()
|
||
.WithToolsFromAssembly();
|
||
```
|
||
|
||
**Ручная регистрация в DI**:
|
||
```csharp
|
||
services.AddSingleton<IToolModule, JiraToolModule>();
|
||
services.AddSingleton<IToolModule, KubernetesToolModule>();
|
||
services.AddSingleton<IToolModule, ConfluenceToolModule>();
|
||
```
|
||
|
||
**Post-registration в Program.cs**:
|
||
```csharp
|
||
var registry = host.Services.GetRequiredService<ToolRegistryService>();
|
||
foreach (var module in host.Services.GetServices<IToolModule>())
|
||
{
|
||
registry.RegisterModule(module);
|
||
}
|
||
```
|
||
|
||
## 📝 Кодовые стандарты
|
||
|
||
### Языковые предпочтения
|
||
|
||
- **Код, переменные, типы**: Английский язык
|
||
- **Комментарии, строки, UI**: Русский язык
|
||
- **Публичные API/классы**: Английский
|
||
- **Внутренние компоненты**: Русский
|
||
|
||
### Пример кода
|
||
|
||
```csharp
|
||
// ✅ Хорошо
|
||
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 тестирования
|
||
|
||
```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
|
||
- `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**:
|
||
```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 и важные примечания о разработке. Обновлять при введении новых технологий или зависимостей.* |