Модуль Human MCP

Инструменты для управления жизненным циклом проектов и задач разметки на платформе Tagme через LLM-агента.

По умолчанию выключен. Включается флагом --enable-human-mcp при запуске или переменной окружения CROWD_SDK_MCP_HUMAN_TOOLS=1.

Флоу работы

Сценарий 1 — Проект по шаблону

get_human_mcp_markup_options          ← посмотреть доступные шаблоны, пулы, существующие проекты
        ↓
configure_human_mcp_project (create)  ← создать проект из шаблона с инструкцией и slug
        ↓
create_markup_task_with_items         ← загрузить items и создать задачу
        ↓
list_project_tasks                    ← проверить список задач
        ↓
update_markup_task / stop_markup_task ← управлять параметрами или остановить задачу

Сценарий 2 — Проект с генерацией интерфейса

generate_tagme_interface              ← сгенерировать интерфейс через tagme-x-genui (диалог)
        ↓
configure_human_mcp_project (create)  ← создать проект без шаблона
        ↓
apply_interface_to_project            ← применить сгенерированный интерфейс к проекту
        ↓
create_markup_task_with_items         ← загрузить items и создать задачу

Инспекция существующих проектов

summarize_projects_for_human_mcp ← просмотреть существующие проекты (инструкция, slug, пулы)

Инструменты

`get_human_mcp_markup_options`

Справочный каталог — возвращает доступные шаблоны, пулы и существующие human_mcp проекты. Вызывай перед созданием проекта, чтобы найти нужные template_id и pool_id.

{
    # "organization_id": "org123",          # авто-определяется, если не передан
    # "template_category_tags": ["text"],   # AND-фильтр по категориям шаблонов
    # "templates_catalog": "published",     # published | workspace
}

`configure_human_mcp_project`

Создать проект из шаблона (operation='create') или сменить шаблон на существующем проекте (operation='apply_template').

# Создать новый проект
{
    "operation": "create",
    "template_id": "tpl789",
    "name": "Мой проект разметки",
    "human_mcp_task_slug": "dialog_quality_v1",
    "instruction": "Оцените каждый диалог по критериям качества...",
    "pool_ids": ["pool001"],
}

# Сменить шаблон на существующем проекте
{
    "operation": "apply_template",
    "template_id": "tpl789",
    "project_id": "proj456",
}

`generate_tagme_interface`

Генерация интерфейса разметки через сервис tagme-x-genui. Многошаговый диалог: сервис может задать уточняющие вопросы перед генерацией.

# Шаг 1 — старт генерации
{
    "prompt": "Интерфейс для бинарной классификации текстов: тональность (позитив/негатив)",
    "genui_url": "http://localhost:8000",
}
# → status="needs_input":  вернёт questions[] и generation_id
# → status="completed":    вернёт interface{html, js, css, config, specification, example}

# Шаг 2 — ответить на вопросы (если needs_input)
{
    "prompt": "...",
    "genui_url": "http://localhost:8000",
    "generation_id": "<id из шага 1>",
    "answers": [{"question_id": "q1", "value": "Да"}],
}

`apply_interface_to_project`

Записывает сгенерированный интерфейс (html/js/css/config/specification/example) в метод проекта. Передай interface из результата generate_tagme_interface.

{
    "project_id": "proj456",
    "html": "<div>...</div>",
    "js": "...",
    "css": "...",
    "config": {...},
    "specification": {...},
    "example": {...},
}

`create_markup_task_with_items`

Создаёт задачу разметки внутри существующего проекта и загружает в неё items.

{
    "project_id": "proj456",
    "task_name": "Батч диалогов 2024-03",
    "items": [
        {"task": {"text": "Привет, как дела?", "id": "d001"}},
        {"task": {"text": "Какая погода сегодня?", "id": "d002"}},
    ],
    "price": 10.0,
    "overlap": 1,
    "start_after_upload": False,  # True только по явной просьбе пользователя
    # "deadline": "2024-04-01",
}

Каждый item должен иметь ключ "task". Внутренние поля должны соответствовать форме разметки целевого проекта. При необходимости разбей items на несколько вызовов (см. HUMAN_MCP_MAX_UPLOAD_ITEMS).

`list_project_tasks`

Получает список всех задач проекта с их ID, названиями и статусами. Используй перед update_markup_task или stop_markup_task для получения task_id.

{"project_id": "proj456"}

`update_markup_task`

Изменяет параметры существующей задачи. Хотя бы одно поле должно быть передано.

{
    "task_id": "task123",
    "price": 15.0,
    "overlap": 2,
    "deadline": "2026-07-01",
    # "name": "Новое название",
    # "description": "Новое описание",
}

`stop_markup_task`

Останавливает активную задачу. Инструмент ожидает полной остановки перед возвратом.

{"task_id": "task123"}

`summarize_projects_for_human_mcp`

Получает текст инструкции, slug, template_id и pool_ids для существующих human_mcp проектов. Удобно для подбора подходящего проекта под новый тип задачи.

{
    "project_ids": ["proj456", "proj789"],  # опционально — без параметра авто-обнаружение
}

Идентификация проекта: slug

Каждый human_mcp проект хранит slug в поле inner_comment в формате human_mcp_task:<slug>. Slug идентифицирует тип задачи разметки и используется для поиска проекта между сессиями.

Подсказки разметчику (hints YAML)

Передай путь через переменную окружения CROWD_MCP_HUMAN_LABELING_HINTS или параметр hints_path в get_human_mcp_markup_options. Это позволяет агенту выбирать шаблоны, задавать дефолты цены/перекрытия и понимать типы задач.

Шаблон файла: examples/30.mcp/human_mcp_labeling_hints.example.yaml.

Demo

Полный пример работы с кодом и детальным разбором инструментов представлен в интерактивной странице документации Human MCP Demo.