Employees

サンプルの従業員情報を格納したローカル SQLite データベースを、 Model Context Protocol (MCP) サーバーとして公開します。AI エージェントから 従業員の検索・組織構造の照会ができます。

概要

• データソース: scripts/build_employees_db.py で生成する data/employees.db（サンプル36名）
• REST API などの外部依存はなく、ローカル DB のみで完結
• トランスポート: stdio（ローカル）と HTTP/SSE の両対応

MCP クライアントの設定方法・ツールの詳しい使い方は USAGE.md を参照してください。 Claude Desktop / VS Code などへの登録手順、各ツールのパラメータ、使用例をまとめています。

提供ツール

ツール	説明
lookup_employee(employee_id)	従業員 ID から 1 名の詳細を取得。ID は大文字小文字不問・数字のみでも補完（"1"→"E0001"）。上長名も付与。
search_employees(query="", department="", office_location="", employment_type="", status="", limit=50)	氏名・メール・電話・役職・部署を横断キーワード検索。部署／勤務地／雇用形態／在籍状況で絞り込み可。
list_departments()	部署ごとの在籍人数一覧（人数の多い順）。
get_direct_reports(manager_id)	指定従業員の直属の部下一覧（組織図のドリルダウン）。
get_management_chain(employee_id)	指定従業員の上長チェーン（直属の上長→最上位までのレポートライン）。

いずれのツールも結果を整形済み JSON 文字列で返します。

データ項目（employees テーブル）

カラム	説明
employee_id	従業員 ID（主キー、例 E0001）
first_name / last_name	名 / 姓（full_name に姓名結合を付与）
email / phone	メールアドレス（一意） / 電話番号
department	部署（例 開発部）
job_title	役職（例 バックエンドエンジニア）
employment_type	雇用形態（正社員 / 契約社員 / パートタイム / インターン）
office_location	勤務地（例 東京本社）
hire_date	入社日（YYYY-MM-DD）
manager_id	上長の従業員 ID（無い場合は null）
status	在籍状況（例 在籍中）

必要要件

• Python 3.10 以上
• pip

セットアップ

# 仮想環境の作成・有効化
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/Mac

# 依存関係のインストール
pip install -r requirements.txt

初回起動までの最短手順

Windows PowerShell で、リポジトリ直下から以下の順に実行します。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

# data/employees.db が無い場合のみ作成
python scripts\build_employees_db.py --db data\employees.db

# ローカル MCP クライアントから使う場合
python main.py --transport stdio

# HTTP/SSE で起動する場合
python main.py --transport sse

HTTP/SSE モードで起動した場合、MCP クライアントには http://localhost:38117/sse を登録します。.env を作成しない場合も既定値で起動できます。

環境変数ファイル（.env）の作成

設定をカスタマイズする場合は、同梱の .env.example をコピーして .env を作成し、 必要な項目を編集します（.env は Git 管理対象外です）。既定値のままで動く場合は 作成を省略しても構いません。

copy .env.example .env        # Windows (PowerShell では Copy-Item .env.example .env)
# cp .env.example .env        # Linux/Mac

設定できる項目（DB_PATH / HTTP_HOST / HTTP_PORT / LOG_LEVEL / ALLOWED_HOSTS など）の 詳細は USAGE.md を参照してください。

実行方法

2 つのモードの違い（MCP をはじめて使う方へ）

このサーバーは、AI クライアント（Claude Desktop / VS Code など）と通信する方式（トランスポート）を 2 種類から選べます。どちらもツールの機能は同じで、違いは「AI クライアントとどうつながるか」だけです。

• stdio モード: AI クライアントがこのサーバーを子プロセスとして起動し、標準入出力 （キーボード入力・画面出力に使われるパイプ）を通じて 1 対 1 で会話します。 ネットワークを一切使わないため、同じ PC 上で使うのが前提です。
• HTTP/SSE モード: このサーバーを常駐する Web サーバーとして起動しておき、AI クライアントが http://…/sse という URL 経由で接続します。ネットワーク越しに使えるため、別の PC やコンテナ からも接続でき、複数のクライアントで共有できます。

観点	stdio モード	HTTP/SSE モード
起動する人	AI クライアントが自動で起動	自分で先に起動しておく（常駐）
通信経路	標準入出力（ネットワーク不使用）	HTTP（http://localhost:38117/sse）
接続範囲	同じ PC 内のみ	別 PC・コンテナからも可・複数接続可
設定の手間	少ない（コマンドを登録するだけ）	サーバーを起動＆URL を登録する
向いている用途	手元の Claude Desktop などで手軽に使う	チーム共有・Docker・リモート運用

迷ったら stdio モードを選んでください。 手元の PC で Claude Desktop や VS Code から使うだけなら stdio が最も簡単です。Docker で動かしたい、1 つのサーバーを複数人や複数ツールで共有したい、 別のマシンから接続したい、といった場合に HTTP/SSE モードを選びます。

stdio モード（ローカル MCP クライアント向け）

python main.py --transport stdio

設定例は examples/mcp-config-stdio.json を参照。

HTTP/SSE モード

python main.py --transport sse

SSE エンドポイント: http://localhost:38117/sse （ホスト・ポートは環境変数 HTTP_HOST / HTTP_PORT で変更可能）

MCP クライアントの設定・使い方

MCP クライアント（Claude Desktop / VS Code など）への登録手順、各ツールの パラメータ詳細、使用例は USAGE.md にまとめています。主な内容:

• Claude Desktop への登録（stdio モード）: claude_desktop_config.json の設定例
• VS Code への登録（HTTP/SSE モード）: .vscode/mcp.json の設定例
• 各ツールのパラメータ表
• 環境変数（.env）・トラブルシューティング

設定例ファイルは examples/mcp-config-stdio.json も参照できます。

データベースの再構築

data/employees.db は同梱済みですが、サンプルデータから再構築するには:

python scripts/build_employees_db.py --db data/employees.db

スキーマ:

• employees(employee_id, first_name, last_name, email, phone, department, job_title, employment_type, office_location, hire_date, manager_id, status)
• manager_id は同テーブルの employee_id を参照する自己参照（組織構造）。

テスト

pytest tests/ -v

Docker

docker build -t employees-mcp-server .
docker run -p 48117:38117 employees-mcp-server python main.py --transport sse

SSE エンドポイントは http://localhost:48117/sse です。

※ Dockerfile の CMD は既定で stdio 起動です。HTTP/SSE で使う場合は、上記のように python main.py --transport sse を指定して起動してください。

docker compose

docker-compose.yml で SSE 起動・DB マウント済みの構成を用意しています。

docker compose up -d

• コンテナ内部ポートは 38117 固定（HTTP_PORT）、ホスト公開ポートは 48117 に マッピングしています（ports: "48117:38117"）。ホスト側からは http://localhost:48117/sse でアクセスします。公開ポートを変えたい場合は docker-compose.yml の ports の左側の番号を変更してください。
• data/employees.db は読み取り専用（:ro）でマウントされます。

ライセンス

MIT