M1 MCP

🚀 m1-mcp

このプロジェクトは、アカウントデータに関する3つのツールを提供する最小限のNode.js (TypeScript) MCPサーバーです。 デフォルトでは、メモリ内の小さなモックデータセットを提供します。環境変数を使用して、"Members 1st"のHTTPベースのデータソースに切り替えることも可能です。

🚀 クイックスタート

m1-mcpの初心者の方は、QUICKSTART.mdを参照して、5分で始めるガイドをご覧ください！

✨ 主な機能

• get_all_accounts：{ accounts: Account[] }を返します。
• get_account_details：{ accountId: string }を入力として受け取り、{ account }または{ error }を返します。
• get_account_transactions：accountId: stringが必須で、オプションとしてstartDateとendDate（YYYY-MM-DD形式、デフォルトは直近30日間）を指定できます。180日を超える日付範囲は自動的に分割され、結果がマージされます。

📦 インストール

npm install

💻 使用例

基本的な使用法

get_all_accounts

入力:

{}

出力（モック例）:

{
  "accounts": [
    {
      "id": "acct_001",
      "name": "Everyday Checking",
      "type": "checking",
      "currency": "USD",
      "balance": 2450.32
    }
  ]
}

get_account_details

入力:

{ "accountId": "acct_001" }

get_account_transactions

最小限の入力（デフォルトは直近30日間）:

{ "accountId": "acct_001" }

日付範囲を指定する場合:

{
  "accountId": "acct_001",
  "startDate": "2025-11-13",
  "endDate": "2025-12-13"
}

📚 ドキュメント

アーキテクチャ

このプロジェクトは、クリーンな抽象化レイヤーを通じて金融アカウントデータを提供するMCP (Model Context Protocol) サーバーを実装しています。

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                           │
│              (Claude, Cline, etc.)                      │
└────────────────────┬────────────────────────────────────┘
                     │ MCP Protocol
                     │ (stdio or HTTP)
┌────────────────────▼────────────────────────────────────┐
│                  server.ts                              │
│         (MCP Server Implementation)                     │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Tool Request Handler                            │   │
│  │  - ListToolsRequest                              │   │
│  │  - CallToolRequest                               │   │
│  └────────────────┬─────────────────────────────────┘   │
└───────────────────┼─────────────────────────────────────┘
                    │
┌───────────────────▼─────────────────────────────────────┐
│                  tools.ts                               │
│            (Tool Handlers & Schemas)                    │
│  - handleGetAllAccounts()                               │
│  - handleGetAccountDetails(accountId)                   │
│  - handleGetAccountTransactions(accountId, opts)        │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  data.ts                                │
│           (Data Abstraction Layer)                      │
│  - getAllAccounts()                                     │
│  - getAccountById(id)                                   │
│  - getTransactionsForAccount(id, opts)                  │
└───────┬───────────────────────────┬────────────────────┘
        │                           │
        │ DATA_SOURCE=mock          │ DATA_SOURCE=members1st
        ▼                           ▼
┌───────────────────┐    ┌──────────────────────────────┐
│  Mock Data        │    │     members1st/              │
│  (in-memory)      │    │  (HTTP API Integration)      │
│                   │    │  - client.ts (main API)      │
│  - 3 accounts     │    │  - http.ts (requests)        │
│  - 5 transactions │    │  - mappers.ts (transforms)   │
│                   │    │  - logging.ts, headers.ts,   │
│                   │    │    date-utils.ts (utilities) │
└───────────────────┘    └──────────────────────────────┘

主要コンポーネント

• server.ts: stdioとHTTPトランスポートを持つコアMCPサーバー
• tools.ts: MCPツールの定義とリクエストハンドラー
• data.ts: 複数のバックエンドをサポートするデータレイヤーの抽象化
• members1st/: 認証とキャッシュを持つMembers1st APIクライアントモジュール
  • client.ts: アカウントとトランザクションの取得を行うメインAPIクライアント
  • http.ts: リダイレクト処理を持つHTTPクライアントユーティリティ
  • logging.ts: ANSIカラーを使用したAPIリクエスト/レスポンスのロギング
  • headers.ts: ヘッダーの構築、サニタイズ、クッキー処理
  • date-utils.ts: 日付の解析、フォーマット、範囲の分割
  • mappers.ts: APIレスポンスからドメインタイプへのデータ変換
  • index.ts: 公開APIのエクスポート
• env.ts: dotenvを使用した環境変数のローダー

データフロー

1. MCPクライアントがツールリクエスト（例: get_all_accounts）を送信します。
2. サーバーがリクエストを検証し、適切なハンドラーにルーティングします。
3. ハンドラーがデータレイヤーの関数を呼び出します。
4. データレイヤーがDATA_SOURCEをチェックし、モックまたはMembers1stにルーティングします。
5. レスポンスが各レイヤーを通ってクライアントにJSON形式で返されます。

前提条件

• Node.js 18+（Node 20+が推奨）

環境設定 (.env)

このリポジトリは、dotenvを使ってローカルの.envファイルを自動的に読み込みます（src/env.tsを参照）。

• .env.exampleを.envにコピーし、値を入力してください。
• .envはコミットしないでください（.gitignoreに設定されています）。

スクリプト

開発とビルド

• npm run dev – stdioを通じてMCPサーバーを実行します（tsxを使ったTypeScript）
• npm run dev:http – HTTPを通じてMCPサーバーを実行します（tsxを使ったTypeScript）
• npm run build – dist/にコンパイルします
• npm start – stdioを通じてコンパイル済みのサーバーを実行します（dist/server.js）
• npm run start:http – HTTPを通じてコンパイル済みのサーバーを実行します（dist/server.js）

テスト

• npm test – すべてのテスト（単体テスト + 統合テスト）を実行します
• npm run test:unit – コンパイルされた単体テストをカバレッジレポート付きで実行します
• npm run test:unit:dev – 開発モードで単体テストを実行します（tsxを使ったTypeScript）
• npm run test:integration – 統合テストハーネスを実行します

ユーティリティ

• npm run get:account -- <accountId> – アカウント詳細ハンドラーを直接呼び出します（開発ヘルパー）

実行 (stdio)

これは、MCP対応クライアント内で設定するためのデフォルトのMCPトランスポート（stdio）です。 開発環境:

npm run dev

本番環境:

npm run build
npm start

実行 (HTTP)

このリポジトリは、MCP Streamable HTTPトランスポートをサポートしています。 開発環境:

npm run dev:http

本番環境:

npm run build
npm run start:http

デフォルト設定:

• 127.0.0.1:3000にバインドします
• MCPエンドポイントはGET/POST /mcpです

HTTP設定（環境変数）

• MCP_TRANSPORT: stdio（デフォルト）またはhttp
• HOST: バインドアドレス（デフォルト127.0.0.1）
• PORT: リスンポート（デフォルト3000）
• MCP_PATH: MCPエンドポイントのパス（デフォルト/mcp）
• MCP_ENABLE_JSON_RESPONSE: true/1に設定すると、SSEストリームを開始する代わりにJSONレスポンスを優先します
• MCP_STATELESS: true/1に設定すると、MCPセッションIDを無効にします（ステートレスモード）

例:

MCP_TRANSPORT=http HOST=0.0.0.0 PORT=8787 MCP_PATH=/mcp node dist/server.js

テスト

このプロジェクトには、Node.jsのネイティブテストランナーを使用した包括的な単体テストと統合テストが含まれています。

テストの実行

まずプロジェクトをビルドしてから、テストを実行します。

npm run build
npm test

これにより、以下が実行されます。

1. ユーティリティモジュール、データレイヤー、およびツールハンドラーのコードカバレッジ付きの単体テスト
2. 完全なツールワークフローをテストする統合テスト

テストコマンド

• 全テスト: npm test - カバレッジ付きの単体テスト + 統合テストを実行します
• 単体テストのみ: npm run test:unit - コンパイルされたテストをカバレッジレポート付きで実行します
• 開発モード: npm run test:unit:dev - コンパイルせずにテストを実行します（高速な反復）
• 統合テスト: npm run test:integration - エンドツーエンドのワークフローテスト

テストカバレッジ

現在のテストカバレッジ（最終実行時）:

• 全体: 行カバレッジ99.46%、ブランチカバレッジ94.77%
• 112個の単体テストがユーティリティ関数、データレイヤー、およびツールハンドラーをカバーしています
• テストはデフォルトでモックデータを使用して、一貫したオフラインテストを行います

クイックバリデーション

モックデータを使用したオフライン/安全な健全性チェックを行うには:

export DATA_SOURCE=mock
npm run build
npm test

MCPクライアントの設定例

MCPクライアントがコマンドを通じてMCPサーバーを起動できる場合:

• コマンド: node
• 引数: dist/server.js
• 作業ディレクトリ: リポジトリのルート

例（疑似設定）:

{
  "mcpServers": {
    "m1-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/m1-mcp/dist/server.js"]
    }
  }
}

データソース

モック（デフォルト）

src/data.ts内のメモリ内データセットを使用します。

Members 1st（オプション）

Members 1stベースのフェッチャーに切り替えるには:

export DATA_SOURCE=members1st

重要事項:

• クッキーやトークンをこのリポジトリに貼り付けたり、コミットしたりしないでください。
• シークレットは環境変数を通じてのみ提供してください。

Members 1stの環境変数

• DATA_SOURCE: mock（デフォルト）またはmembers1st
• MEMBERS1ST_ACCOUNTS_URL: デフォルトはhttps://myonline.members1st.org/api/v1/account
• MEMBERS1ST_TRANSACTIONS_URL_BASE: デフォルトはhttps://myonline.members1st.org/api/v1/Transactions
• MEMBERS1ST_ORIGIN: デフォルトはhttps://myonline.members1st.org（Origin/Refererヘッダーに使用）
• MEMBERS1ST_COOKIE: クッキー値または完全なクッキーヘッダー値（実装では裸の値をM1Online=<value>としてラップします）
• MEMBERS1ST_COOKIE_FILE: クッキー値を含むファイルへのパス（MEMBERS1ST_COOKIEの代替、長い値の場合は便利）
• MEMBERS1ST_AUTHORIZATION: Authorizationヘッダーの値（例: Bearer ...）（適用可能な場合）
• MEMBERS1ST_HEADERS_JSON: 送信リクエストに追加する追加ヘッダーのオプションJSONオブジェクト文字列
• MEMBERS1ST_CACHE_TTL_MS: アカウントフェッチのキャッシュ期間（デフォルト30000）
• MEMBERS1ST_DISABLE_CACHE: true/1に設定すると、アカウントキャッシュを無効にします

APIリクエストのロギング

APIリクエストは、デフォルトで（本番モードでない場合）stderrに色付きでログ出力されます。これはデバッグと開発に役立ちます。

• LOG_API_REQUESTS: true/1に設定するとAPIリクエストのロギングを有効にし、false/0に設定すると無効にします（デフォルト: NODE_ENV=productionでない限り有効）
• LOG_API_RESPONSES: true/1に設定するとAPIレスポンスボディのロギングを有効にします（デフォルト: false）
• NODE_ENV: productionに設定すると、デフォルトでAPIリクエストのロギングを無効にします

ログに記録される情報には以下が含まれます:

• リクエストメソッドとURLパス
• クエリパラメータ（色付き）
• リクエストヘッダー（CookieやAuthorizationなどの機密値は隠されます）
• レスポンスステータスコードとメッセージ（LOG_API_RESPONSESが有効な場合）
• レスポンスボディのプレビュー（LOG_API_RESPONSESが有効な場合、500文字に切り詰められます）

使用例

オプション1: 直接クッキー値を指定する

export DATA_SOURCE=members1st
export MEMBERS1ST_COOKIE='your_cookie_or_cookie_header_here'

npm run dev:http

オプション2: ファイルからクッキーを読み込む（推奨）

# クッキーファイルを作成する
echo 'your_cookie_value_here' > .members1st-cookie

# ファイルを使用するように設定する
export DATA_SOURCE=members1st
export MEMBERS1ST_COOKIE_FILE=.members1st-cookie

npm run dev:http

クッキーファイルを使用する方法は、以下の理由から便利です:

• スクリプトを変更することなくクッキーを簡単に更新できます。
• ファイルはデフォルトで.gitignoreに設定されているため、セキュリティが確保されます。
• MCPクライアントの設定とうまく連携します（examples/ディレクトリを参照）

CI/CDと自動化

このプロジェクトは、自動化されたワークフローを持つ最新のDevOpsプラクティスを採用しています。

GitHub Actionsワークフロー

• CIパイプライン (.github/workflows/ci.yml):

  • Node.js 18.x、20.x、および22.xでビルドとテストを行います。
  • セキュリティ監査を実行します。
  • TypeScriptのコンパイルを検証します。
  • ビルドアーティファクトをアップロードします。

• リリースパイプライン (.github/workflows/release.yml):

  • バージョンタグ（例: v1.0.0）で自動的にリリースを行います。
  • 変更履歴を生成します。
  • アーティファクト付きのGitHubリリースを作成します。
  • npm公開をサポートします（パッケージが公開されている場合）。

• セキュリティスキャン (.github/workflows/codeql.yml):

  • 脆弱性のためのCodeQL分析を行います。
  • 毎週のスキャンをスケジュールします。
  • 問題に対するセキュリティアラートを提供します。

依存関係管理

• Dependabot: 依存関係の更新のためのPRを自動的に作成します。
• npm audit: 各CIビルドで実行されます。
• グループ化された更新: マイナーおよびパッチ更新がまとめて行われます。

GitHub Copilotアセット

.github/にAI支援開発リソースが用意されています。

• copilot-instructions.md: GitHub Copilotのためのプロジェクト固有のガイドライン
• agents/: さまざまな開発タスクのための特殊な指示
  • code-review.md: コードレビューのガイドラインとチェックリスト
  • testing.md: テスト戦略とパターン
  • feature-development.md: 機能実装ガイド
  • bug-fixing.md: 体系的なバグ修正ワークフロー
  • security.md: セキュリティのベストプラクティスと脆弱性対応

コントリビューション

コントリビューションは大歓迎です！詳細なガイドラインについては、CONTRIBUTING.mdを参照してください。

• 開発環境のセットアップとワークフロー
• プロジェクトの構造とアーキテクチャ
• テスト要件
• コードスタイルとベストプラクティス
• プルリクエストの提出方法
• CI/CDパイプラインの詳細

バグレポートや機能リクエストについては、GitHubでイシューを開いてください。