HG GTM Tools MCP

Внутренний MCP-сервер для GTM-команд HG Insights (Sales, CS, Marketing, Product). Обеспечивает AI-ассистируемое создание черновиков аутрич-писем, исследование аккаунтов, поиск по обращениям в поддержку и администрирование через Claude Desktop.

Что такое MCP? Model Context Protocol — стандарт, с помощью которого Claude Desktop вызывает серверные инструменты. В этом репозитории реализован MCP-сервер, предоставляющий GTM-специфичные инструменты (поиск по Salesforce, поиск обращений в Pylon, исследование аккаунтов и т.д.). Когда CSM вводит запрос в Claude Desktop, Claude вызывает инструменты, описанные здесь.

Настройка

Предварительные требования: Python 3.11+, uv (установка) и Railway CLI для получения значений переменных окружения. Ещё нет доступа к Railway? Спросите в #gtm-automation.

Впервые пользуетесь Railway CLI? Выполните railway login, чтобы авторизоваться через браузер, перед шагами ниже.

uv sync                                                                        # install deps
railway link -p 283ad9d5-e8d7-48d9-b380-10f9e5fab860 -e production             # link to hg-gtm-tools / production
railway variable list --kv > .env                                              # pull env values into a local .env
uv run pytest                                                                  # confirm setup works (37 tests, ~2s, no network)
uv run python -m src                                                           # run the server on http://localhost:8000/mcp

uv run pytest работает на свежем клоне ещё до заполнения .env — тесты подменяют Clerk, Supabase и внешние HTTP-запросы заглушками. Переменные окружения для продакшена вступают в силу только при реальном запуске сервера (python -m src).

Продакшен: https://hg-gtm-tools-mcp.madkudu.ai/mcp. Манифест — по адресу /tools/manifest (без аутентификации; перечисляет все зарегистрированные инструменты). Деплой — командой railway up из корня проекта: см. DEPLOYMENT.md.

Смоук-тест живого сервера после деплоя: uv run pytest tests/live/ -v (при первом запуске открывается браузер для OAuth). Исключён из стандартного запуска pytest.

Related MCP server: Worksona MCP Server

Документация

Начните здесь (путь контрибьютора):

• Добавление инструмента — полное пошаговое руководство для новых инструментов

• Тестирование — фикстуры и паттерны

• Соглашения об именовании инструментов

• Контрибьюция — краткий справочник по процессу внесения вклада

Справочные материалы:

• Архитектура — поток аутентификации, асинхронная передача управления, зоны ответственности слоёв

• Деплой — как работает railway up, фоновые задачи

• Разработка — исследовательский пайплайн и скрытые особенности API

• Роль Super-Ops — универсальный доступ к SOQL

• Диаграмма архитектуры / Диаграмма MCP-приложения (открываются в браузере)

Инструменты

Создание аутрич-писем (ops, csm, am, manager, marketing): create_outreach_draft, update_outreach_draft, list_drafts

Просмотр аутрич-писем (ops, csm, am, manager, marketing): my_drafts, get_draft_detail, approve_draft, skip_draft

Исследования (ops, csm, am, manager, marketing): start_research, get_research_result, show_account_brief, get_account_detail

Книга аккаунтов (ops, csm, am, manager, marketing): get_amount_of_accounts, update_last_outbound, clear_last_outbound_override

Каталоги данных HG (ops, csm, am, manager, marketing): hg_lookup_industry_codes, hg_lookup_intent, hg_lookup_products

Категории расходов HG (ops, csm, am, manager, marketing): hg_get_spend_categories

Инцентивный бюджет TrustRadius (ops, csm, am, manager, marketing): tr_get_incentive_budget

Отзывы и кампании TrustRadius (ops, csm, am, manager): tr_search_vendors, tr_get_review_report, tr_get_campaign_report

Планы успеха Vitally (ops, csm, am, manager, marketing): vitally_show_success_plans, vitally_create_success_plan, vitally_update_success_plan

Клиентские проекты (ops, csm, am, manager, marketing): list_customer_projects

Поиск контактов (ops, csm, am, manager, marketing): search_crm_contacts (по ZIP-коду и радиусу)

Просмотр контакта (ops, csm, am, manager): lookup_contact

Pylon (ops, csm, am, pm, manager, marketing): pylon_search_accounts, pylon_search_issues, pylon_get_issue

Jira (ops, csm, am, pm, manager, marketing): jira_search_tickets, jira_get_ticket

Weflow (ops, csm, am, pm, manager, marketing): weflow_search_recordings, weflow_get_transcript

База знаний (ops, csm, am, pm, manager, marketing): kb_search, kb_read, kb_flag_gap

Статистика CSM (ops, csm, am, manager): get_csm_book_stats

Просмотр аккаунта (ops, csm, am, manager, marketing): lookup_account

Google Slides (ops, csm, am, manager, pm, marketing): google_slides

Администрирование (ops): list_users, create_user, update_user, delete_user

Изменение контактов в Salesforce (ops, csm, am, manager, marketing): crm_update_contact, crm_create_contact. Правки качества данных с защитой от перезаписи и полным журналом аудита.

Super-Ops Salesforce (super_ops): crm_soql_query, crm_describe_sobject, crm_soql_update. Универсальное чтение/запись SOQL и описание схем для доверенных операторов. Каждый вызов аудируется. См. docs/super-ops-role.md.

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

src/
├── server.py            # FastMCP server + Clerk OIDC auth
├── __main__.py          # Uvicorn entry point
├── auth.py              # Current user from JWT claims
├── roles.py             # Role-based tool filtering (VALID_ROLES)
├── usage.py             # @tracked audit-log decorator
├── manifest.py          # /tools.json manifest endpoint for the dashboard
├── db.py                # Supabase CRUD (sync + async variants)
├── storage.py           # Supabase-backed AsyncKeyValue for OAuth state
├── geo.py               # State/country normalization + zip radius
├── product_map.py       # ProductCode → category mapping
├── tools/               # MCP tool handlers (one file per source)
│   ├── _shared.py       # @tool decorator (the contributor entry point)
│   ├── _registry.py     # Auto-discovery: walks this dir at startup
│   └── *.py             # One file per source — see `ls src/tools/`
├── clients/             # Async upstream API clients (one per service)
├── apps/                # MCP app bundles (Vite + vite-plugin-singlefile)
├── research/            # Account research pipeline (orchestrator + agents)
├── kb/                  # Knowledge base sync + read endpoints
└── sync/                # Scheduled sync jobs

tests/
├── conftest.py          # mcp_client, fake_user, mock_audit_log, env stubs
├── fixtures/upstreams.py  # mock_jira, mock_pylon, mock_salesforce, etc.
└── test_*.py            # one file per tool module being tested

docs/
├── adding-a-tool.md     # end-to-end walkthrough for new contributors
├── testing.md           # fixture reference
└── *.md                 # design docs and references

Каталог tools/ намеренно плоский: один файл на каждый внешний источник, автоматически подхватывается при запуске. Добавить новый инструмент — значит просто положить файл сюда. См. docs/adding-a-tool.md.