bizgate-mcp-server 0.1.0 → 0.3.0

package/README.md

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

package/dist/bizgate-client.d.ts

@@ -2,17 +2,37 @@ import type { BizGateConfig, BizGateDoc } from "./types.js";
 import { UsageTracker } from "./usage-tracker.js";
 /** Extract first element from a string array field, or return empty string. */
 export declare function first(field: string[] | string | undefined): string;
+interface CompanyResult {
+    matchPattern: string;
+    docs: BizGateDoc[];
+}
+interface DepartmentResult {
+    docs: BizGateDoc[];
+    numFound: number;
+}
+interface MarketingResult {
+    docs: BizGateDoc[];
+}
+interface KeymanResult {
+    docs: BizGateDoc[];
+    numFound: number;
+}
 export declare class BizGateClient {
     private config;
     private usageTracker;
+    private companyCache;
+    private departmentCache;
+    private marketingCache;
+    private keymanCache;
     constructor(config: BizGateConfig, usageTracker: UsageTracker);
     private buildUrl;
     private getHeaders;
-    /** Send GET request and return parsed response. */
     private request;
+    /** Build cache key from params. */
+    private cacheKey;
     /**
      * Company lookup (企業).
-     * Billed even on no-result — usage tracker is incremented BEFORE the call.
+     * Cached for 60s. Billed even on no-result.
      */
     searchCompany(params: {
         shogo?: string;
@@ -20,13 +40,10 @@ export declare class BizGateClient {
         hpurl?: string;
         email?: string;
         tel?: string;
-    }): Promise<{
-        matchPattern: string;
-        docs: BizGateDoc[];
-    }>;
+    }): Promise<CompanyResult>;
     /**
      * Department lookup (部署).
-     * Not billed on failure, but we count conservatively.
+     * Cached for 60s. Not billed on failure.
      */
     searchDepartments(params: {
         shogo?: string;
@@ -35,24 +52,18 @@ export declare class BizGateClient {
         cList?: string;
         bKwd?: string;
         bKOpr?: string;
-    }): Promise<{
-        docs: BizGateDoc[];
-        numFound: number;
-    }>;
+    }): Promise<DepartmentResult>;
     /**
      * Marketing tags lookup (マーケティングタグ).
-     * Not billed on failure (company not found or no tags).
+     * Cached for 60s. Not billed on failure.
      */
     searchMarketingTags(params: {
         shogo?: string;
         compno?: string;
-    }): Promise<{
-        docs: BizGateDoc[];
-    }>;
+    }): Promise<MarketingResult>;
     /**
      * Keyman lookup (キーマン・人名なし).
-     * Returns personnel records (department + title, announcement date, etc.).
-     * Not billed on failure.
+     * Cached for 60s. Not billed on failure.
      */
     searchKeyman(params: {
         shogo?: string;
@@ -61,8 +72,28 @@ export declare class BizGateClient {
         cList?: string;
         bKwd?: string;
         bKOpr?: string;
+    }): Promise<KeymanResult>;
+    /**
+     * Keyman with name lookup (キーマン・人名あり).
+     * Fetches details in parallel for speed.
+     */
+    getKeymanDetails(keymanIDs: string[]): Promise<{
+        docs: BizGateDoc[];
+    }>;
+    /**
+     * Full keyman search with names (2-step).
+     */
+    searchKeymanWithNames(params: {
+        shogo?: string;
+        compno?: string;
+        pList?: string;
+        cList?: string;
+        bKwd?: string;
+        bKOpr?: string;
+        limit?: number;
     }): Promise<{
         docs: BizGateDoc[];
-        numFound: number;
+        totalFound: number;
     }>;
 }
+export {};

package/dist/bizgate-client.js

@@ -1,13 +1,20 @@
 import { BizGateApiError, BIZGATE_ERROR_CODES } from "./types.js";
+import { Cache } from "./cache.js";
 /** Extract first element from a string array field, or return empty string. */
 export function first(field) {
     if (Array.isArray(field))
         return field[0] ?? "";
     return field ?? "";
 }
+// Cache TTL: 60 seconds — same company searched within 60s won't hit the API again
+const CACHE_TTL = 60_000;
 export class BizGateClient {
     config;
     usageTracker;
+    companyCache = new Cache(CACHE_TTL);
+    departmentCache = new Cache(CACHE_TTL);
+    marketingCache = new Cache(CACHE_TTL);
+    keymanCache = new Cache(CACHE_TTL);
     constructor(config, usageTracker) {
         this.config = config;
         this.usageTracker = usageTracker;
@@ -28,7 +35,6 @@ export class BizGateClient {
         }
         return {};
     }
-    /** Send GET request and return parsed response. */
     async request(skey, params) {
         const url = this.buildUrl(skey, params);
         const response = await fetch(url, { headers: this.getHeaders() });
@@ -36,7 +42,6 @@ export class BizGateClient {
             throw new BizGateApiError(String(response.status), `HTTP ${response.status}: ${response.statusText}`);
         }
         const json = (await response.json());
-        // Error response: status=999, error.code + error.msg
         if (json.responseHeader.status === 999) {
             const err = json.responseHeader.error;
             const code = err?.code ?? "unknown";
@@ -47,11 +52,23 @@ export class BizGateClient {
         }
         return json;
     }
+    /** Build cache key from params. */
+    cacheKey(params) {
+        return Object.entries(params)
+            .filter(([, v]) => v)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${k}=${v}`)
+            .join("&");
+    }
     /**
      * Company lookup (企業).
-     * Billed even on no-result — usage tracker is incremented BEFORE the call.
+     * Cached for 60s. Billed even on no-result.
      */
     async searchCompany(params) {
+        const key = this.cacheKey(params);
+        const cached = this.companyCache.get(key);
+        if (cached)
+            return cached;
         this.usageTracker.increment();
         const queryParams = {};
         if (params.shogo)
@@ -65,16 +82,22 @@ export class BizGateClient {
         if (params.tel)
             queryParams.tel = params.tel;
         const result = await this.request(this.config.skeyCompany, queryParams);
-        return {
+        const data = {
             matchPattern: result.responseHeader.matchpatern ?? "",
             docs: result.response?.docs ?? [],
         };
+        this.companyCache.set(key, data);
+        return data;
     }
     /**
      * Department lookup (部署).
-     * Not billed on failure, but we count conservatively.
+     * Cached for 60s. Not billed on failure.
      */
     async searchDepartments(params) {
+        const key = this.cacheKey(params);
+        const cached = this.departmentCache.get(key);
+        if (cached)
+            return cached;
         this.usageTracker.increment();
         const queryParams = {};
         if (params.shogo)
@@ -90,16 +113,22 @@ export class BizGateClient {
         if (params.bKOpr)
             queryParams.bKOpr = params.bKOpr;
         const result = await this.request(this.config.skeyDepartment, queryParams);
-        return {
+        const data = {
             docs: result.response?.docs ?? [],
             numFound: result.response?.numFound ?? 0,
         };
+        this.departmentCache.set(key, data);
+        return data;
     }
     /**
      * Marketing tags lookup (マーケティングタグ).
-     * Not billed on failure (company not found or no tags).
+     * Cached for 60s. Not billed on failure.
      */
     async searchMarketingTags(params) {
+        const key = this.cacheKey(params);
+        const cached = this.marketingCache.get(key);
+        if (cached)
+            return cached;
         this.usageTracker.increment();
         const queryParams = {};
         if (params.shogo)
@@ -107,16 +136,21 @@ export class BizGateClient {
         if (params.compno)
             queryParams.compno = params.compno;
         const result = await this.request(this.config.skeyMarketing, queryParams);
-        return {
+        const data = {
             docs: result.response?.docs ?? [],
         };
+        this.marketingCache.set(key, data);
+        return data;
     }
     /**
      * Keyman lookup (キーマン・人名なし).
-     * Returns personnel records (department + title, announcement date, etc.).
-     * Not billed on failure.
+     * Cached for 60s. Not billed on failure.
      */
     async searchKeyman(params) {
+        const key = this.cacheKey(params);
+        const cached = this.keymanCache.get(key);
+        if (cached)
+            return cached;
         this.usageTracker.increment();
         const queryParams = {};
         if (params.shogo)
@@ -132,9 +166,64 @@ export class BizGateClient {
         if (params.bKOpr)
             queryParams.bKOpr = params.bKOpr;
         const result = await this.request(this.config.skeyKeyman, queryParams);
-        return {
+        const data = {
             docs: result.response?.docs ?? [],
             numFound: result.response?.numFound ?? 0,
         };
+        this.keymanCache.set(key, data);
+        return data;
+    }
+    /**
+     * Keyman with name lookup (キーマン・人名あり).
+     * Fetches details in parallel for speed.
+     */
+    async getKeymanDetails(keymanIDs) {
+        const fetchOne = async (id) => {
+            this.usageTracker.increment();
+            try {
+                const result = await this.request(this.config.skeyKeymanName, {
+                    keymanID: id,
+                });
+                return result.response?.docs?.[0] ?? null;
+            }
+            catch {
+                return null;
+            }
+        };
+        // Parallel fetch (max 5 concurrent)
+        const results = [];
+        const batchSize = 5;
+        for (let i = 0; i < keymanIDs.length; i += batchSize) {
+            const batch = keymanIDs.slice(i, i + batchSize);
+            const batchResults = await Promise.all(batch.map(fetchOne));
+            for (const doc of batchResults) {
+                if (doc)
+                    results.push(doc);
+            }
+        }
+        return { docs: results };
+    }
+    /**
+     * Full keyman search with names (2-step).
+     */
+    async searchKeymanWithNames(params) {
+        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 };
+        }
+        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/cache.d.ts

@@ -0,0 +1,9 @@
+/** Simple in-memory TTL cache. */
+export declare class Cache<T> {
+    private ttlMs;
+    private store;
+    constructor(ttlMs: number);
+    get(key: string): T | undefined;
+    set(key: string, data: T): void;
+    has(key: string): boolean;
+}

package/dist/cache.js

@@ -0,0 +1,24 @@
+/** Simple in-memory TTL cache. */
+export class Cache {
+    ttlMs;
+    store = new Map();
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expires) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.data;
+    }
+    set(key, data) {
+        this.store.set(key, { data, expires: Date.now() + this.ttlMs });
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+}

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,
@@ -192,17 +194,19 @@ server.tool("bizgate__company_search", "会社名または法人番号で企業
     }
 });
 // ---------- Tool 2: 部署検索 ----------
-server.tool("bizgate__department_search", "会社名または法人番号で部署情報（部署名・住所・電話番号・カテゴリ）を検索する。最大500件。都道府県・カテゴリ・部署名キーワードで絞り込み可能。", {
+server.tool("bizgate__department_search", "会社名または法人番号で部署情報（部署名・住所・電話番号・カテゴリ）を検索する。最大500件。都道府県・カテゴリ・部署名キーワードで絞り込み可能。デフォルトで上位30件を表示（limitで変更可能）。", {
     shogo: z.string().optional().describe("会社名（例：株式会社○○）"),
     compno: z.string().optional().describe("法人番号（13桁）"),
     pList: z.string().optional().describe("都道府県コード（カンマ区切り。例: 13,14 = 東京都,神奈川県）"),
     cList: z.string().optional().describe("部署カテゴリ番号（カンマ区切り。1=経営企画,2=営業企画,3=人事,4=経理,5=総務,6=広報IR,7=法務,8=研究,9=購買,10=システム,11=海外,12=環境CSR,13=営業,14=製造工場,15=その他）"),
     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("表示する件数の上限（デフォルト: 30）"),
+}, async ({ shogo, compno, pList, cList, bKwd, bKOpr, limit }) => {
     const err = validateInput(shogo, compno);
     if (err)
         return { content: [{ type: "text", text: err }] };
+    const displayLimit = limit ?? 30;
     try {
         const { docs, numFound } = await client.searchDepartments({
             shogo, compno, pList, cList, bKwd, bKOpr,
@@ -213,10 +217,14 @@ server.tool("bizgate__department_search", "会社名または法人番号で部
             };
         }
         const companyName = f(docs[0].shogo);
-        const header = `## 部署情報${companyName ? `: ${companyName}` : ""}（全${numFound}件）\n`;
-        const text = docs.map((d, i) => formatDepartmentDoc(d, i + 1)).join("\n\n");
+        const displayed = docs.slice(0, displayLimit);
+        const header = `## 部署情報${companyName ? `: ${companyName}` : ""}（全${numFound}件中${displayed.length}件表示）\n`;
+        const text = displayed.map((d, i) => formatDepartmentDoc(d, i + 1)).join("\n\n");
+        const truncNote = docs.length > displayLimit
+            ? `\n\n> 残り${numFound - displayLimit}件あります。キーワード（bKwd）やカテゴリ（cList）で絞り込むか、limitを増やしてください。`
+            : "";
         return {
-            content: [{ type: "text", text: header + text + usageFooter() }],
+            content: [{ type: "text", text: header + text + truncNote + usageFooter() }],
         };
     }
     catch (e) {
@@ -247,14 +255,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 +278,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 +307,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() }],
         };
@@ -301,7 +334,7 @@ server.tool("bizgate__keyman_search", "会社名または法人番号で人事
     }
 });
 // ---------- Tool 5: 企業総合検索（企業+部署+キーマンを一括取得） ----------
-server.tool("bizgate__company_full", "会社名または法人番号で企業情報・部署情報・人事情報を一括取得する。個別ツールを3回呼ぶ代わりに1回で全情報を取得可能。API 3回分を消費。部署やキーワードで絞り込みも可能。", {
+server.tool("bizgate__company_full", "会社名または法人番号で企業情報・部署情報・人事情報を一括取得する。個別ツールを3回呼ぶ代わりに1回で全情報を取得可能。API 3回分を消費。部署は上位15件、人事は役職一覧のみ（人名は含まない）。人名が必要な場合はbizgate__keyman_searchを別途使用。", {
     shogo: z.string().optional().describe("会社名（例：株式会社○○）"),
     compno: z.string().optional().describe("法人番号（13桁）"),
     hpurl: z.string().optional().describe("ホームページURL（企業特定精度向上）"),
@@ -329,15 +362,19 @@ server.tool("bizgate__company_full", "会社名または法人番号で企業情
     catch (e) {
         sections.push(`企業情報: ${e instanceof Error ? e.message : "取得失敗"}`);
     }
-    // 2. Department info
+    // 2. Department info (top 15 for token efficiency)
     try {
         const { docs, numFound } = await client.searchDepartments({
             shogo, compno, bKwd, cList,
         });
         if (docs.length > 0) {
+            const displayed = docs.slice(0, 15);
             const companyName = f(docs[0].shogo);
-            sections.push(`\n## 部署情報${companyName ? `: ${companyName}` : ""}（全${numFound}件）`);
-            sections.push(docs.map((d, i) => formatDepartmentDoc(d, i + 1)).join("\n\n"));
+            sections.push(`\n## 部署情報${companyName ? `: ${companyName}` : ""}（全${numFound}件中${displayed.length}件表示）`);
+            sections.push(displayed.map((d, i) => formatDepartmentDoc(d, i + 1)).join("\n\n"));
+            if (numFound > 15) {
+                sections.push(`\n> 残り${numFound - 15}件はbizgate__department_searchで個別に取得できます。`);
+            }
         }
         else {
             sections.push("\n## 部署情報\n該当なし");

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.3.0",
   "description": "BizGate APIとClaudeを連携するMCPサーバー",
   "type": "module",
   "main": "dist/index.js",