m1 MCP

m1 mcp

最小的Node.js（TypeScript）MCP服务器，它公开了三个用于帐户数据的工具。

默认情况下，它提供一个小的内存模拟数据集。您可以选择通过环境变量切换到“成员优先”HTTP支持的数据源。

m1 mcp新手？ 看 QUICKSTART.md 5分钟入门指南！

目录

• 建筑
• 工具
• 先决条件
• 安装
• 配置
• 用法
• 跑步
• 测试
• 客户端配置
• 工具示例
• 数据源
• 贡献

建筑

该项目实现了一个MCP（模型上下文协议）服务器，该服务器通过一个干净的抽象层提供金融账户数据：

┌─────────────────────────────────────────────────────────┐
│                    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：支持多个后端的数据层抽象
• 成员1st/：具有身份验证和缓存的第一个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 以及前往模拟或会员名单的路线
5. 响应以JSON格式通过层流回到客户端

工具

• get_all_accounts → 回报 { accounts: Account[] }
• get_account_details → input { accountId: string }，返回 { account } 或 { error }
• get_account_transactions → 输入：

- 必修的： accountId: string - 可选过滤器： startDate, endDate （YYYY-MM-DD，默认为过去30天） - 注意：超过180天的日期范围会自动分块和合并

注意：工具结果以JSON编码返回到MCP中 text 内容。

前提条件

• Node.js 18+（建议使用Node 20+）

安装

npm install

环境（.env）

此repo自动加载本地 .env 文件通过 dotenv （参见 src/env.ts).

• 复制 .env.example 到 .env 并填写数值。
• 不要承诺 .env （这是理所当然的）。

脚本

开发和建设

• npm run dev –通过stdio运行MCP服务器（通过TypeScript tsx)
• npm run dev:http –通过HTTP运行MCP服务器（TypeScript通过 tsx)
• 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 –在开发模式下运行单元测试（TypeScript通过 tsx)
• npm run test:integration –运行集成测试工具

公用事业

• npm run get:account -- –直接调用帐户详细信息处理程序（dev-helper）

运行（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
• Args： dist/server.js
• 工作目录：repo根目录

示例（伪配置）：

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

工具I/O示例

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天的日期范围，请求会自动拆分为多个块并合并结果。

数据源

模拟（默认）

在中使用内存中的数据集 src/data.ts.

成员1（可选）

切换到会员优先支持的fetchers：

export DATA_SOURCE=members1st

重要提示：

• 不要将Cookie/令牌粘贴到此仓库中或提交它们。
• 仅通过环境变量提供机密。

成员1环境变量

• 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=)
• 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和授权等敏感值）
• 响应状态代码和消息（当 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（推荐）

# Create a cookie file
echo 'your_cookie_value_here' > .members1st-cookie

# Configure to use the file
export DATA_SOURCE=members1st
export MEMBERS1ST_COOKIE_FILE=.members1st-cookie

npm run dev:http

cookie文件方法更方便，因为：

• 您可以轻松更新cookie，而无需更改脚本
• 默认情况下，为了安全起见，该文件被忽略
• 它与MCP客户端配置配合良好（请参阅 examples/ 目录）

CI/CD与自动化

该项目使用现代DevOps实践和自动化工作流程：

GitHub操作工作流

• 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分析 - 计划每周扫描 - 针对问题的安全警报

依赖管理

• 依赖机器人：自动为依赖关系更新创建PR
• npm审计：在每个CI构建上运行
• 分组更新：小更新和补丁更新组合在一起

GitHub复制品资产

人工智能辅助开发资源可用 .github/:

• 副驾驶指令.md：GitHub Copilot的项目特定指导
• 代理商/：针对不同开发任务的专门说明

- code-review.md：代码审查指南和清单 - testing.md：测试策略和模式 - feature-development.md：功能实现指南 - bug-fixing.md：系统的错误修复工作流程 - security.md：安全最佳做法和漏洞处理

贡献

欢迎投稿！请看 贡献.md 有关以下内容的详细指南：

• 开发设置和工作流程
• 项目结构和架构
• 测试要求
• 代码风格和最佳实践
• 如何提交pull请求
• CI/CD管道详细信息

有关错误报告和功能请求，请在GitHub上打开问题。