boilerplate-mcp-tool

v1.0.7

Published

13 days ago

CX Boilerplate MCP Tool cli

0High
0Medium
0Low

xiong.pan

cx mcp tool cli

cx-mcp-tool

Boilerplate Mcp Tool CLI —— 基于 Model Context Protocol (MCP) 的命令行工具开发模板。使用 OAuth2 进行 Atlassian (Jira, Confluence) 和 GitHub 认证。使用 Bearer Token，通过 REST API 访问相关服务。

前提

需要先在 Atlassian 和 GitHub 分别注册 OAuth 应用，获取 Client ID 和 Client Secret。

Atlassian developer: https://developer.atlassian.com/console/myapps/
GitHub developer: https://github.com/settings/developers

安装

  # 通过 npm 全局安装（假设已经成功推送到了 JFrog 部署）
  npm install -g boilerplate-mcp-tool --registry=https://artifactory.cathaypacific.com/artifactory/api/npm/npm-common/

  # 会弹出浏览器进行 OAuth 登录，然后在终端显示登录成功信息
  boilerplate-mcp-tool login

  # 强制登录，忽略已有登录状态。默认已登录过就不回弹出浏览器OAuth授权
  boilerplate-mcp-tool login -f

  # 清空登录信息
  boilerplate-mcp-tool login -c

  # 清空全部信息
  boilerplate-mcp-tool clear -f

Basic 登录

需要到 GitHub 和 Atlassian 分别创建 Personal Access Token (PAT)，并赋予相应权限，然后在登录时输入用户名和 PAT 进行登录。

Atlassian: https://id.atlassian.com/manage-profile/security/api-tokens
GitHub: https://github.com/settings/tokens

  # 使用 Basic 方式登录（适用于无法使用 OAuth 的场景）
  boilerplate-mcp-tool login -b

注意：Basic Token 与 OAuth Token 不能混用，登录时会覆盖之前的登录状态。API 也不兼容。根据你的程序版本选择登录模式。

安装

  # 自动配置一个 MCP Server 到 VSCode 的 mcp.json 配置文件中
  boilerplate-mcp-tool install

  # 如果 install 时报错，config 可以列出配置信息，手动添加到 mcp.json
  boilerplate-mcp-tool config

mcp.json 示例

{
  "servers": {
    "boilerplateMcpTool": {
      "command": "node",
      "args": ["/Users/mango/github/boilerplate-mcp-tool/dist/app.js"]
    }
  },
  "inputs": []
}

Tool & Prompt 列表

Tools
- #cx_fetch_atlassian_attachment
- #cx_fetch_github_repository_code
- #cx_fetch_github_repository_info
- #cx_fetch_jira_issue
- #cx_health_check
- #cx_my_jira_issue
- #cx_search_confluence
- #cx_search_github
Prompts
- /my_todo_list

问题

Atlassian OAuth Token 是 Bearer Token，Jira 暂未发现问题，Atlassian 权限收紧 Confluence 无法获取正文内容，但能进行搜索
- 暂时未找到解决方案，也许存在其他的 REST API，但未找到
Atlassian OAuth Token 有效期只有一个小时，需要定时刷新
- 这个问题可以通过 refresh token 解决
GitHub OAuth Token 是 Bearer Token，无法获取私有仓库内容，需要管理员授权
- 需要联系组织管理员，请他们在组织设置的“第三方访问”或“OAuth应用访问限制”里允许你要用的应用。
- 管理员进入：组织 Settings → OAuth App Access settings → 允许相关App 之后你就可以用相应的应用访问组织内的仓库和数据了。

简介

本项目为 CLI 工具模板，基于 @modelcontextprotocol/sdk 实现 MCP Tool/Prompt 注册与调用，适用于 AI 工具链、自动化脚本、DevOps 工具等场景。

项目结构

├── src/
│   ├── app.ts                # CLI 主入口，注册 MCP Tool/Prompt
│   ├── modules/
│   │   ├── tools/            # MCP Tool 实现目录
│   │   └── prompts/          # MCP Prompt 实现目录
│   ├── config/               # 配置（如 logger、axios 等）
│   ├── utils/                # 通用工具函数
│   └── types/                # 类型定义
├── test/                     # 单元测试
├── package.json
├── tsconfig.json
└── ...

快速开始

安装依赖

npm install

构建项目

npm run build

运行 CLI 工具（开发模式）

npm run dev -- [参数]
# 或
npx ts-node src/app.ts -- [参数]

MCP Tool/Prompt 注册机制

所有 MCP Tool/Prompt 需在 src/modules/tools/ 或 src/modules/prompts/ 下实现，并在 src/app.ts 中注册：

import healthCheck from './modules/tools/healthCheck';
import fetchJiraIssue from './modules/tools/fetchJiraIssue';
// ...

export const getMcpTools = (server, headers) => [
  healthCheck(server, headers),
  fetchJiraIssue(server, headers),
  // ...更多工具
];

export const getMcpPrompts = (server, headers) => [myTodoList(server, headers)];

每个 Tool/Prompt 需导出标准结构，详见 src/app.ts。

开发与测试

本地开发

# 启动开发（支持热重载）
npm run dev -- [参数]

构建

npm run build

单元测试

npm run test

测试代码位于 test/ 目录，结构与 src/ 保持一致，文件以 .test.ts 结尾。

代码风格与质量

ESLint 规则见 eslint.config.js，格式化用 Prettier。
提交前自动执行 lint/test（Husky + lint-staged）。
推荐在 VSCode 安装 ESLint/Prettier 插件。

常用命令：

npm run lint      # 代码检查
npm run lint:fix  # 自动修复

常用工具函数

PGP 加解密：src/utils/pgp.utils.ts
MFT 文件传输：src/utils/mft.utils.ts
OAuth2/JWT：src/utils/oauth.utils.ts、src/utils/jwt.utils.ts
Hash/签名：src/utils/hash.utils.ts
数据脱敏：src/utils/mask.utils.ts

详见各工具源码与注释。

CI/CD 与部署

构建产物位于 dist/，入口为 dist/bin/main.js。
可通过 npx boilerplate-mcp-tool 或 node dist/bin/main.js 调用。
推荐在 CI 中执行：

npm ci
npm run build
npm run test

Husky/Lint/Jest 已集成，保障代码质量。

其他

如需自定义 Copilot 代码风格，可编辑 .github-template/copilot-instructions.md。
详细 MCP 协议/SDK 用法请参考 @modelcontextprotocol/sdk 文档。