K Targo Subway MCP Server

🚀 K-Targo Subway MCP Server

このサーバーは韓国の地下鉄情報を提供するMCP (Model Context Protocol) サーバーです。APIを通じて、地下鉄駅の検索や列車時刻表の照会、リアルタイムの地下鉄情報を取得することができます。

✨ 主な機能

• 地下鉄駅検索：駅名を使って地下鉄駅の情報を検索できます。
• 列車時刻表照会：特定の駅の列車時刻表を照会できます。
• リアルタイム地下鉄情報：Tago APIを通じてリアルタイムのデータを提供します。
• MCP標準準拠：Model Context Protocol標準に準拠したツールを提供します。

📦 インストール

Smitheryを通じたインストール

Smithery を通じてClaude Desktop用の k-targo-subway-mcp-server を自動でインストールするには、以下のコマンドを実行します。

npx -y @smithery/cli install @slicequeue/k-targo-subway-mcp-server --client claude

1. 公共データAPIキーの設定

このサーバーは 国土交通省_(TAGO)_地下鉄情報 APIを使用しています。使用する前に、APIキーを設定する必要があります。

API情報

• API名：国土交通省_(TAGO)_地下鉄情報
• API URL：https://www.data.go.kr/data/15098554/openapi.do
• 提供機関：国土交通省
• データ形式：JSON

APIキーの発行

1. 公共データポータル に登録します。
2. "国土交通省_(TAGO)_地下鉄情報" APIを申請します。
3. 承認された後、発行されたAPIキーを環境変数として設定します。

環境変数の設定

# Windows
set GOV_API_KEY=your_api_key_here

# macOS/Linux
export GOV_API_KEY=your_api_key_here

# .envファイルの使用（推奨）
echo "GOV_API_KEY=your_api_key_here" > .env

2. npxで即時実行（推奨）

npx k-targo-subway-mcp-server

3. npmでインストール

npm install k-targo-subway-mcp-server

4. グローバルインストール

npm install -g k-targo-subway-mcp-server

💻 使用例

MCPツールの使用

1. 地下鉄駅検索 (search_subway_station)

地下鉄駅名を使って駅の情報を検索します。

入力パラメータ:

• stationName (string): 検索する駅名

使用例:

// "江南" 駅を検索
const result = await searchSubwayStationTool.handler({
  stationName: "江南"
}, {});

2. 列車時刻表照会 (get_station_timetable)

特定の駅の列車時刻表を照会します。

入力パラメータ:

• stationCode (string): 駅コード
• direction (string): 方向 (上り/下り)

使用例:

// 江南駅の上り時刻表を照会
const result = await getStationTimetableTool.handler({
  stationCode: "0222",
  direction: "上り"
}, {});

MCPクライアントでの使用

MCPクライアントの設定

MCPクライアントでこのサーバーを使用するには、以下のように設定します。

{
  "mcpServers": {
    "k-targo-subway": {
      "command": "npx",
      "args": ["k-targo-subway-mcp-server"],
      "env": {
        "GOV_API_KEY": "your_targo_api_key_here"
      }
    }
  }
}

MCPクライアントでの実行

// 地下鉄駅検索
const searchResult = await mcpClient.callTool('search_subway_station', {
  stationName: '江南'
});

// 時刻表照会
const timetableResult = await mcpClient.callTool('get_station_timetable', {
  stationCode: '0222',
  direction: '上り'
});

CLIでの直接実行

# npxで実行（推奨）
npx k-targo-subway-mcp-server

# グローバルインストール後の実行
k-targo-subway-mcp-server

# またはnpmスクリプトで実行
npm start

📚 詳細ドキュメント

プロジェクト構造

src/
├── config/           # 設定ファイル
│   └── index.ts
├── external/         # 外部API連携
│   ├── common/       # 共通ユーティリティ
│   └── tago-subway/  # Tago地下鉄API
│       ├── api.ts    # APIクライアント
│       ├── service.ts # ビジネスロジック
│       ├── dtos/     # データ転送オブジェクト
│       └── types/    # 型定義
├── tools/           # MCPツール
│   ├── subway.ts    # 地下鉄関連ツール
│   ├── index.ts     # ツールの統合
│   └── types.ts     # ツールの型定義
├── utils/           # ユーティリティ
│   ├── PackageJsonUtil.ts
│   └── ResponseUtil.ts
└── index.ts         # メインエントリポイント

開発環境の設定

1. 依存関係のインストール

npm install

2. APIキーの設定

# .envファイルの作成
echo "GOV_API_KEY=your_api_key_here" > .env

# または環境変数として設定
export GOV_API_KEY=your_api_key_here  # macOS/Linux
set GOV_API_KEY=your_api_key_here     # Windows

.envファイルの例

# 国土交通省_(TAGO)_地下鉄情報APIキー
# 公共データポータル(https://www.data.go.kr/)で発行されたAPIキーを設定してください
# API URL: https://www.data.go.kr/data/15098554/openapi.do
GOV_API_KEY=your_public_data_api_key_here

# 例:
# GOV_API_KEY=abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567

3. 開発サーバーの起動

npm run dev

4. ビルド

npm run build

5. テスト

# 全テスト
npm test

# APIテスト
npm run test:api

# 特定の駅のテスト
npm run test:api:station

API連携

国土交通省_(TAGO)_地下鉄情報API

• API名：国土交通省_(TAGO)_地下鉄情報
• API URL：https://www.data.go.kr/data/15098554/openapi.do
• 提供機関：国土交通省
• 基本URL：https://api.tago.go.kr
• 認証：公共データAPIキーに基づく認証 (GOV_API_KEY 環境変数)
• データ形式：JSON
• APIキーの発行：公共データポータル で "国土交通省_(TAGO)_地下鉄情報" を申請します。

環境変数の設定

# 必須環境変数
GOV_API_KEY=your_public_data_api_key_here

主なエンドポイント

• GET /subway-station/search：地下鉄駅の検索
• GET /subway-station/{stationCode}/timetable：列車時刻表の照会

開発ワークフロー

1. 新機能の追加：src/tools/ に新しいツールファイルを作成します。
2. API連携：src/external/ に外部APIクライアントを追加します。
3. 型定義：必要な型を定義します。
4. テスト：test/ ディレクトリにテストコードを作成します。
5. ビルドとデプロイ：npm run build を実行した後、デプロイします。

主な概念

MCP Tool

ユーザーが呼び出すことができる関数です。入力スキーマとハンドラー関数で構成されています。

TAGO API

国土交通省が提供する地下鉄情報APIです。公共データポータルを通じて利用できます。

地下鉄駅コード

各地下鉄駅には一意のコードが割り当てられています (例: 江南駅 = "0222")。

🚀 デプロイ

# ビルド
npm run build

# npmへの公開
npm publish

# 実行
node dist/index.js

📄 ライセンス

MIT License

🤝 コントリビューション

1. プロジェクトをForkします。
2. 新しい機能ブランチを作成します (git checkout -b feature/AmazingFeature)
3. 変更をコミットします (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュします (git push origin feature/AmazingFeature)
5. プルリクエストを作成します。

📞 問い合わせ

• GitHub: https://github.com/slicequeue/k-targo-subway-mcp-server
• Issues: https://github.com/slicequeue/k-targo-subway-mcp-server/issues

🙏 謝辞

• 国土交通省_(TAGO)_地下鉄情報 - 地下鉄情報の提供
• 公共データポータル - APIサービスの提供
• Model Context Protocol - MCP標準
• Node.js - ランタイム環境