bizgate-mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -1,161 +1,221 @@
 # bizgate-mcp-server
 
 BizGate API と Claude を接続する MCP サーバーです。
-会社名・法人番号で企業情報・部署・人事情報を検索し、Claude が自然言語で回答できるようにします。
+Claude に話しかけるだけで、企業の情報を調べられるようになります。
 
-## 仕組み
+```
+例：
+「株式会社エージェントの電話番号を教えて」
+「富士フイルムBIの営業部署を一覧で出して」
+「この会社の全情報を調べて、Excelに入れて」
+```
+
+### 仕組み
 
 ```
-[ユーザー] → [Claude] ←── MCP (stdio) ──→ [本サーバー] ──→ [BizGate API]
+[ユーザー] → [Claude] ←── MCP ──→ [本サーバー] ──→ [BizGate API]
 ```
 
-1. ユーザーが Claude に「○○の人事部の電話番号を教えて」と依頼
-2. Claude が MCP プロトコル経由で本サーバーのツールを呼び出す
-3. 本サーバーが BizGate API に問い合わせ → JSON レスポンスを解析
-4. 構造化された情報を Claude に返却
-5. Claude がユーザーに自然言語で回答（スプレッドシートへの入力も可能）
+---
 
-## 提供ツール
+## セットアップ（所要時間：約10分）
 
-| ツール名 | 説明 | API消費 |
-|---------|------|--------|
-| `bizgate__company_search` | 企業の基本情報（住所・電話・代表者・業種・資本金 等） | 1回（結果なしでも課金） |
-| `bizgate__department_search` | 部署情報（部署名・住所・電話番号）最大500件 | 1回（データなしは課金なし） |
-| `bizgate__marketing_tags` | マーケティングタグ（SNS・MA・サービス・活動） | 1回（データなしは課金なし） |
-| `bizgate__keyman_search` | 人事情報（部署・役職・発令日）最大500件 | 1回（データなしは課金なし） |
-| `bizgate__company_full` | 企業＋部署＋人事を一括取得 | 3回 |
-| `bizgate__usage_status` | 本日の残りAPI回数を確認 | 0回 |
+### 事前に必要なもの
 
-## セットアップ
+- **Claude Code** がパソコンにインストール済み
+- **Node.js 18 以上** がインストール済み
+- **BizGate のアカウント情報**（管理者から受け取ってください）
+  - ユーザー名
+  - パスワード
+  - サービスキー（企業用・部署用の2つ）
 
-### 前提条件
+---
 
-- Node.js 18 以上
-- Claude Code がインストール済み
-- BizGate API のアカウント（ユーザー名・パスワード・サービスキー）
+### ステップ 1：ターミナルを開く
 
-### 1. リポジトリをクローン＆ビルド
+Mac の場合：
+1. `Command + Space` で Spotlight を開く
+2. 「ターミナル」と入力して Enter
 
-```bash
-git clone https://github.com/digiman-hq/bizgate-mcp-server.git
-cd bizgate-mcp-server
-npm install
-npm run build
+---
+
+### ステップ 2：MCP サーバーを登録する
+
+ターミナルに以下を **そのままコピーして貼り付け** → Enter を押してください。
+
+```
+claude mcp add --scope user bizgate -- npx bizgate-mcp-server
+```
+
+以下のように表示されれば OK です。
+```
+Added stdio MCP server bizgate...
 ```
 
-### 2. Claude Code に MCP サーバーを登録
+---
 
-以下のコマンドを **1行ずつ** 実行してください。サービスキーの値は管理者から受け取ってください。
+### ステップ 3：設定ファイルを編集する
 
-```bash
-claude mcp add --scope user bizgate \
-  --transport stdio \
-  -- node /path/to/bizgate-mcp-server/dist/index.js
+ターミナルに以下を **そのままコピーして貼り付け** → Enter を押してください。
+
+```
+open ~/.claude.json
 ```
 
-> **注意**: 上記コマンドでは環境変数が設定されません。次のステップで手動設定が必要です。
+テキストエディタで設定ファイルが開きます。
+
+ファイルの中から `"bizgate"` というセクションを探してください。
+以下のように **書き換え** ます。
+
+#### 書き換え前
 
-### 3. 環境変数を設定
+```json
+"bizgate": {
+  "type": "stdio",
+  "command": "npx",
+  "args": ["bizgate-mcp-server"],
+  "env": {}
+}
+```
 
-`~/.claude.json` を開き、`mcpServers.bizgate` の `env` セクションに以下を設定します。
+#### 書き換え後
 
 ```json
-{
-  "mcpServers": {
-    "bizgate": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/path/to/bizgate-mcp-server/dist/index.js"],
-      "env": {
-        "BIZGATE_USERNAME": "あなたのユーザー名",
-        "BIZGATE_PASSWORD": "あなたのパスワード",
-        "BIZGATE_AUTH_MODE": "basic",
-        "BIZGATE_DAILY_LIMIT": "200",
-        "BIZGATE_SKEY_COMPANY": "企業APIのサービスキー",
-        "BIZGATE_SKEY_DEPARTMENT": "部署APIのサービスキー",
-        "BIZGATE_SKEY_MARKETING": "マーケAPIのサービスキー（任意）",
-        "BIZGATE_SKEY_KEYMAN": "キーマンAPIのサービスキー（任意）"
-      }
-    }
+"bizgate": {
+  "type": "stdio",
+  "command": "npx",
+  "args": ["bizgate-mcp-server"],
+  "env": {
+    "BIZGATE_USERNAME": "ここにユーザー名を入力",
+    "BIZGATE_PASSWORD": "ここにパスワードを入力",
+    "BIZGATE_AUTH_MODE": "basic",
+    "BIZGATE_DAILY_LIMIT": "200",
+    "BIZGATE_SKEY_COMPANY": "ここに企業APIキーを入力",
+    "BIZGATE_SKEY_DEPARTMENT": "ここに部署APIキーを入力"
   }
 }
 ```
 
-> `/path/to/` はクローンした実際のパスに置き換えてください。
+> **注意（よくあるミス）**
+> - `ここに〇〇を入力` の部分を、管理者から受け取った **実際の値** に置き換えてください
+> - ダブルクォーテーション `"` は **消さないで** ください
+> - カンマ `,` の位置を **変えないで** ください
+> - 最後の行（`"BIZGATE_SKEY_DEPARTMENT"` の行）の末尾には **カンマをつけないで** ください
+> - 編集後、`Command + S` で保存 → ファイルを閉じる
 
-### 4. Claude Code を再起動して確認
+---
 
-```bash
+### ステップ 4：Claude Code を再起動する
+
+もし Claude Code が開いている場合は、一度閉じてください。
+
+ターミナルで以下を実行してください。
+
+```
 claude
 ```
 
-起動後、`/mcp` コマンドで `bizgate` が **connected** になっていれば成功です。
+---
 
-## 使い方
-
-Claude Code で自然言語で聞くだけです。
+### ステップ 5：接続を確認する
 
-### 基本的な使い方
+Claude Code が起動したら、以下を入力してください。
 
 ```
-エージェントの企業情報を教えて
+/mcp
+```
 
-富士フイルムBIの営業部署を調べて
+一覧が表示されます。 `bizgate` の横に **✔ connected** と表示されていれば成功です。
 
-GMOインターネットのマーケティングタグを教えて
-```
+うまくいかない場合は、このページの一番下の「うまくいかないとき」を確認してください。
 
-### 部署の絞り込み
+---
 
-```
-富士フイルムBIの東京都にある人事部を調べて
+## 使い方
 
-トヨタ自動車の経理と総務の部署情報を教えて
-```
+設定完了後は、Claude に **日本語で話しかけるだけ** です。特別なコマンドは不要です。
 
-### 一括取得
+### よく使うパターン
 
-```
-株式会社エージェントの全情報を調べて
-（→ 企業情報・部署・人事情報をまとめて取得）
-```
+| やりたいこと | Claude への聞き方 |
+|------------|-----------------|
+| 会社の基本情報を知りたい | 「株式会社○○の企業情報を教えて」 |
+| 電話番号を知りたい | 「○○の電話番号は？」 |
+| 部署の一覧を見たい | 「○○の部署一覧を出して」 |
+| 特定の部署を探したい | 「○○の人事部の連絡先を教えて」 |
+| 全情報をまとめて見たい | 「○○の全情報を調べて」 |
+| Excelに入力したい | 「○○の情報を調べてExcelに入れて」 |
 
-### スプレッドシートとの連携
+### 注意点
 
-```
-エージェントの企業情報を調べて、Excelに入力して
+- **会社名は正確に** 入力してください（例：「ソフバン」→ 「ソフトバンク株式会社」）
+- 1日に使える回数は **200回** までです（残り回数は毎回表示されます）
+- 企業検索は、結果が見つからなくても **1回分消費** されます
+- 部署検索・人事検索は、データが見つからなかった場合は **消費されません**
 
-このリストの会社の電話番号をスプレッドシートのB列に入れて
-```
+---
+
+## 提供ツール（参考情報）
+
+通常はツール名を意識する必要はありません。Claude が自動で適切なツールを選びます。
+
+| ツール名 | 説明 | API消費 |
+|---------|------|--------|
+| `bizgate__company_search` | 企業の基本情報（住所・電話・代表者・業種・資本金 等） | 1回 |
+| `bizgate__department_search` | 部署情報（部署名・住所・電話番号）最大500件 | 1回 |
+| `bizgate__marketing_tags` | マーケティングタグ（SNS・MA・サービス・活動） | 1回 |
+| `bizgate__keyman_search` | 人事情報（部署・役職・発令日）最大500件 | 1回 |
+| `bizgate__company_full` | 企業＋部署＋人事を一括取得 | 3回 |
+| `bizgate__usage_status` | 本日の残りAPI回数を確認 | 0回 |
+
+---
 
-## 環境変数一覧
+## 環境変数一覧（参考情報）
 
 | 変数名 | 必須 | 説明 |
 |-------|------|------|
-| `BIZGATE_USERNAME` | ○（basic認証時） | BizGate ユーザー名 |
-| `BIZGATE_PASSWORD` | ○（basic認証時） | BizGate パスワード |
+| `BIZGATE_USERNAME` | ○ | BizGate ユーザー名 |
+| `BIZGATE_PASSWORD` | ○ | BizGate パスワード |
 | `BIZGATE_AUTH_MODE` | | `basic`（デフォルト）または `ip` |
-| `BIZGATE_APP` | ○（IP認証時） | アプリ識別子 |
+| `BIZGATE_APP` | ○（IP認証時のみ） | アプリ識別子 |
 | `BIZGATE_SKEY_COMPANY` | ○ | 企業APIのサービスキー |
 | `BIZGATE_SKEY_DEPARTMENT` | ○ | 部署APIのサービスキー |
 | `BIZGATE_SKEY_MARKETING` | | マーケティングタグAPIのサービスキー |
 | `BIZGATE_SKEY_KEYMAN` | | キーマンAPIのサービスキー |
 | `BIZGATE_DAILY_LIMIT` | | 1日のAPI上限（デフォルト: 200） |
-| `BIZGATE_BASE_URL` | | APIエンドポイント（通常変更不要） |
 
-## API利用上の注意
+---
+
+## うまくいかないとき
+
+### `/mcp` で `bizgate` が `failed` になっている
+
+ステップ 3 の設定ファイルに入力ミスがある可能性が高いです。以下を確認してください。
+
+- ダブルクォーテーション `"` が抜けていないか
+- カンマ `,` が余分についていないか（特に **最後の行の末尾**）
+- ユーザー名・パスワード・サービスキーが正しいか
+
+確認しても直らない場合は、管理者に `~/.claude.json` の中身を見せて相談してください。
+
+### 「サービスキーが無効です」と表示される
+
+サービスキーが間違っている、または有効期限切れです。管理者に確認してください。
+
+### 「1日のリクエスト上限に達しました」と表示される
+
+本日の利用回数（200回）を使い切りました。翌日にリセットされます。
+
+### 「該当する企業が見つかりませんでした」と表示される
+
+会社名を **正式名称** で入力してみてください。
+- 悪い例：「トヨタ」
+- 良い例：「トヨタ自動車株式会社」
+
+法人番号がわかる場合は、そちらでも検索できます。
 
-- **企業検索は結果なしでも課金**されます。会社名は正確に入力してください
-- **部署・マーケ・キーマンはデータなしなら課金なし**です
-- 1日のAPI上限はエンリッチメントパイプラインと共有です（全体900回中、MCP用に200回を確保）
-- すべてのレスポンスに残りAPI回数が表示されます
+### 「複数の企業が存在します」と表示される
 
-## トラブルシューティング
+検索条件が曖昧で、複数の企業がヒットしています。
+会社名をより正確に入力するか、メールアドレスやホームページURLを追加で伝えてください。
 
-| 症状 | 原因 | 対処法 |
-|------|------|--------|
-| `/mcp` で `failed` | 環境変数の設定ミス | `~/.claude.json` の env を確認 |
-| エラーコード 102 | サービスキーが無効 | 管理者に有効なサービスキーを確認 |
-| エラーコード 112 | 1日の上限超過 | 翌日まで待つ、または上限を確認 |
-| エラーコード 204 | 企業が見つからない | 正式名称（株式会社○○）で再検索 |
-| エラーコード 205 | 複数企業がマッチ | 法人番号やメールアドレスを追加で指定 |

package/dist/bizgate-client.d.ts

@@ -65,4 +65,29 @@ export declare class BizGateClient {
         docs: BizGateDoc[];
         numFound: number;
     }>;
+    /**
+     * Keyman with name lookup (キーマン・人名あり).
+     * Two-step flow: uses IDs from searchKeyman() to get person names.
+     * Not billed on failure.
+     */
+    getKeymanDetails(keymanIDs: string[]): Promise<{
+        docs: BizGateDoc[];
+    }>;
+    /**
+     * Full keyman search with names (2-step).
+     * Step 1: searchKeyman() to get IDs
+     * Step 2: getKeymanDetails() to get names for each ID
+     */
+    searchKeymanWithNames(params: {
+        shogo?: string;
+        compno?: string;
+        pList?: string;
+        cList?: string;
+        bKwd?: string;
+        bKOpr?: string;
+        limit?: number;
+    }): Promise<{
+        docs: BizGateDoc[];
+        totalFound: number;
+    }>;
 }

package/dist/bizgate-client.js

@@ -137,4 +137,49 @@ export class BizGateClient {
             numFound: result.response?.numFound ?? 0,
         };
     }
+    /**
+     * Keyman with name lookup (キーマン・人名あり).
+     * Two-step flow: uses IDs from searchKeyman() to get person names.
+     * Not billed on failure.
+     */
+    async getKeymanDetails(keymanIDs) {
+        const allDocs = [];
+        for (const id of keymanIDs) {
+            this.usageTracker.increment();
+            const result = await this.request(this.config.skeyKeymanName, {
+                keymanID: id,
+            });
+            if (result.response?.docs) {
+                allDocs.push(...result.response.docs);
+            }
+        }
+        return { docs: allDocs };
+    }
+    /**
+     * Full keyman search with names (2-step).
+     * Step 1: searchKeyman() to get IDs
+     * Step 2: getKeymanDetails() to get names for each ID
+     */
+    async searchKeymanWithNames(params) {
+        // Step 1: Get IDs
+        const { docs: keymanDocs, numFound } = await this.searchKeyman({
+            shogo: params.shogo,
+            compno: params.compno,
+            pList: params.pList,
+            cList: params.cList,
+            bKwd: params.bKwd,
+            bKOpr: params.bKOpr,
+        });
+        if (keymanDocs.length === 0) {
+            return { docs: [], totalFound: 0 };
+        }
+        // Step 2: Get details with names (limit to avoid excessive API calls)
+        const maxDetails = params.limit ?? 10;
+        const ids = keymanDocs
+            .slice(0, maxDetails)
+            .map((d) => d.id)
+            .filter((id) => !!id);
+        const { docs: detailDocs } = await this.getKeymanDetails(ids);
+        return { docs: detailDocs, totalFound: numFound };
+    }
 }

package/dist/index.js

@@ -12,6 +12,7 @@ const skeyCompany = process.env.BIZGATE_SKEY_COMPANY;
 const skeyDepartment = process.env.BIZGATE_SKEY_DEPARTMENT;
 const skeyMarketing = process.env.BIZGATE_SKEY_MARKETING ?? "";
 const skeyKeyman = process.env.BIZGATE_SKEY_KEYMAN ?? "";
+const skeyKeymanName = process.env.BIZGATE_SKEY_KEYMAN_NAME ?? "";
 if (!skeyCompany || !skeyDepartment) {
     console.error("Error: BIZGATE_SKEY_COMPANY and BIZGATE_SKEY_DEPARTMENT environment variables are required");
     process.exit(1);
@@ -39,6 +40,7 @@ const config = {
     skeyDepartment,
     skeyMarketing,
     skeyKeyman,
+    skeyKeymanName,
     authMode,
     username: process.env.BIZGATE_USERNAME,
     password: process.env.BIZGATE_PASSWORD,
@@ -247,14 +249,21 @@ server.tool("bizgate__marketing_tags", "会社名または法人番号で企業
         const lines = [`## マーケティングタグ: ${f(doc.shogo)}`];
         if (doc.compno)
             lines.push(`法人番号: ${doc.compno}`);
+        const formatTags = (raw) => {
+            return raw
+                .split("/")
+                .filter((t) => t.trim())
+                .map((t) => `- ${t.trim()}`)
+                .join("\n");
+        };
         if (doc.snstag)
-            lines.push(`\n### SNSタグ\n${doc.snstag.replace(/¥\//g, "\n- ").replace(/^/, "- ")}`);
+            lines.push(`\n### SNSタグ\n${formatTags(doc.snstag)}`);
         if (doc.matag)
-            lines.push(`\n### MAツール\n${doc.matag.replace(/¥\//g, "\n- ").replace(/^/, "- ")}`);
+            lines.push(`\n### MAツール\n${formatTags(doc.matag)}`);
         if (doc.servicetag)
-            lines.push(`\n### 事業サービス\n${doc.servicetag.replace(/¥\//g, "\n- ").replace(/^/, "- ")}`);
+            lines.push(`\n### 事業サービス\n${formatTags(doc.servicetag)}`);
         if (doc.activtag)
-            lines.push(`\n### 活動タグ\n${doc.activtag.replace(/¥\//g, "\n- ").replace(/^/, "- ")}`);
+            lines.push(`\n### 活動タグ\n${formatTags(doc.activtag)}`);
         return {
             content: [{ type: "text", text: lines.join("\n") + usageFooter() }],
         };
@@ -263,26 +272,28 @@ server.tool("bizgate__marketing_tags", "会社名または法人番号で企業
         return { content: [{ type: "text", text: errorText(e) }] };
     }
 });
-// ---------- Tool 4: キーマン検索 ----------
-server.tool("bizgate__keyman_search", "会社名または法人番号で人事情報（部署・役職、発表日、発令日）を検索する。最大500件。部署カテゴリやキーワードで絞り込み可能。人名は含まれない。課金なし（企業特定不可・データなしの場合）。", {
+// ---------- Tool 4: キーマン検索（人名付き） ----------
+server.tool("bizgate__keyman_search", "会社名または法人番号で人事情報（担当者名・部署・役職・電話番号・住所）を検索する。部署カテゴリやキーワードで絞り込み可能。デフォルトで上位10名の詳細を取得（limitで変更可能）。API消費: 1回（一覧取得）+ N回（詳細取得、Nはlimit数）。", {
     shogo: z.string().optional().describe("会社名（例：株式会社○○）"),
     compno: z.string().optional().describe("法人番号（13桁）"),
     pList: z.string().optional().describe("都道府県コード（カンマ区切り）"),
     cList: z.string().optional().describe("部署カテゴリ番号（カンマ区切り。3=人事,13=営業 など）"),
-    bKwd: z.string().optional().describe("部署・役職キーワード（カンマ区切り。例: 役員,部長,ソリューション）"),
+    bKwd: z.string().optional().describe("部署・役職キーワード（カンマ区切り。例: 役員,部長,営業）"),
     bKOpr: z.string().optional().describe("キーワード結合演算子（0=OR（デフォルト）, 1=AND）"),
-}, async ({ shogo, compno, pList, cList, bKwd, bKOpr }) => {
+    limit: z.number().optional().describe("詳細取得する人数の上限（デフォルト: 10、最大: 50）。API消費に注意。"),
+}, async ({ shogo, compno, pList, cList, bKwd, bKOpr, limit }) => {
     const err = validateInput(shogo, compno);
     if (err)
         return { content: [{ type: "text", text: err }] };
-    if (!skeyKeyman) {
+    if (!skeyKeyman || !skeyKeymanName) {
         return {
-            content: [{ type: "text", text: "エラー: BIZGATE_SKEY_KEYMAN が設定されていません。" }],
+            content: [{ type: "text", text: "エラー: BIZGATE_SKEY_KEYMAN および BIZGATE_SKEY_KEYMAN_NAME が設定されていません。" }],
         };
     }
+    const maxLimit = Math.min(limit ?? 10, 50);
     try {
-        const { docs, numFound } = await client.searchKeyman({
-            shogo, compno, pList, cList, bKwd, bKOpr,
+        const { docs, totalFound } = await client.searchKeymanWithNames({
+            shogo, compno, pList, cList, bKwd, bKOpr, limit: maxLimit,
         });
         if (docs.length === 0) {
             return {
@@ -290,8 +301,24 @@ server.tool("bizgate__keyman_search", "会社名または法人番号で人事
             };
         }
         const companyName = f(docs[0].shogo);
-        const header = `## 人事情報${companyName ? `: ${companyName}` : ""}（全${numFound}件）\n`;
-        const text = docs.map((d, i) => formatKeymanDoc(d, i + 1)).join("\n\n");
+        const header = `## 人事情報${companyName ? `: ${companyName}` : ""}（全${totalFound}件中、上位${docs.length}件の詳細）\n`;
+        const text = docs
+            .map((d, i) => {
+            const lines = [`${i + 1}. ${f(d.ceo) || "(氏名不明)"}`];
+            lines.push(`   役職: ${f(d.bumon) || "(不明)"}`);
+            if (f(d.tel))
+                lines.push(`   電話: ${f(d.tel)}`);
+            if (f(d.add))
+                lines.push(`   住所: ${f(d.add)}`);
+            if (d.haturei)
+                lines.push(`   発令日: ${d.haturei}`);
+            if (d.pagedate)
+                lines.push(`   発表日: ${d.pagedate}`);
+            if (d.bikou)
+                lines.push(`   備考: ${d.bikou}`);
+            return lines.join("\n");
+        })
+            .join("\n\n");
         return {
             content: [{ type: "text", text: header + text + usageFooter() }],
         };

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export interface BizGateConfig {
     skeyDepartment: string;
     skeyMarketing: string;
     skeyKeyman: string;
+    skeyKeymanName: string;
     authMode: "basic" | "ip";
     username?: string;
     password?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bizgate-mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "BizGate APIとClaudeを連携するMCPサーバー",
   "type": "module",
   "main": "dist/index.js",