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

keumbang/goldpopcon-openapi-mcp

@keumbang/goldpopcon-openapi-mcp

npm CI node license

Servidor MCP de asistente de codificación para la API abierta de Goldpopcon (Keumbang). Se conecta a clientes MCP como Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor, etc., para ayudar a escribir código preciso para la integración con la API de comercio de oro y plata.

Emisión de clave API

La clave de API abierta (clave de acceso gpk_ + clave secreta sk_) se emite solo en la aplicación Goldpopcon. No hay una ruta de emisión web.

  1. Instala la aplicación Goldpopcon — App Store · Google Play

  2. Regístrate y emite la clave en el menú de API abierta dentro de la aplicación

  3. La clave secreta sk_ solo se muestra en la pantalla de emisión — guárdala en un lugar seguro en ese momento

El punto donde los desarrolladores se atascan en esta API no es el nombre del campo, sino la firma de la solicitud — la entrada query_hash varía según el método (POST=cuerpo sin procesar, GET=querystring normalizada) y copiar el ejemplo de Upbit directamente da como resultado un 401. Este MCP genera el código para ese procedimiento y realiza la firma/verificación localmente.

Related MCP server: korea-stock-mcp

Herramientas

Herramienta

Propósito

list_endpoints

Lista de endpoints — incluye alcance de permisos, idempotencia, bucket de tasa

get_endpoint

Detalle de un solo endpoint — parámetros, esquema del cuerpo, ejemplos de solicitud/respuesta exitosa, códigos de respuesta

list_error_codes

Tabla de códigos de error + juicio de reintento por código de estado + trampas (saldo insuficiente=400 P0001, fallo de autenticación=401 error:null)

signing_guide

Procedimiento de firma JWT — bifurcación de query_hash, reclamo de tiempo, nonce, idempotencia

generate_signed_request

Generación de código de solicitud firmada completa por lenguaje (python/javascript/go/curl)

sign_request

Cálculo local de JWT con clave real (depuración) — devuelve JWT, query_hash, curl listo para usar

verify_signature

Verificación de un JWT ya creado en el mismo orden que el servidor — diagnóstico de causa de 401

call_api (opt-in)

Llamada real — solo consulta, fijo en producción. Se registra solo cuando se activa con env

Recursos: goldpopcon://openapi.yaml (especificación completa), goldpopcon://overview (prosa sobre firma, límites, errores).

Seguridad: La secret_key pasada a sign_request/verify_signature/call_api se usa solo para la firma local y solo se transmite el resultado de la firma (JWT) — el secreto en sí no viaja por la red.

call_api — Llamada en vivo solo de consulta

Desactivada por defecto. Solo se registra cuando GOLDPOPCON_MCP_ALLOW_LIVE=true. Cuádruple protección para bloquear por completo las transferencias de fondos:

  1. Puerta env — sin la variable, la herramienta no existe

  2. Lista blanca — solo getPrices / getBalances / getPriceHistory / getOrderPreview / getTradeHistory. buy·sell·payout·virtual-accounts no están disponibles en vivo (solo generación de código)

  3. Fijo en producción — no se puede cambiar el servidor con argumentos. Como es solo de consulta, leer producción no mueve fondos

  4. Forzar GET — bloquea métodos de escritura

Para llamar realmente a los endpoints de transferencia de fondos, recibe el código con generate_signed_request y ejecútalo en tu propio entorno de desarrollo.

Automatización de lectura — clave por env

Si el LLM automatiza la consulta repetitiva de precios/saldos, omite los argumentos accessKey/secretKey y proporciónalos por env. La sk_ pasada como argumento queda en texto plano en el contexto del modelo, la transcripción y los registros del cliente en cada llamada.

{
  "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_..."
      }
    }
  }
}

El fallback de env solo existe para call_api (solo consulta). sign_request no se ha abierto porque puede crear firmas hasta para buyAsset — si se abriera, un agente podría generar firmas de transferencia de fondos válidas sin intervención humana.

call_api también responde con structuredContent — para usar los valores directamente sin analizar 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 }
}
  • La forma de data varía según el endpoint — el ejemplo de respuesta exitosa de get_endpoint es la especificación.

  • Los errores 4xx/5xx también llegan como status/ok, no como error de herramienta. El bucle los maneja por separado.

  • El cuerpo que no es JSON (errores HTML de puerta de enlace, etc.) llega como raw en lugar de data.

  • Si es 429, rateLimit.retryAfter contiene los segundos de espera. Límite: 600 consultas/minuto, 60 operaciones/minuto.

Instalación · Compilación

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

Registro del cliente MCP

Clientes que se conectan con una sola línea de 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

Edición directa del archivo de configuración (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"] } } }

La resolución de PATH en Gemini CLI es inestable — si el servidor no arranca, cambia command por la ruta absoluta obtenida con which npx.

Ejecución con clon local:

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

Durante el desarrollo, usa command: "npx", args: ["tsx", "/ruta/absoluta/.../src/index.ts"].

Variables de entorno

Variable

Por defecto

Significado

GOLDPOPCON_OPENAPI_SPEC

spec/openapi.yaml empaquetado

Redirigir la ruta del archivo de especificación

GOLDPOPCON_MCP_ALLOW_LIVE

(ninguno)

Si es true, activa call_api (solo consulta, producción)

GOLDPOPCON_ACCESS_KEY

(ninguno)

Valor por defecto de la clave de acceso para call_api — se usa si se omite el argumento

GOLDPOPCON_SECRET_KEY

(ninguno)

Valor por defecto de la clave secreta para call_api — recomendado para automatización de llamadas repetitivas

  • "Dame el código para llamar a sellAsset en Python, 0.5g de oro" → generate_signed_request(operationId=sellAsset, language=python, pathParams={asset:gold}, body={quantity:0.5})

  • "¿Cómo vender todo el oro que tengo?" → generate_signed_request(operationId=sellAsset, language=python, pathParams={asset:gold}, body={quantity:0.001, sell_all:true}) — sell_all ignora la cantidad solicitada y ejecuta la totalidad del saldo disponible

  • "¿Por qué este JWT da 401?" → verify_signature(token=..., secretKey=..., method=POST, rawBody=...)

  • "¿Qué parámetros tiene el endpoint de historial de precios?" → get_endpoint(operationId=getPriceHistory)

  • "Si es saldo insuficiente, ¿qué número de error es?" → list_error_codes — 400 P0001 (no 500). También muestra la tabla de decisión de reintento por código de estado

Sincronización de la especificación

La fuente original de la especificación es docs/openapi.yaml en el repositorio del backend (fuera de este repo), y este repo incluye una copia en spec/openapi.yaml. Si la fuente cambia, actualízala especificando la ruta con SPEC_SRC:

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

SPEC_SRC es obligatorio. Si se omite, no encontrará la fuente y fallará — no se ha establecido una ruta por defecto para no dejar el nombre del repositorio del backend en este repo.

Después de la actualización, confirma spec/openapi.yaml. Si las reglas de firma se desvían del servidor, npm test (que refleja las reglas de verificación del servidor) lo detectará.

<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