@keumbang/goldpopcon-openapi-mcp

ゴールドポップコーン（金房）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

ツール

リソース: 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"]。

環境変数

対話例

• "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