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。