MCP Server Boilerplate 39k

🚀 MCP 服務器骨架代碼

本項目提供了模型上下文協議（MCP）服務器的簡單實現，可作為構建自定義工具的基礎模板，幫助開發者快速搭建自己的 MCP 服務器並擴展功能。

🚀 快速開始

按照以下步驟，您可以快速搭建並啟動 MCP 服務器：

1. 克隆代碼倉庫到本地。
2. 安裝所需的依賴包。
3. 根據需求修改 .env 文件中的配置。
4. 啟動服務器並測試功能。

✨ 主要特性

工具管理

通過 src/index.ts 文件能夠定義和註冊自定義工具。默認實現包含以下工具：

• echo：簡單回顯工具。
• random-string：生成隨機字符串。
• math-calculate：執行數學計算。

環境配置

項目支持通過環境變量進行配置，主要涉及以下方面：

• 端口配置：修改 .env 文件中的 PORT 變量，可調整服務器監聽的端口。
• 日誌級別：通過設置 .env 中的 NODE_ENV 和 LOG_LEVEL，能控制日誌輸出的詳細程度。

📦 安裝指南

步驟 1: 克隆代碼倉庫

在終端中運行以下命令以克隆此項目：

git clone git@github.com:yourusername/mcp-server.git
cd mcp-server

步驟 2: 安裝依賴項

使用 npm 或 yarn 安裝所需的包：

• npm：

npm install

• yarn：

yarn install

步驟 3: 啟動服務器

安裝完成後，啟動服務器：

npm run dev

或

yarn dev

💻 使用示例

基礎用法

在 src/index.ts 文件中，按照以下模式添加新的工具：

/**
 * 定義工具的模式
 * name 和 description 決定了工具的選擇方式
 * handler 返回 CallToolResult（異步情況下返回 Promise）
 */
server.tool(
  "新工具名稱",
  "新工具的功能描述",
  {參數名: z.類型().describe("參數說明")},
  ({參數名}) => ({內容: [{type: "text", text: 結果}]}),
);

📚 詳細文檔

項目結構

mcp-server/
├── .env                # 環境變量配置文件
├── .gitignore          # Git 倉庫忽略規則
├── package.json        # 包依賴和腳本配置
├── tsconfig.json       # TypeScript 編譯器配置
├── src/
│   ├── index.ts       # 應用入口點
│   └── types/         # 類型定義文件夾（持續更新中）
└── README.md           # 項目說明文檔

目錄結構說明

• src/：項目的核心源碼目錄。
  • index.ts：應用啟動入口文件。
  • types/：類型定義文件夾，用於統一管理接口和數據結構。
• .env：環境變量配置文件，包含運行時所需的各種參數。
• package.json：項目依賴管理和腳本執行的配置文件。

主要依賴包

• @modelcontextprotocol/sdk: ^1.9.0 - MCP 服務器實現所需的 SDK
• zod: ^3.24.2 - 用於類型驗證和模式定義的庫

開發工具配置

使用 Biome 進行代碼質量管理

Biome 是一個高效的 JavaScript 和 TypeScript 語言服務器，支持代碼檢查、格式化等功能。項目中通過 biome.json 文件進行了定製化的配置。

可用命令

# 檢查代碼質量
npm run lint

# 自動修復代碼問題
npm run lint:fix

# 格式化代碼
npm run format

# 自動調整格式
npm run format:fix

參考文章

簡易的自定義MCP服務器的搭建方法 - Zenn 中的文章提供了詳細的指導，本文檔是對該文章內容的補充說明。

前提條件

• Node.js：需要安裝版本16.0或更高。
• npm 或 yarn ：用於包管理。
• Git （可選）：如果使用 Git 進行代碼倉庫管理。

🔧 技術細節

環境變量配置

項目支持通過環境變量進行配置，主要涉及端口配置和日誌級別控制。修改 .env 文件中的 PORT 變量可調整服務器監聽的端口；通過設置 .env 中的 NODE_ENV 和 LOG_LEVEL 能控制日誌輸出的詳細程度。

工具定義與註冊

通過 src/index.ts 文件可以定義和註冊自定義工具。在該文件中，使用 server.tool 方法來定義工具，其中 name 和 description 決定了工具的選擇方式，handler 返回 CallToolResult（異步情況下返回 Promise）。