# MCP・Skills・SDK

HTTP を直接呼ぶほかに、公式のオープンソース接続方法が 3 つあります。AI アシスタント向けの MCP サーバー、エージェント向けの Agent Skills、自分のコード向けの TypeScript / Python SDK です。いずれも環境変数 DATAFORGEO_API_KEY 1 つで動き、課金は API を直接呼ぶ場合と同じです。

| 方法 | 向いている用途 | インストール |
| --- | --- | --- |
| MCP サーバー | Claude や Cursor などの AI アシスタントにクエリ用ツールを追加 | `npx -y @dataforgeo/mcp` |
| Agent Skills | エージェントが診断・競合比較・引用分析・週次レポートをワークフローとして実行 | `/plugin install dataforgeo@dataforgeo` |
| SDK | 自分の TypeScript / Python コードに組み込む | `npm install @dataforgeo/client` |

### MCP サーバー

Claude Code・Claude Desktop・Cursor・Windsurf など MCP 対応の AI アシスタントに 6 つのツールを追加します。stdio 接続で npx から直接起動、Node.js 20 以上が必要です。各ツールの説明に課金ルールが書かれているため、アシスタントは呼び出し前に消費 credits を把握できます。

```bash
claude mcp add dataforgeo -e DATAFORGEO_API_KEY=$DATAFORGEO_API_KEY -- npx -y @dataforgeo/mcp
```

```json
{
  "mcpServers": {
    "dataforgeo": {
      "command": "npx",
      "args": [
        "-y",
        "@dataforgeo/mcp"
      ],
      "env": {
        "DATAFORGEO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

| tool | API | 説明 | 消費 |
| --- | --- | --- | --- |
| `geo_answer` | POST /v1/geo/answer | 1 つの prompt の複数エンジン回答（言及・引用・競合付き） | API と同じ |
| `geo_index` | POST /v1/geo/index | 同上＋GEO Index KPI（Pro 以上） | API と同じ |
| `geo_index_summary` | GET /v1/geo/index/summary | 実行済み結果の KPI・トレンド・分解 | 0 |
| `get_job` | GET /v1/jobs/{job_id} | 非同期ジョブを取得。wait_seconds で完了まで待機 | 0 |
| `get_account` | GET /v1/account | プラン・残高・今月の使用量 | 0 |
| `estimate_credits` | ローカル計算 | 1 回またはバッチの最大仮押さえ credits を API を呼ばずに見積もり | 0 |

| 環境変数 | 必須 | 説明 |
| --- | --- | --- |
| `DATAFORGEO_API_KEY` | はい | API キー。x-api-key ヘッダーとして送信 |
| `DATAFORGEO_BASE_URL` | いいえ | API のベース URL を上書き |
| `DATAFORGEO_MAX_CREDITS_PER_CALL` | いいえ | 1 回の geo_answer / geo_index が仮押さえできる上限。超えるとローカルで拒否し送信しません。自動エージェントに推奨 |

https://github.com/DataForGEO/mcp

### Agent Skills

Claude Code・Claude.ai、そして Agent Skills に対応した他のエージェント（Codex CLI・Cursor・Gemini CLI など）で使える GEO ワークフローです。credits を使う skill は残高確認と見積もりを行い、同意を得てから一括実行します。各 skill には依存ゼロの CLI dfgeo.py が付属し、Python 3.8+ だけで動きます。

```text
/plugin marketplace add DataForGEO/skills
/plugin install dataforgeo@dataforgeo
```

| skill | 説明 | credits 消費 |
| --- | --- | --- |
| `dataforgeo-api` | 基本：answer / index / summary の単発呼び出し、残高、credits 見積もり、非同期ジョブ | 呼び出しごと |
| `geo-prompt-set-builder` | 意図 × 層 × 言語で追跡する prompt セットを設計し、JSONL 出力とコスト見積もり | なし |
| `geo-visibility-audit` | ブランドの AI 可視性診断：prompt × エンジンを一括実行し、根拠と施策付きレポートを作成 | あり（見積もり後に同意を得てから） |
| `geo-competitor-benchmark` | 競合比較：シェア・オブ・ボイス、トップ推奨率、平均順位、prompt ごとの勝敗 | あり（同上） |
| `geo-citation-audit` | 引用元分析：AI が引用するサイト、自社ソースの引用率、コンテンツ・外部施策・PR のリスト | 既存結果を再利用し追加課金なし |
| `geo-index-report` | GEO Index の週次・月次レポートと固定 tag の週次追跡 | レポートは無料、追跡は呼び出しごと |

Claude.ai / Claude Desktop：リポジトリで python3 scripts/package.py を実行して zip を作り、設定 → 機能 → Skills からアップロードし、コード実行を有効にします。Skills と MCP は併用できます。

https://github.com/DataForGEO/skills

### SDK

TypeScript / JavaScript は @dataforgeo/client、Python は dataforgeo。

```bash
npm install @dataforgeo/client
pip install dataforgeo
```

```ts
import { DataForGEO } from "@dataforgeo/client";

const client = new DataForGEO(); // reads DATAFORGEO_API_KEY
const res = await client.geo.answer({
  prompt: "东京有哪些适合家庭入住的民宿？",
  engines: ["chatgpt"],
  brand: "晓宅",
  location: "JP",
  language: "zh-CN",
});
console.log(res.answers[0].brand?.mentioned, res._meta.creditsRemaining);
```

```python
from dataforgeo import DataForGEO

client = DataForGEO()  # reads DATAFORGEO_API_KEY
res = client.geo.answer(
    prompt="东京有哪些适合家庭入住的民宿？",
    engines=["chatgpt"],
    brand="晓宅",
    location="JP",
    language="zh-CN",
)
print(res["answers"][0]["brand"]["mentioned"], res.meta.credits_remaining)
```

- 2 つの SDK は 1 対 1 で対応し、全エンドポイント・エラーコード・使用量ヘッダー（x-credits-used など）・非同期ジョブ・webhook 署名検証をカバーします。
- リクエストパラメータとレスポンスフィールドは API と同じ（snake_case）で変換しません。
- 429・408・5xx は自動リトライ（エラーは無料）。ネットワークエラーは GET のみリトライし、二重課金を避けるため POST はリトライしません。

https://github.com/DataForGEO/client