HG GTM Tools MCP

HG Insights GTM 팀(영업, CS, 마케팅, 프로덕트)을 위한 내부 MCP 서버입니다. Claude Desktop에서 AI 기반 아웃리치 초안 작성, 계정 리서치, 고객 지원 조회, 관리자 기능을 제공합니다.

MCP란? Model Context Protocol — Claude Desktop이 백엔드 도구를 호출할 때 사용하는 표준입니다. 이 저장소는 GTM 전용 도구(Salesforce 조회, Pylon 이슈 검색, 계정 리서치 등)를 노출하는 MCP 서버를 구현합니다. CSM이 Claude Desktop에서 입력하면, Claude는 여기에 정의된 도구를 호출합니다.

설정

전제 조건: Python 3.11+, uv (설치), 그리고 env 값을 가져오기 위한 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 응답을 스텁(stub)으로 처리합니다. 프로덕션 환경 변수는 실제로 서버를 실행(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

Docs

여기서 시작하세요 (기여자 경로):

• 도구 추가 — 새 도구에 대한 초종합 처음부터 끝까지 워크스루

• 테스팅 — 픽스처 및 패턴

• 도구 명명 규칙

• 기여하기 — 기여자 플로우에 대한 간단한 참고 자료

참고:

• 아키텍처 — 인증 플로우, 비동기 핸드오프, 레이어별 매들어

• 배포 — railway up이 어떻게 동작하는지, 동기화 작업

• 개발 — 리서치 파이프라인 + API 다양한 응용

• Super-Ops 역할 — 일반적인 SOQL 액세스

• 아키텍처 다이어그램 / MCP 앱 다이어그램 (브라우저에서 열기)

도구

아웃리치 생성 (ops): 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

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

HG Data Catalogs (ops, csm, am, manager, marketing): hg_lookup_industry_codes, hg_lookup_intent, hg_lookup_products

HG Spend Categories (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 Success Plans (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 Contact 수정 (ops, csm, am, manager, marketing): crm_update_contact, crm_create_contact. 덮어쓰기 방지와 전체 감사 로그를 포함한 데이터 품질 편집 기능입니다.

슈퍼옵스 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를 참조하세요.