Skip to content

Latest commit

 

History

History
212 lines (164 loc) · 7.01 KB

CONTRIBUTING.md

File metadata and controls

212 lines (164 loc) · 7.01 KB

Руководство по участию в разработке

Спасибо за интерес к Telegram-MCP! Этот документ описывает процесс внесения изменений в проект.

Быстрый старт для разработчиков

1. Форк и клонирование

git clone https://github.com/plagness/Telegram-MCP.git
cd Telegram-MCP

2. Настройка окружения

# Создать .env из примера
cp .env.example .env

# Установить TELEGRAM_BOT_TOKEN в .env
# Получить токен можно у @BotFather в Telegram

3. Запуск в dev-режиме

docker compose -f compose.yml up -d --build

4. Проверка

curl http://127.0.0.1:8081/health
curl http://127.0.0.1:3335/health

Структура проекта

Telegram-MCP/
├── api/                    # FastAPI-сервис (Python)
│   └── app/
│       ├── routers/        # HTTP эндпоинты
│       ├── services/       # Бизнес-логика
│       └── models.py       # Pydantic-модели
├── mcp/                    # MCP-сервер (Node.js/TypeScript)
│   └── src/index.ts        # MCP инструменты
├── sdk/                    # Python SDK для клиентов
├── db/init/                # SQL миграции
├── scripts/                # Тестовые скрипты
└── docs/                   # Документация

Процесс разработки

Создание фичи

  1. Создать ветку:

    git checkout -b feature/название-фичи

  2. Внести изменения:

    • Если добавляете эндпоинт: создать/обновить роутер в api/app/routers/
    • Если добавляете бизнес-логику: создать/обновить сервис в api/app/services/
    • Если изменяете БД: создать миграцию в db/init/
    • Если добавляете MCP-инструмент: обновить mcp/src/index.ts
    • Если расширяете SDK: обновить sdk/telegram_api_client/client.py

  3. Соблюдать стиль кода:

    • Python: имена переменных/функций на английском, docstrings/комментарии на русском
    • TypeScript: имена на английском, описания инструментов на русском
    • Документация: на русском языке

  4. Тестирование:

    # Создать тестовый скрипт в scripts/
export TEST_CHAT_ID=-100ваш_chat_id
python scripts/test_название.py --chat-id $TEST_CHAT_ID

  5. Обновить документацию:

    • Добавить описание в docs/api.md (для HTTP API)
    • Добавить описание в docs/sdk.md (для SDK)
    • Добавить описание в docs/mcp.md (для MCP)
    • Обновить README.md если добавлена крупная фича

  6. Коммит:

    git add .
git commit -m "feat: описание изменения"

Соглашения по коммитам

Используем Conventional Commits:

  • feat: — новая функциональность
  • fix: — исправление бага
  • docs: — изменения в документации
  • refactor: — рефакторинг кода
  • test: — добавление тестов
  • chore: — обновление зависимостей, CI/CD

Примеры:

feat: добавить поддержку опросов (sendPoll)
fix: исправить обработку ошибок в telegram_client
docs: обновить примеры в README
refactor: вынести роутеры в отдельные файлы

Pull Request

  1. Пуш в fork:

    git push origin feature/название-фичи

  2. Создать PR на GitHub с описанием:

    • Что добавлено/исправлено
    • Какие эндпоинты/методы затронуты
    • Примеры использования

  3. Проверка:

    • CI/CD должен пройти успешно
    • Код ревью от мейнтейнеров
    • Все комментарии должны быть закрыты

Правила кодирования

Python (FastAPI, SDK)

# ✅ Хорошо
async def send_message(
    chat_id: int | str,
    text: str,
    parse_mode: str | None = None,
) -> dict[str, Any]:
    """
    Отправить текстовое сообщение в чат.

    Args:
        chat_id: ID чата
        text: Текст сообщения
        parse_mode: Режим парсинга (HTML, MarkdownV2)

    Returns:
        dict: Информация об отправленном сообщении
    """
    ...

# ❌ Плохо (нет docstring, непонятные имена)
async def sm(c, t, pm=None):
    ...

TypeScript (MCP)

// ✅ Хорошо
addTool({
  name: "messages.send",
  description: "Отправить текстовое сообщение в чат Telegram",
  parameters: z.object({
    chat_id: z.union([z.number(), z.string()]).describe("ID чата"),
    text: z.string().describe("Текст сообщения"),
  }),
});

// ❌ Плохо (описание на английском для русскоязычного проекта)
addTool({
  name: "messages.send",
  description: "Send text message to chat",
  ...
});

SQL (Миграции)

-- ✅ Хорошо: имена таблиц/колонок на английском, комментарии на русском
CREATE TABLE polls (
    id SERIAL PRIMARY KEY,
    poll_id TEXT UNIQUE NOT NULL,  -- Telegram poll_id
    question TEXT NOT NULL,         -- Вопрос опроса
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Индексы для часто используемых запросов
CREATE INDEX idx_polls_chat_id ON polls(chat_id);

Версионирование

Проект использует формат версий: [год].[месяц].[версия]

  • 2025.02.1 — первый релиз февраля 2025
  • 2025.02.2 — второй релиз февраля 2025
  • 2025.03.1 — первый релиз марта 2025

При добавлении фичи обновите:

  1. VERSION — инкремент последней цифры
  2. CHANGELOG.md — описание изменений

Вопросы?

Спасибо за вклад! 🚀