Boilerplate MCP Server

MCP 服务样板

使用 TypeScript 实现的样板 Model Context Protocol（MCP）服务。本项目演示了如何构建结构良好的 MCP 服务，为 Claude Desktop 等 AI 应用提供工具和资源。它可作为开发者构建兼容 MCP 的服务的起点，重点关注清晰的架构、自动化工作流和轻松部署。

核心功能

• STDIO MCP 服务：专为 Claude Desktop 等 AI 客户端设计，通过 Model Context Protocol 提供工具和资源。
• CLI 支持：提供易于使用的命令行界面，实现相同功能，方便直接测试和使用。
• IP 地址查询：获取任意 IP 地址或当前设备 IP 的详细信息。
• 自动化发布管理：通过 GitHub Actions 工作流进行持续集成、测试和发布到 GitHub Packages。

安装

全局安装

你可以全局安装此软件包，将其用作 CLI 工具：

npm install -g @aashari/boilerplate-mcp-server

全局安装后，你可以直接运行 CLI 命令：

# Get help
boilerplate-mcp-server --help

# Get current IP details
boilerplate-mcp-server get-ip-details

# Get details for a specific IP
boilerplate-mcp-server get-ip-details 8.8.8.8

本地安装

如需开发或本地使用，请克隆仓库并安装依赖：

git clone https://github.com/aashari/boilerplate-mcp-server.git
cd boilerplate-mcp-server
npm install

然后运行开发服务：

npm run dev

或者构建并启动：

npm run build
npm start

面向最终用户的配置选项

在 Claude Desktop 或 Cursor AI 中进行设置之前，你可以配置此服务。面向最终用户，有两种推荐的选项：

选项 1：在 Claude/Cursor 中直接配置

将配置直接传入 Claude Desktop 配置文件或 Cursor AI 命令：

{
  "mcpServers": {
    "aashari/boilerplate-mcp-server": {
      "command": "npx",
      "args": ["-y", "DEBUG=true", "IPAPI_API_TOKEN=your_token", "aashari/boilerplate-mcp-server"]
    }
  }
}

选项 2：全局配置文件（推荐）

1. 在 $HOME/.mcp/configs.json 创建全局配置文件：

{
  "@aashari/boilerplate-mcp-server": {
    "environments": {
      "DEBUG": "true",
      "IPAPI_API_TOKEN": "your_token"
    }
  }
}

2. 然后在 Claude Desktop 或 Cursor AI 中使用简化配置：

{
  "mcpServers": {
    "aashari/boilerplate-mcp-server": {
      "command": "npx",
      "args": ["-y", "aashari/boilerplate-mcp-server"]
    }
  }
}

这种方式可将配置集中保存在一个安全的位置，并简化 AI 助手的设置。

可用配置选项

• DEBUG：设为 true 可启用调试日志。
• IPAPI_API_TOKEN：IP API 服务的 API 令牌（如有需要）。

在 Claude Desktop 中设置

要在 Claude Desktop 中使用此 MCP 服务：

1. 打开 Claude Desktop 设置：

   • 启动 Claude Desktop
   • 点击右上角的设置图标（齿轮）

   

2. 编辑 MCP 配置：

   • 点击“Edit Config”按钮
   • 这会打开包含 claude_desktop_config.json 文件的文件资源管理器/Finder

3. 更新配置文件：

   • 将上述某个配置选项添加到文件中
   • 保存文件

   以下示例使用已设置的全局配置文件：

   {
     "mcpServers": {
       "aashari/boilerplate-mcp-server": {
         "command": "npx",
         "args": ["-y", "aashari/boilerplate-mcp-server"]
       }
     }
   }
   

4. 重启 Claude Desktop：

   • 关闭并重新打开 Claude Desktop，以应用更改

   

5. 确认工具可用：

   • 在 Claude 主页上，找到右侧的锤子图标
   • 点击图标查看可用工具
   • 确认列表中包含 get-ip-details 工具

   

6. 测试工具：

   • 尝试向 Claude 提问：“告诉我我的公网 IP”或“分析这个 IP：8.8.8.8”
   • Claude 会使用 MCP 工具获取并显示所请求的信息

   

使用 Cursor AI 进行设置

要在 Cursor AI 中使用此 MCP 服务：

1. 打开 Cursor 设置：

   • 启动 Cursor
   • 按 CMD + SHIFT + P（Windows 上按 CTRL + SHIFT + P）
   • 输入“settings”，然后选择“Cursor Settings”
   • 在侧边栏中选择“MCP”

   

2. 添加新的 MCP 服务：

   • 点击“+ Add new MCP server”
   • 系统会显示配置表单

   

3. 配置 MCP 服务：

   • 名称：输入 aashari/boilerplate-mcp-server
   • 类型：从下拉菜单中选择 command
   • 命令：根据你的配置方式选择以下其中一种：

   如果使用全局配置文件（推荐）：

   npx -y aashari/boilerplate-mcp-server
   

   如果直接传入配置：

   DEBUG=true IPAPI_API_TOKEN=your_token npx -y aashari/boilerplate-mcp-server
   

   • 点击“Add”

4. 验证服务配置：

   • 现在，服务应已列出，并显示绿色指示标记
   • 你应该能在服务下看到 get_ip_details 工具

   

5. 测试工具：

   • 在聊天侧边栏中，确保已启用 Agent 模式
   • 尝试提问：“给我我的公网 IP”或“分析这个 IP：8.8.8.8”
   • Cursor AI 将使用 MCP 工具获取并显示所请求的信息

   

作为命令行工具使用

该软件包也可作为命令行工具供用户交互使用：

• 查看帮助和可用命令：

  npx -y aashari/boilerplate-mcp-server --help
  

  示例输出：

  Usage: @aashari/boilerplate-mcp-server [options] [command]
  
  A boilerplate Model Context Protocol (MCP) server implementation using TypeScript
  
  Options:
    -V, --version               output the version number
    -h, --help                  display help for command
  
  Commands:
    get-ip-details [ipAddress]  Get details about a specific IP address or the current device
    help [command]              display help for command
  

• 获取当前设备的 IP 详情：

  npx -y aashari/boilerplate-mcp-server get-ip-details
  

  示例输出：

  status: success
  country: Indonesia
  countryCode: ID
  region: JK
  regionName: Jakarta
  city: Jakarta
  zip: 11730
  lat: -6.2114
  lon: 106.8446
  timezone: Asia/Jakarta
  isp: Biznet Wifi
  org:
  as: AS17451 BIZNET NETWORKS
  query: 118.99.106.135
  

  • 获取指定 IP 地址的详情：

  npx -y aashari/boilerplate-mcp-server get-ip-details 8.8.8.8
  

  示例输出：

  status: success
  country: United States
  countryCode: US
  region: VA
  regionName: Virginia
  city: Ashburn
  zip: 20149
  lat: 39.03
  lon: -77.5
  timezone: America/New_York
  isp: Google LLC
  org: Google Public DNS
  as: AS15169 Google LLC
  query: 8.8.8.8
  

---

关于 MCP

有关模型上下文协议（MCP）的详细信息，包括核心概念、架构和实现指南，请参阅 MCP 官方文档。

开发者须知

如果你有兴趣开发或扩展此项目，请参阅开发指南，了解以下内容的详细信息：

• 先决条件和安装
• 项目结构
• 配置系统
• 添加你自己的功能
• 测试和部署
• 创建你自己的 MCP 服务
• 以及更多内容

许可证

ISC