M1 MCP

🚀 m1-mcp

m1-mcp 是一個極簡的 Node.js（TypeScript）MCP 服務器，它提供了三個用於處理賬戶數據的工具。默認情況下，它使用一個小型的內存模擬數據集。你也可以通過環境變量選擇切換到基於 HTTP 的“Members 1st”數據源。

初次使用 m1-mcp？ 請查看 QUICKSTART.md，獲取 5 分鐘快速入門指南！

🚀 快速開始

本項目實現了一個 MCP（模型上下文協議）服務器，通過一個簡潔的抽象層提供金融賬戶數據。如果你是初次使用，可查看 QUICKSTART.md 進行 5 分鐘快速入門。

✨ 主要特性

• 提供三個用於處理賬戶數據的工具，分別為 get_all_accounts、get_account_details 和 get_account_transactions。
• 默認使用內存模擬數據集，也可通過環境變量切換到“Members 1st”數據源。
• 支持 stdio 和 HTTP 兩種傳輸方式。
• 包含全面的單元測試和集成測試。
• 採用現代 DevOps 實踐，具備自動化工作流程。

📦 安裝指南

前提條件

• Node.js 18+（推薦 Node 20+）

安裝命令

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"
}

如果日期範圍超過 180 天，請求將自動拆分為多個塊，併合並結果。

高級用法

使用“Members 1st”數據源

export DATA_SOURCE=members1st

重要提示：

• 不要將 cookie/token 粘貼到本倉庫中或提交。
• 僅通過環境變量提供機密信息。

“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: cookie 值或完整的 cookie 頭值（實現會將裸值包裝為 M1Online=<value>）
• MEMBERS1ST_COOKIE_FILE: 包含 cookie 值的文件路徑（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：直接使用 cookie 值

export DATA_SOURCE=members1st
export MEMBERS1ST_COOKIE='your_cookie_or_cookie_header_here'

npm run dev:http

選項 2：從文件中讀取 cookie（推薦）

# 創建一個 cookie 文件
echo 'your_cookie_value_here' > .members1st-cookie

# 配置使用該文件
export DATA_SOURCE=members1st
export MEMBERS1ST_COOKIE_FILE=.members1st-cookie

npm run dev:http

使用 cookie 文件的方法更方便，原因如下：

• 你可以輕鬆更新 cookie，而無需更改腳本。
• 默認情況下，該文件會被 git 忽略，以確保安全。
• 它與 MCP 客戶端配置配合良好（請參閱 examples/ 目錄）。

📚 詳細文檔

架構

┌─────────────────────────────────────────────────────────┐
│                    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：核心 MCP 服務器，支持 stdio 和 HTTP 傳輸。
• tools.ts：MCP 工具定義和請求處理程序。
• data.ts：支持多個後端的數據層抽象。
• members1st/：Members1st API 客戶端模塊，具有身份驗證和緩存功能。
  • client.ts：主要 API 客戶端，用於獲取賬戶和交易數據。
  • http.ts：具有重定向處理功能的 HTTP 客戶端實用工具。
  • logging.ts：使用 ANSI 顏色記錄 API 請求/響應。
  • headers.ts：頭構建、清理和 cookie 處理。
  • 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 形式返回給客戶端。

工具

• get_all_accounts → 返回 { accounts: Account[] }
• get_account_details → 輸入 { accountId: string }，返回 { account } 或 { error }
• get_account_transactions → 輸入：
  • 必需：accountId: string
  • 可選過濾器：startDate, endDate（YYYY-MM-DD，默認值為最近 30 天）
  • 注意：超過 180 天的日期範圍會自動分塊併合並。

注意：工具結果以 JSON 格式編碼為 MCP text 內容返回。

環境配置（.env）

本倉庫通過 dotenv 自動加載本地 .env 文件（請參閱 src/env.ts）。

• 將 .env.example 複製到 .env 並填寫值。
• 不要提交 .env 文件（它已被 git 忽略）。

腳本命令

開發和構建

• 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 可流式 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 以優先使用 JSON 響應，而不是啟動 SSE 流
• 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"]
    }
  }
}

持續集成/持續部署和自動化

本項目採用現代 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：系統的 bug 修復工作流程。
  • security.md：安全最佳實踐和漏洞處理。

📄 許可證

文檔中未提及許可證相關信息。

🔧 技術細節

數據層抽象

數據層通過 data.ts 文件實現抽象，支持多種數據源。根據 DATA_SOURCE 環境變量的值，數據層會選擇使用模擬數據或連接到 Members1st API。這種抽象設計使得代碼具有良好的可擴展性，方便後續添加新的數據源。

API 請求處理

在 server.ts 中，實現了對 MCP 協議的支持，處理來自客戶端的工具請求。對於不同的工具請求，如 get_all_accounts、get_account_details 和 get_account_transactions，會調用相應的處理函數。這些處理函數在 tools.ts 中定義，它們會根據請求參數調用數據層的函數來獲取數據，並將結果以 JSON 格式返回給客戶端。

緩存機制

在使用 Members1st 數據源時，通過 MEMBERS1ST_CACHE_TTL_MS 環境變量可以配置賬戶數據的緩存時間，默認緩存時間為 30000 毫秒。通過 MEMBERS1ST_DISABLE_CACHE 環境變量可以禁用緩存。緩存機制的實現有助於減少對 Members1st API 的請求次數，提高系統性能。

日誌記錄

為了方便調試和開發，項目實現了 API 請求和響應的日誌記錄功能。通過設置 LOG_API_REQUESTS 和 LOG_API_RESPONSES 環境變量，可以控制是否啟用請求和響應的日誌記錄。在生產環境中，可以通過設置 NODE_ENV=production 來默認禁用請求日誌記錄。日誌記錄使用 ANSI 顏色編碼，使得日誌信息更加清晰易讀。

測試框架

項目使用 Node.js 原生測試運行器進行單元測試和集成測試。單元測試覆蓋了實用函數、數據層和工具處理程序，確保代碼的正確性。集成測試則模擬了完整的工具工作流程，驗證系統的整體功能。通過測試覆蓋率報告，可以瞭解代碼的測試覆蓋情況，及時發現未測試的代碼部分。

持續集成和部署

項目使用 GitHub Actions 實現了自動化的 CI/CD 流程。CI 管道會在不同版本的 Node.js 上進行構建和測試，同時運行安全審計和驗證 TypeScript 編譯。發佈管道會在版本標籤上自動發佈新版本，並生成變更日誌和創建 GitHub 發佈。安全掃描管道使用 CodeQL 進行漏洞分析，定期掃描代碼併發出安全警報。這些自動化流程確保了代碼的質量和安全性，提高了開發效率。

🤝 貢獻說明

歡迎貢獻代碼！請查看 CONTRIBUTING.md 獲取詳細指南，內容包括：

• 開發環境設置和工作流程
• 項目結構和架構
• 測試要求
• 代碼風格和最佳實踐
• 如何提交拉取請求
• CI/CD 管道詳情

如果要報告 bug 或提出功能請求，請在 GitHub 上創建一個 issue。