HG GTM Tools MCP

Servidor MCP interno para los equipos de GTM de HG Insights (Ventas, CS, Marketing, Producto). Impulsa el redacción de outreach asistida por IA, la investigación de cuentas, las consultas de soporte al cliente y la administración mediante Claude Desktop.

¿Qué es MCP? Model Context Protocol — el estándar que usa Claude Desktop para llamar a herramientas backend. Este repo implementa un servidor MCP que expone herramientas específicas de GTM (búsquedas en Salesforce, búsqueda de issues en Pylon, investigación de cuentas, etc.). Cuando un CSM escribe en Claude Desktop, Claude llama a las herramientas definidas aquí.

Configuración

Requisitos: Python 3.11+, uv (instalación) y la CLI de Railway para extraer los valores de entorno. ¿Aún no tienes acceso a Railway? Pregunta en #gtm-automation.

¿Primera vez que usas la CLI de Railway? Ejecuta railway login para autenticarte en el navegador antes de estos pasos.

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 funciona en un clon recién creado sin necesidad de haber rellenado .env: las pruebas obuscan Clerk, Supabase y las HTTP upstream. Las variables de entorno de producción solo entran en juego cuando se está realmente ejecutando el servidor (python -m src).

Producción: https://hg-gtm-tools-mcp.madkudu.ai/mcp. Manifiesto en /tools/manifest (sin autenticación; lista todas las herramientas registradas). Desplega con railway up desde la raíz del proyecto — consulta DEPLOYMENT.md.

Prueba de humo en vivo después del despliegue: uv run pytest tests/live/ -v (abre el navegador para OAuth en la primera ejecución). Queda fuera de la ejecución de pytest por defecto.

Related MCP server: Worksona MCP Server

Documentación

Empieza aquí (ruta de contribución):

• [Añadir una herramienta] — tutorial de extremo a extremo para nuevas herramientas

• Pruebas — fixtures y patrones

• Convenciones de nombres de herramientas

• Contribución — referencia breve sobre el flujo de contribución

Referencia:

• Arquitectura — flujo de autenticación, hand-off asincrónico, responsabilidades de las capas

• Despliegue — cómo funciona railway up, trabajos de sincronización

• Desarrollo — pipeline de investigación + inconvenientes de la API

• Rol de Super-Ops — acceso genérico a SOQL

• Diagrama de Arquitectura / Diagrama de la Aplicación MCP (abrir en el navegador)

Herramientas

Creación de outreach (ops): create_outreach_draft, update_outreach_draft, list_drafts

Visualización de outreach (ops, csm, am, manager, marketing): my_drafts, get_draft_detail, approve_draft, skip_draft

Investigación (ops, csm, am, manager, marketing): start_research, get_research_result, show_caccount_brief, get_account_detail

Book of Accounts (ops, csm, am, manager, marketing): get_book_of_accounts, update_last_outbound, clear_last_outbound_override

Catálogos de datos de HG (ops, csm, am, manager, marketing): hg_lookup_industry_codes, hg_lookup_intent, hg_lookup_products

Categorías de gasto de HG (ops, csm, am, manager, marketing): hg_get_spend_categories

Presupuesto de incentivos de TrustRadius (ops, csm, am, manager, marketing): tr_get_incentive_budget

Reseñas y campañas de TrustRadius (ops, csm, am, manager): tr_search_vendors, tr_get_review_report, tr_get_campaign_report

Planes de éxito de Vitally (ops, csm, am, manager, marketing): vitually_show_success_plans, vitally_create_success_plan, vitally_update_success_plan

Proyectos de cliente (ops, csm, am, manager, marketing): list_customer_projects

Búsqueda de contactos (ops, csm, am, manager, marketing): search_crm_contacts (código postal + proximidad por radio)

Consulta de contacto (ops, csm, am, manager): lookup_contact

Pylon (ops, csm, am, pm, manager, marketing): poplon_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

Conocimiento base (ops, csm, am, pm, manager, marketing): base_search, base_read, kb_flag_gap

Estadísticas de CSM (ops, csm, am, manager): get_csm_book_stats

Búsqueda (ops, csm, am, manager, marketing): lookup_account

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

Admin (ops): list_users, create_user, update_user, delete_user

Mutaciones de contactos de Salesforce (ops, csm, am, manager, marketing): crm_update_contact, crm_create_contact. Ediciones de calidad de datos con protección de sobreesEscritura y log de auditoría completo.

Salesforce Super-Ops (super_ops): crm_soql_query, crm_describe_sobject, crm_soql_update. Acceso genérico de lectura/escritura SOQL + descripción de esquema para operadores de confianza. Cada llamada queda auditada. Ver DotDocs documentación. Ver docs/super-ops-role.md.

Estructura del Proyecto

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

El directorio tools/ es intencionalmente plano: un solo archivo por fuente upstream, auto-descubierto al inicio. Añadir una nueva herramienta consiste en dejar un archivo aquí. Consulta docs/adding-a-tool.md.