# 🔄 Руководство по миграции: Конфигурация через переменные окружения

## 📝 Обзор изменений

MCP сервер Finam был рефакторен для использования переменных окружения вместо параметров функций для передачи `api_token` и `account_id`.

## ✅ Что изменилось

### До рефакторинга

```python
# Каждая функция требовала api_token и account_id
await get_account(api_token="...", account_id="...")
await trades(api_token="...", account_id="...", start_time="...", end_time="...")
await assets(api_token="...")
```

### После рефакторинга

```python
# Функции используют конфигурацию из переменных окружения
await get_account()
await trades(start_time="...", end_time="...")
await assets()
```

## 🔧 Настройка конфигурации

### Вариант 1: Через MCP конфигурацию (рекомендуется)

Добавьте в `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "finam": {
      "command": "uvx",
      "args": ["git+ssh://git@github.com/mdmeldon/finam-mcp.git"],
      "env": {
        "FINAM_API_TOKEN": "ваш_api_токен",
        "FINAM_ACCOUNT_ID": "ваш_account_id"
      },
      "description": "MCP server for Finam API"
    }
  }
}
```

### Вариант 2: Через .env файл (для локальной разработки)

Создайте файл `.env` в корне проекта:

```env
FINAM_API_TOKEN=ваш_api_токен
FINAM_ACCOUNT_ID=ваш_account_id
```

### Вариант 3: Через переменные окружения напрямую

```bash
export FINAM_API_TOKEN="ваш_api_токен"
export FINAM_ACCOUNT_ID="ваш_account_id"
uv run finam_mcp
```

## 📦 Измененные файлы

### Новые файлы

- `src/finam_mcp/configs/server.py` - добавлен класс `FinamConfig`

### Измененные файлы

1. **`src/finam_mcp/configs/__init__.py`**

   - Добавлен `FINAM: FinamConfig` в класс `Config`

2. **`src/finam_mcp/presentation/mcp/handlers/client.py`**

   - Добавлены функции `init_config()` и `_get_config()`
   - Удалены параметры `api_token` и `account_id` из всех 18 функций
   - `_build_client()` теперь использует конфигурацию из окружения

3. **`src/finam_mcp/presentation/mcp/handlers/__init__.py`**

   - `init_tools()` теперь принимает `FinamConfig` и инициализирует handlers

4. **`src/finam_mcp/presentation/mcp/main.py`**

   - `create_mcp_app()` передает `cfg.FINAM` в `init_tools()`

5. **`README.md`**
   - Обновлены инструкции по установке и конфигурации

## 🔍 Архитектурные улучшения

### Преимущества новой архитектуры

1. **🔐 Безопасность**: Credentials хранятся в переменных окружения, а не передаются как параметры
2. **🎯 Упрощение API**: Функции имеют меньше параметров и более чистые сигнатуры
3. **♻️ DRY принцип**: Конфигурация инициализируется один раз, используется везде
4. **🔧 Гибкость**: Легко переключаться между разными аккаунтами через env
5. **📦 Совместимость**: Следует стандартной практике MCP серверов (как в GitHub MCP)

### Паттерны проектирования

- **Singleton Pattern**: Глобальная конфигурация инициализируется один раз
- **Dependency Injection**: Конфигурация передается через `init_tools()`
- **Factory Pattern**: `_build_client()` создает клиент с конфигурацией

## ✅ Тестирование

Все изменения протестированы:

1. ✅ Загрузка конфигурации из переменных окружения
2. ✅ Инициализация handlers с конфигурацией
3. ✅ Удаление параметров `api_token` и `account_id` из всех функций
4. ✅ Корректность работы с реальным API

## 🚀 Быстрая проверка

```bash
# Убедитесь что виртуальное окружение активно
source .venv/bin/activate

# Проверьте загрузку конфигурации
FINAM_API_TOKEN="test" FINAM_ACCOUNT_ID="test" python -c "
from finam_mcp.configs.server import FinamConfig
c = FinamConfig()
print(f'✅ Config loaded: {c.ACCOUNT_ID}')
"
```

## 📚 Дополнительная информация

- Все 18 инструментов обновлены и работают с новой конфигурацией
- API токен по-прежнему используется только для получения JWT (~15 минут)
- Автоматическое обновление JWT при истечении срока сохранено
- Обратная совместимость: старый код не поддерживается, требуется обновление конфигурации

## 🆘 Устранение неполадок

### Ошибка: "Field required" для FINAM_API_TOKEN или FINAM_ACCOUNT_ID

**Причина**: Переменные окружения не установлены

**Решение**:

1. Проверьте что переменные экспортированы: `echo $FINAM_API_TOKEN`
2. Убедитесь что `.env` файл существует и содержит правильные ключи
3. Перезапустите Cursor/IDE после изменения `mcp.json`

### Ошибка: "Конфигурация Finam не инициализирована"

**Причина**: `init_config()` не был вызван до использования инструментов

**Решение**: Это должно происходить автоматически при запуске. Если ошибка возникает, проверьте что `create_mcp_app()` вызывает `init_tools(mcp, cfg.FINAM)`

## 📧 Поддержка

Если возникли проблемы с миграцией, создайте Issue в репозитории проекта.

---

**Дата создания**: 2025-10-04  
**Версия**: 1.0.0
