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

keumbang/goldpopcon-openapi-mcp

@keumbang/goldpopcon-openapi-mcp

npm CI node license

ゴールドポップコーン(金房)Open API コーディングアシスタントMCPサーバー。Claude Code · Claude Desktop · Codex CLI · Gemini CLI · Cursor などのMCPクライアントに接続し、金・銀取引API連携コードを正確に作成できるように支援します。

APIキーの発行

Open APIキー(gpk_ アクセスキー + sk_ シークレットキー)は ゴールドポップコーンアプリでのみ発行 されます。Web発行の経路はありません。

  1. ゴールドポップコーンアプリをインストール — 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

エンドポイント一覧 — 権限スコープ・冪等性・レートバケットを含む

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(署名・制限・エラーに関する散文)。

セキュリティ: sign_request/verify_signature/call_api に渡した secret_key はローカル署名にのみ使用され、署名結果(JWT)だけが送信されます — secret自体はネットワークを経由しません。

call_api — 参照専用のライブ呼び出し

デフォルトでは 無効。GOLDPOPCON_MCP_ALLOW_LIVE=true の場合のみ登録されます。4重の安全策で資金移動を根本的にブロックします:

  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 でも応答します — マークダウンパースなしで値を直接利用できます。

{
  "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エラーなど)は data の代わりに raw で返ります。

  • 429 の場合は rateLimit.retryAfter に待機秒数。quote 600/分、trade 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 のシークレットキーデフォルト — 繰り返し呼び出しの自動化で推奨

対話例

  • "sellAsset をPythonで呼び出すコードをください、金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