BMI MCP Server

一个基于 TypeScript 构建的自定义 MCP (Model Context Protocol) 服务器，提供 BMI 计算、体重单位转换和健康建议功能。

本项目是 MCP Server 开发的完整教程示例。

📋 目录

• 功能特性
• 快速开始
• 项目结构
• API 参考
• 完整教程：从零构建 MCP Server
• 发布到 MCP Registry
• 最佳实践
• 官方资源

功能特性

Tools (工具)

Resources (资源)

Prompts (提示)

快速开始

环境要求

• Node.js >= 18.0.0
• npm 或 yarn

安装与运行

# 1. 克隆项目
git clone https://github.com/opencode/bmi-mcp-server.git
cd bmi-mcp-server

# 2. 安装依赖
npm install

# 3. 直接运行（stdio 模式，用于 opencode 等客户端）
npx tsx src/server.ts

接入 OpenCode

在 OpenCode 配置文件中添加 MCP Server：

全局配置 (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-opencode"],
  "mcpServers": {
    "bmi-mcp-server": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/bmi-mcp-server/src/server.ts"
      ],
      "type": "stdio"
    }
  }
}

项目配置 (.opencode.json in project root):

{
  "mcpServers": {
    "bmi-mcp-server": {
      "command": "npx",
      "args": ["tsx", "./src/server.ts"],
      "type": "stdio"
    }
  }
}

配置完成后，重启 OpenCode 即可使用 BMI 计算工具。

项目结构

bmi-mcp-server/
├── src/
│   └── server.ts       # 主服务文件（stdio 模式，Tools/Resources/Prompts 定义）
├── dist/                # 编译输出目录
├── package.json         # npm 包配置
├── tsconfig.json        # TypeScript 配置
├── server.json          # MCP Registry 元数据
├── .gitignore           # Git 忽略配置
└── README.md            # 项目文档

注意: 本项目使用 stdio 传输模式（而非 HTTP），适用于与 OpenCode、Claude Desktop 等 MCP 客户端集成。

API 参考

Tool: calculate-bmi

计算身体质量指数 (BMI)。

输入参数:

{
  "weightKg": 70,      // 体重（千克）
  "heightM": 1.75      // 身高（米）
}

输出:

{
  "bmi": 22.86,
  "category": "Normal weight"
}

Tool: convert-weight

在千克和磅之间转换体重。

输入参数:

{
  "value": 150,
  "fromUnit": "lb",
  "toUnit": "kg"
}

输出:

{
  "originalValue": 150,
  "originalUnit": "lb",
  "convertedValue": 68.04,
  "convertedUnit": "kg"
}

Tool: get-bmi-recommendations

根据 BMI 值获取健康建议。

输入参数:

{
  "bmi": 28.5
}

输出:

{
  "category": "Overweight",
  "recommendations": [
    "Aim for gradual weight loss (0.5-1 kg per week)",
    "Increase physical activity to 200+ minutes per week",
    "Focus on whole foods, reduce processed food intake",
    "Monitor portion sizes and practice mindful eating"
  ]
}

完整教程：从零构建 MCP Server

第一部分：理解 MCP 生态

什么是 MCP？

MCP (Model Context Protocol) 是一个开放协议，为 LLM 应用与外部数据源/工具之间提供标准化的连接方式。类似于 USB-C 为设备提供了标准化的连接接口，MCP 为 AI 模型提供了标准化的方式来连接不同的数据源和工具。

核心组件

┌─────────────────────────────────────────────────────────────┐
│                        MCP 生态                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐      MCP Protocol      ┌─────────────┐    │
│  │             │  ◄──────────────────►  │             │    │
│  │  MCP Client │                         │  MCP Server │    │
│  │             │                         │             │    │
│  │ (LLM App)   │                         │ (Tools/     │    │
│  │ - Copilot   │                         │  Resources/ │    │
│  │ - Claude    │                         │  Prompts)   │    │
│  │ - Custom    │                         │             │    │
│  └─────────────┘                         └─────────────┘    │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  MCP Registry                        │   │
│  │          (Server 发现和发布平台)                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

MCP 的三个核心概念

1. Tools (工具) - 可被 LLM 调用的操作，类似函数调用

   • 例如：搜索、计算、数据库查询
   • 类比：REST API 的 POST 端点

2. Resources (资源) - 只读的数据源，类似 GET 请求

   • 例如：文件内容、数据库记录、配置信息
   • 类比：REST API 的 GET 端点

3. Prompts (提示) - 预定义的提示模板

   • 例如：代码审查模板、文档生成模板
   • 类比：可复用的系统提示

第二部分：项目初始化

2.1 创建项目目录

mkdir bmi-mcp-server
cd bmi-mcp-server

2.2 初始化 npm 项目

npm init -y

2.3 安装依赖

# 核心依赖
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express zod

# 开发依赖
npm install -D typescript ts-node @types/express @types/node

2.4 创建 TypeScript 配置

创建 tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

2.5 创建项目结构

bmi-mcp-server/
├── src/
│   └── server.ts       # 主服务文件
├── dist/                # 编译输出 (自动生成)
├── package.json
├── tsconfig.json
└── README.md

第三部分：实现 MCP Server

3.1 基础框架

创建 src/server.ts:

import { McpServer } from '@modelcontextprotocol/server';
import { createMcpExpressApp } from '@modelcontextprotocol/express';
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
import { z } from 'zod';

// 初始化 MCP Server
const server = new McpServer({
  name: 'bmi-mcp-server',
  version: '1.0.0',
});

// ... Tools/Resources/Prompts 定义 ...

// 创建 Express 应用并挂载 MCP
const app = createMcpExpressApp();

app.post('/mcp', async (req, res) => {
  const transport = new NodeStreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000, () => {
  console.log('MCP Server running on http://localhost:3000/mcp');
});

3.2 注册 Tool (工具)

server.registerTool(
  'calculate-bmi',                              // 工具 ID
  {
    title: 'BMI Calculator',                     // 显示标题
    description: 'Calculate Body Mass Index',    // 描述
    inputSchema: z.object({                      // 输入参数 Schema
      weightKg: z.number().positive(),
      heightM: z.number().positive(),
    }),
    outputSchema: z.object({                     // 输出 Schema
      bmi: z.number(),
      category: z.string(),
    }),
  },
  async ({ weightKg, heightM }) => {             // 实现函数
    const bmi = weightKg / (heightM * heightM);
    return {
      content: [{ type: 'text', text: JSON.stringify({ bmi, category: getBmiCategory(bmi) }) }],
      structuredContent: { bmi, category: getBmiCategory(bmi) },
    };
  }
);

3.3 注册 Resource (资源)

server.registerResource(
  'bmi-categories',           // 资源 ID
  'bmi://categories',         // 资源 URI
  {
    title: 'BMI Categories',
    description: 'Reference table of BMI categories',
    mimeType: 'application/json',
  },
  async () => ({
    contents: [{
      uri: 'bmi://categories',
      mimeType: 'application/json',
      text: JSON.stringify({ categories: [...] }),
    }],
  })
);

3.4 注册 Prompt (提示)

server.registerPrompt(
  'analyze-bmi',
  {
    title: 'Analyze BMI Results',
    description: 'Generate a prompt for analyzing BMI results',
  },
  async () => ({
    messages: [{
      role: 'user',
      content: {
        type: 'text',
        text: 'Analyze the BMI results and provide health assessment...',
      },
    }],
  })
);

第四部分：传输层配置

MCP 支持多种传输方式：

Streamable HTTP (推荐用于 Web 服务)

import { createMcpExpressApp } from '@modelcontextprotocol/express';

const app = createMcpExpressApp();
app.post('/mcp', async (req, res) => {
  const transport = new NodeStreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

stdio (推荐用于 CLI 工具)

import { StdioServerTransport } from '@modelcontextprotocol/server';

const transport = new StdioServerTransport();
await server.connect(transport);

DNS 重绑定防护

使用 @modelcontextprotocol/express 提供的 createMcpExpressApp() 可以自动启用主机头验证，防止本地服务被恶意域名劫持。

第五部分：测试 MCP Server

5.1 启动服务器

# 开发模式
npm run dev

# 或构建后运行
npm run build
npm start

5.2 使用 MCP Client 测试

可以使用官方的 MCP Inspector 或编写简单的测试脚本：

import { Client } from '@modelcontextprotocol/client';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const client = new Client({ name: 'test-client', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport({
  url: 'http://localhost:3000/mcp',
});

await client.connect(transport);

// 调用 calculate-bmi 工具
const result = await client.callTool({
  name: 'calculate-bmi',
  arguments: { weightKg: 70, heightM: 1.75 },
});

console.log(result);

5.3 健康检查

curl http://localhost:3000/health

响应示例：

{
  "status": "healthy",
  "server": "bmi-mcp-server",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

发布到 MCP Registry

📖 官方文档：Publish Your MCP Server

6.1 部署方式概述

MCP Server 可以通过以下方式发布：

6.2 安装 mcp-publisher CLI

Windows (PowerShell):

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"
tar xf mcp-publisher.tar.gz mcp-publisher.exe
# 将 mcp-publisher.exe 移到 PATH 中的目录

macOS/Linux:

brew install mcp-publisher

6.3 初始化 server.json

cd /path/to/your/mcp-server
mcp-publisher init

这会自动创建带有检测值的 server.json。

6.4 配置 server.json

选择命名空间

• io.github.yourname/* - 需要 GitHub 认证
• com.yourcompany/* - 需要 DNS 验证

Package Deployment (NPM 为例)

1. 更新 package.json 添加 mcpName:

{
  "name": "@yourname/bmi-mcp-server",
  "version": "1.0.0",
  "mcpName": "io.github.yourname/bmi-mcp-server"
}

2. 配置 server.json:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.yourname/bmi-mcp-server",
  "description": "A custom MCP server for BMI calculation, weight conversion, and health recommendations",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "@yourname/bmi-mcp-server",
      "version": "1.0.0"
    }
  ]
}

Remote Deployment (可选)

如果需要远程部署：

{
  "name": "io.github.yourname/bmi-mcp-server",
  "description": "Remote BMI MCP Server",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "sse",
      "url": "https://your-server.example.com/sse"
    }
  ]
}

6.5 发布到 npm (Package 方式)

# 登录 npm
npm login

# 发布包
npm publish --access public

6.6 认证 MCP Registry

GitHub 认证 (用于 io.github. 命名空间):*

mcp-publisher login github

这会打开浏览器进行 OAuth 认证。

6.7 发布服务器

mcp-publisher publish

成功输出：

✓ Successfully published

6.8 验证发布

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.yourname/bmi-mcp-server"

bmi-mcp-server 完整发布配置示例

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.opencode/bmi-mcp-server",
  "description": "A custom MCP server for BMI calculation, weight conversion, and health recommendations. Built with TypeScript.",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "@opencode/bmi-mcp-server",
      "version": "1.0.0"
    }
  ],
  "homepage": "https://github.com/opencode/bmi-mcp-server",
  "keywords": ["mcp", "mcp-server", "bmi", "health", "calculator"]
}

📖 完整发布指南：modelcontextprotocol.info

最佳实践

安全性

类型安全

可维护性

性能优化

官方资源

BMI 分类参考

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

Built with MCP SDK | GitHub