Skip to main content
Glama
keumbang/goldpopcon-openapi-mcp

keumbang/goldpopcon-openapi-mcp

@keumbang/goldpopcon-openapi-mcp

npm CI node license

MCP-сервер для кодинг-ассистента для Open API сервиса Goldpopcon (Geumbang). Подключается к MCP-клиентам, таким как Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor и другим, помогая точно писать код для интеграции с API торговли золотом и серебром.

Получение API-ключа

Ключи Open API (ключ доступа gpk_ + секретный ключ sk_) выдаются только в приложении Goldpopcon. Веб-пути для получения нет.

  1. Установите приложение Goldpopcon — App Store · Google Play

  2. Зарегистрируйтесь и получите ключи в меню Open API внутри приложения

  3. Секретный ключ sk_ отображается только на экране выдачи — сохраните его в надежном месте сразу же

Самое сложное место для разработчика в этом API — не названия полей, а подпись запроса: ввод query_hash различается в зависимости от метода (POST = raw body, GET = нормализованная querystring), и если скопировать пример из Upbit, все запросы будут возвращать 401. Этот MCP генерирует код для этой процедуры и выполняет локальное подписание/верификацию.

Related MCP server: korea-stock-mcp

Инструменты

Инструмент

Назначение

list_endpoints

Список эндпоинтов — включает область разрешений, идемпотентность, rate bucket

get_endpoint

Детали одного эндпоинта — схема параметров и тела, примеры запроса/успешного ответа, коды ответов

list_error_codes

Таблица кодов ошибок + рекомендации по повторным попыткам в зависимости от кода состояния + ловушки (недостаточно средств = 400 P0001, ошибка аутентификации = 401 error:null)

signing_guide

Процедура подписи JWT — ветвление query_hash, временные утверждения, nonce, идемпотентность

generate_signed_request

Генерация завершенного кода подписанного запроса на разных языках (python/javascript/go/curl)

sign_request

Локальное вычисление JWT с реальным ключом (отладка) — возвращает JWT, query_hash, готовый к использованию curl

verify_signature

Верификация уже созданного JWT в том же порядке, что и сервер — диагностика причины 401

call_api (opt-in)

Реальный вызов — только для чтения, production фиксирован. Регистрируется только при включении через env

Ресурсы: goldpopcon://openapi.yaml (полная спецификация), goldpopcon://overview (подпись, лимиты, описание ошибок).

Безопасность: secret_key, переданный в sign_request/verify_signature/call_api, используется только для локальной подписи, передается только результат подписи (JWT) — сам секрет не передается по сети.

call_api — вызов в реальном времени только для чтения

По умолчанию отключен. Регистрируется только при GOLDPOPCON_MCP_ALLOW_LIVE=true. Четырехуровневая защита, полностью блокирующая перемещение средств:

  1. Шлюз env — без переменной инструмент отсутствует

  2. Белый список — только getPrices / getBalances / getPriceHistory / getOrderPreview / getTradeHistory. buy·sell·payout·virtual-accounts недоступны для живого вызова (только генерация кода)

  3. Фиксация production — аргументом нельзя изменить сервер. Так как это только чтение, чтение production не приводит к движению средств

  4. Принудительный GET — блокировка методов записи

Для реального вызова эндпоинтов, связанных с перемещением средств, используйте generate_signed_request, чтобы получить код и выполнить его в своей среде разработчика.

Автоматизация чтения — ключ через env

Если LLM автоматически повторно запрашивает цены и балансы, опустите аргументы accessKey/secretKey и передайте их через env. sk_, переданный в аргументах, остается в открытом виде в контексте модели, транскрипте и логах клиента при каждом вызове.

{
  "mcpServers": {
    "goldpopcon-openapi": {
      "command": "npx",
      "args": ["-y", "@keumbang/goldpopcon-openapi-mcp"],
      "env": {
        "GOLDPOPCON_MCP_ALLOW_LIVE": "true",
        "GOLDPOPCON_ACCESS_KEY": "gpk_...",
        "GOLDPOPCON_SECRET_KEY": "sk_..."
      }
    }
  }
}

Резервный вариант через env доступен только для call_api (только чтение). sign_request не открыт, так как может создавать подписи вплоть до buyAsset — если бы он был открыт, агент мог бы создавать действительные подписи для перемещения средств без участия человека.

call_api также отвечает с помощью structuredContent — значения доступны напрямую, без парсинга Markdown.

{
  "operationId": "getPrices",
  "url": "https://api.goldpopcon.com/api/open/v1/prices",
  "status": 200,
  "ok": true,
  "data": { "...": "응답 본문 JSON 그대로" },
  "rateLimit": { "limit": 600, "remaining": 599, "reset": 1730000000, "retryAfter": null }
}
  • Формат data различается для каждого эндпоинта — пример успешного ответа из get_endpoint является спецификацией.

  • Ошибки 4xx/5xx также приходят не как ошибки инструмента, а в виде status/ok. Цикл обрабатывает их ветвлением.

  • Если тело ответа не в JSON (например, HTML-ошибка шлюза), оно приходит в raw вместо data.

  • При 429 в rateLimit.retryAfter указано время ожидания в секундах. Лимит: 600 запросов/мин для котировок, 60 запросов/мин для торговли.

Установка и сборка

git clone https://github.com/keumbang/goldpopcon-openapi-mcp.git
cd goldpopcon-openapi-mcp
npm install
npm run build       # dist/ 생성
npm test            # 서명 회귀 테스트

Регистрация в MCP-клиенте

Клиенты, подключаемые одной командой CLI:

# Claude Code
claude mcp add goldpopcon-openapi -- npx -y @keumbang/goldpopcon-openapi-mcp

# Codex CLI  (~/.codex/config.toml 에 기록된다. 세션에서 /mcp 로 연결 확인)
codex mcp add goldpopcon-openapi -- npx -y @keumbang/goldpopcon-openapi-mcp

Редактирование файла конфигурации вручную (Claude Desktop claude_desktop_config.json, Cursor ~/.cursor/mcp.json, Gemini CLI ~/.gemini/settings.json):

{ "mcpServers": { "goldpopcon-openapi": { "command": "npx", "args": ["-y", "@keumbang/goldpopcon-openapi-mcp"] } } }

Gemini CLI нестабильно интерпретирует PATH — если сервер не запускается, замените command на абсолютный путь, полученный с помощью which npx.

Запуск локального клона:

{
  "mcpServers": {
    "goldpopcon-openapi": {
      "command": "node",
      "args": ["/절대경로/goldpopcon-openapi-mcp/dist/index.js"]
    }
  }
}

Во время разработки используйте command: "npx", args: ["tsx", "/абсолютный_путь/.../src/index.ts"].

Переменные окружения

Переменная

По умолчанию

Значение

GOLDPOPCON_OPENAPI_SPEC

Встроенный spec/openapi.yaml

Переопределение пути к файлу спецификации

GOLDPOPCON_MCP_ALLOW_LIVE

(нет)

true активирует call_api (только чтение, production)

GOLDPOPCON_ACCESS_KEY

(нет)

Значение по умолчанию для ключа доступа call_api — используется при опущенном аргументе

GOLDPOPCON_SECRET_KEY

(нет)

Значение по умолчанию для секретного ключа call_api — рекомендуется для автоматизации повторяющихся вызовов

Примеры диалогов

  • "Дай код на Python для вызова sellAsset, золото 0.5g" → generate_signed_request(operationId=sellAsset, language=python, pathParams={asset:gold}, body={quantity:0.5})

  • "Как продать все имеющееся золото?" → generate_signed_request(operationId=sellAsset, language=python, pathParams={asset:gold}, body={quantity:0.001, sell_all:true}) — sell_all игнорирует указанное количество и исполняет весь доступный остаток

  • "Почему этот JWT выдает 401?" → verify_signature(token=..., secretKey=..., method=POST, rawBody=...)

  • "Какие параметры у эндпоинта истории цен?" → get_endpoint(operationId=getPriceHistory)

  • "Какой код ошибки при недостатке средств?" → list_error_codes — 400 P0001 (не 500). Также выводится таблица рекомендаций по повторным попыткам в зависимости от кода состояния

Синхронизация спецификации

Оригинал спецификации находится в docs/openapi.yaml репозитория бэкенда (вне этого репозитория), а этот репозиторий содержит копию spec/openapi.yaml в виде бандла. При изменении оригинала обновите копию, указав путь через SPEC_SRC:

SPEC_SRC=/path/to/<backend-repo>/docs/openapi.yaml npm run sync-spec

SPEC_SRC обязателен. Если его опустить, оригинал не будет найден, и операция завершится ошибкой — чтобы не указывать имя репозитория бэкенда в этом репозитории, значение по умолчанию не задано.

После обновления закоммитьте spec/openapi.yaml. Если правила подписи расходятся с сервером, npm test (зеркало правил верификации сервера) это обнаружит.

<backend-repo>/docs/openapi.yaml  ──sync-spec──▶  spec/openapi.yaml

Available Tools

7 tools
generate_signed_requestB

특정 엔드포인트를 호출하는 완결형 서명 코드를 생성한다(python/javascript/go/curl). query_hash 분기·멱등성 헤더를 메서드에 맞게 자동 반영.

Inputs: language (required), operationId (required), body, query, +3 more.

get_endpointA

단일 엔드포인트 상세 — 설명, 파라미터, 요청 본문 스키마와 예제, 응답 상태, 권한·멱등성.

Inputs: operationId (required).

list_endpointsA

금방 Open API 엔드포인트 목록. 각 항목의 권한 스코프·멱등성 필요 여부·rate limit 버킷을 함께 준다.

Inputs: openApiOnly.

list_error_codesA

금방 Open API 에러 코드 표와 함정(잔액 부족은 400 P0001, 인증 실패는 error=null 401, 503 fail-closed 등). 상태 코드별 재시도 판단표 포함.

Inputs: no named parameters.

signing_guideA

요청 서명(JWT + query_hash) 절차. 개발자가 가장 많이 막히는 지점 — 업비트 예제를 그대로 옮기면 전부 401 이 나는 이유 포함.

Inputs: no named parameters.

sign_requestB

실제 키로 요청 하나의 JWT 를 로컬 계산한다(디버깅용). secret_key 는 로컬에서만 쓰이고 어디로도 전송되지 않는다. 결과에 JWT·query_hash·바로 쓸 curl 을 준다.

Inputs: accessKey (required), secretKey (required), operationId (required), body, +4 more.

verify_signatureB

이미 만든 JWT 를 서버와 같은 순서로 로컬 검증해 401 원인을 짚는다. secret_key·전송할 본문/쿼리를 주면 query_hash 불일치까지 진단한다.

Inputs: token (required), method (required), secretKey (required), query, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: listing endpoints, getting details, error codes, signing guide, generating signed code, local signature computation, and signature verification. No overlap in functionality.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern (list_endpoints, get_endpoint, generate_signed_request, sign_request, verify_signature). The one deviation is 'signing_guide' which uses a gerund-noun form, but otherwise naming is uniform and predictable.

    Tool Count5/5

    With 7 tools, the server is well-scoped for its purpose: providing API endpoint discovery, error handling, and request signing utilities. Each tool earns its place without being too many or too few.

    Completeness5/5

    The tool set covers the full workflow for an OpenAPI helper: discover endpoints, understand errors, learn signing, generate signed code, debug signature issues. No obvious gaps for its intended domain.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides current and historical gold/precious metal prices (gold, silver, platinum, and palladium) via the GoldAPI.io service with support for multiple currencies.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables natural language control of Kiwoom Securities accounts through Claude Desktop. It provides tools for stock price lookup, buying and selling stocks, and analyzing portfolios or trade history via the Kiwoom REST API.
      11
      2
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Safe-by-default MCP server for the official Toss Securities Open API, providing read-only market and account data with optional order operations protected by multiple safety gates.
      27
      2
      MIT