Skip to main content
Glama

MCP Tool Starter Kit

by He110te4m

MCP 工具入门套件 (MCP Tool Starter Kit)

这是一个功能完备、开箱即用的 TypeScript 项目模板,旨在帮助开发者快速、规范地启动任何新的 MCP (Model Context Protocol) 工具项目。

它集成了业界最佳的工程化实践,涵盖了从代码规范、测试、调试到自动化发布的全流程。

🚀 如何使用此模板

  1. 创建新仓库: 在 GitHub 或 GitLab 上,使用此模板创建一个新的代码仓库。
  2. 克隆新仓库到本地:
    git clone [你的新仓库地址] cd [你的新项目目录]
  3. 修改 package.json:
    • name 字段修改为你自己的包名 (例如: "@your-scope/my-new-tool")。
    • bin 字段中的命令名修改为你的工具名 (例如: "my-new-tool": "./dist/index.js")。
    • 按需修改 author, description 等字段。
  4. 安装依赖:
    pnpm install
  5. 开始开发: 你现在可以开始在 src/tools/ 目录下创建你自己的工具了!

✨ 特性

  • Node.js 版本: 要求 Node.js 20 或更高版本。
  • 现代化的模块系统: 使用 TypeScript,并配置为标准的 ES Module ("type": "module") 项目。
  • 强大的构建工具: 使用 tsup 进行快速、高效的构建,并已通过 tsup.config.ts 进行配置。
  • 严格的代码规范:
    • 使用 ESLint 进行静态代码分析。
    • 使用 Prettier 进行代码格式化。
    • 通过 eslint-config-prettier 完美解决两者冲突。
    • 使用 husky, lint-staged, 和 commitlint 在代码提交前自动检查、格式化并校验提交信息,保证代码库的整洁统一和 Git 历史的规范性。
  • 完备的测试框架:
    • 使用 Vitest 作为现代化、极速的单元测试框架。
    • 集成 msw (Mock Service Worker) 用于模拟 API 请求,编写高保真度的单元测试。
  • 专业的命令行接口 (CLI):
    • 使用 yargs 构建强大且可扩展的 CLI。
    • 内置 --verbose (调试模式), --help, --version 等标准参数。
  • 自动化的版本与发布流程:
    • 使用 bumpp 进行交互式的版本管理。
    • 遵循 Conventional Commits 规范。
    • 通过 pnpm release 命令一键完成版本提升、生成 Git 标签等操作。
  • 持续集成与部署 (CI/CD):
    • 提供 GitHub Actions (ci.yml) 和 GitLab CI (.gitlab-ci.yml) 的标准配置文件。
    • CI 流程包括自动安装依赖、运行代码检查、测试和构建。
    • CD 流程配置为在创建新的 Git 标签时自动发布包。
  • 清晰的项目结构: 采用关注点分离原则,将 CLI、服务器逻辑、工具等模块清晰地划分到不同文件中。

📂 项目结构

. ├── .github/workflows/ # GitHub Actions CI/CD 配置 ├── .husky/ # Git 钩子 ├── dist/ # 构建产物 ├── src/ # 源码 │ ├── tools/ # MCP Tools 目录 │ │ └── example.tool.ts # 示例 Tool │ ├── cli.ts # 命令行接口定义 │ ├── server.ts # MCP 服务器逻辑 │ └── index.ts # 主入口 ├── tests/ # 测试文件 │ ├── mocks/ # MSW mock 配置 │ └── example.test.ts # 示例测试 ├── .eslintrc.cjs # ESLint 配置 ├── .gitignore ├── .gitlab-ci.yml # GitLab CI/CD 配置 ├── commitlint.config.cjs # Commitlint 配置 ├── package.json ├── pnpm-lock.yaml ├── tsconfig.json ├── tsup.config.ts # tsup 构建配置 └── vitest.config.ts # Vitest 测试配置

🚀 可用脚本

  • pnpm start: 使用 tsx 启动服务。
  • pnpm start:debug: 以调试模式启动服务,会打印详细的请求日志。
  • pnpm build: 使用 tsup 构建项目。
  • pnpm test: 使用 Vitest 运行所有测试。
  • pnpm lint: 使用 ESLint 检查整个项目的代码规范。
  • pnpm release: 使用 bumpp 交互式地提升版本号,创建 Git 标签,并自动发布到 npm。
  • pnpm inspect: 使用官方的 @modelcontextprotocol/inspector 工具进行调试。

🛠️ 开发流程

1. 创建一个新的 Tool

  1. src/tools/ 目录下创建一个新的 *.tool.ts 文件。
  2. 参考 src/tools/example.tool.ts 的结构,定义一个新的 Tool 对象和对应的 Handler 函数。
  3. src/server.ts 中导入新的 Tool 和 Handler,并在请求处理逻辑中注册它。

2. 编写测试

  1. tests/ 目录下创建一个新的 *.test.ts 文件。
  2. 参考 tests/example.test.ts,使用 Vitest 编写测试用例。
  3. 如果你的 Tool 涉及到外部 API 请求,可以在 tests/mocks/handlers.ts 中使用 msw 添加对应的 mock 处理器。

3. 本地调试

如果你想在本地像全局命令一样运行和调试你的工具,而不是每次都通过 pnpm start,你可以遵循以下步骤:

  1. 构建项目: 首先,你需要编译你的 TypeScript 源码,生成 dist 目录。
    pnpm run build
  2. 链接包: 使用 npm link 命令在你的系统中创建一个全局符号链接,指向你当前的项目。这会让你能直接运行在 package.jsonbin 字段中定义的命令。
    npm link
  3. 运行命令: 现在你可以在任何终端窗口中直接运行你的命令了。
    # 假设你的命令是 auto-complete-document auto-complete-document --help

注意: 每次你修改了 src 目录下的代码,都需要重新运行 pnpm run build 来确保你的全局命令执行的是最新的代码。

4. 提交代码

当你提交代码时 (git commit),husky 会自动触发两个钩子:

  • commit-msg: 使用 commitlint 校验你的提交信息是否符合 Conventional Commits 规范。不规范的提交将被拒绝
  • pre-commit: 使用 lint-staged 对你本次修改的文件运行 ESLint 和 Prettier,以确保代码质量。

请确保你的 Commit Message 遵循 Conventional Commits 规范,例如:

  • feat: add new feature
  • fix: resolve a bug
  • docs: update documentation

这是自动化版本管理和 Changelog 生成的基础。

📦 发布流程

当你准备好发布一个新版本时,只需简单地运行:

pnpm release

bumpp 会启动一个交互式流程,引导你选择新的版本号。确认后,它会自动完成以下所有工作:

  1. 更新 package.json 中的版本号。
  2. 提交版本变更。
  3. 创建一个以新版本号命名的 Git 标签 (e.g., v1.2.3)。
  4. 将所有变更和标签推送到远程仓库。
  5. 运行 pnpm publish 将包发布到 npm。

之后,GitLab CI (或 GitHub Actions) 会检测到新的标签,并根据 .gitlab-ci.yml 中的配置执行自动化发布流程。

Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

A feature-complete TypeScript project template for rapidly developing Model Context Protocol tools with integrated best practices for code quality, testing, and automated deployment.

  1. 🚀 如何使用此模板
    1. ✨ 特性
      1. 📂 项目结构
        1. 🚀 可用脚本
          1. 🛠️ 开发流程
            1. 1. 创建一个新的 Tool
            2. 2. 编写测试
            3. 3. 本地调试
            4. 4. 提交代码
          2. 📦 发布流程

            Related MCP Servers

            • A
              security
              A
              license
              A
              quality
              A production-ready template for creating Model Context Protocol servers with TypeScript, providing tools for efficient testing, development, and deployment.
              Last updated -
              1
              477
              32
              JavaScript
              MIT License
            • A
              security
              F
              license
              A
              quality
              A TypeScript-based template for developing Model Context Protocol servers with features like dependency injection and service-based architecture, facilitating the creation and integration of custom data processing tools.
              Last updated -
              1
              9
              4
              TypeScript
            • A
              security
              A
              license
              A
              quality
              A TypeScript-based template for building Model Context Protocol servers, featuring fast testing, automated version management, and a clean structure for MCP tool implementations.
              Last updated -
              1
              477
              4
              TypeScript
              MIT License
            • -
              security
              F
              license
              -
              quality
              A template repository for building Model Context Protocol (MCP) servers with TypeScript, featuring full TypeScript support, testing setup, CI/CD pipelines, and modular architecture for easy extension.
              Last updated -
              0
              TypeScript

            View all related MCP servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/He110te4m/mcp-starter'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server