🛠️ lkx-mcp

一个功能丰富的 MCP (Model Context Protocol) 服务器，提供多种实用工具，包括天气查询、GitHub 仓库分析、手机信息查询、身份证解析和 User-Agent 解析等功能。

✨ 特性

• 🌤️ 天气警报查询 - 获取美国各州的实时天气警报
• 🔍 GitHub 仓库信息 - 查询任何 GitHub 仓库的详细统计信息
• 📱 手机型号查询 - 查询主流手机型号的详细参数
• 🆔 身份证号解析 - 解析中国身份证号码，获取地区、年龄、性别等信息
• 🌐 User-Agent 解析 - 解析浏览器 UA 字符串，识别设备型号和系统版本

📦 安装

# 克隆仓库
git clone https://github.com/liukexina/lkx-mcp.git

# 进入项目目录
cd lkx-mcp

# 安装依赖
pnpm install

# 编译项目
pnpm build

🚀 使用

配置 MCP 服务器

在 Cursor 的 MCP 配置文件中添加：

macOS/Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\Cursor\mcp.json

{
  "mcpServers": {
    "lkx-mcp": {
      "command": "node",
      "args": ["/path/to/lkx-mcp/build/index.js"]
    }
  }
}

重启 Cursor

配置完成后重启 Cursor，工具即可使用。

📚 工具列表

1. 🌤️ 天气警报查询

工具名称: get_lkx_falerts

查询美国各州的天气警报信息。

示例：

查询加利福尼亚州的天气警报

参数：

• state: 两字母州代码（如 CA、NY、TX）

---

2. 🔍 GitHub 仓库信息查询

工具名称: get_github_repo_info

获取 GitHub 仓库的详细信息，包括星标数、fork数、语言、更新时间等。

示例：

查询 microsoft/vscode 仓库的信息

参数：

• owner: 仓库所有者/组织名
• repo: 仓库名称

返回信息：

• ⭐ Stars、🍴 Forks、👀 Watchers
• 💻 主要语言、📜 许可证
• 📅 创建时间、🔄 最后更新时间
• 🏷️ 标签（Topics）

---

3. 📱 手机型号查询

工具名称: get_phone_info

查询手机型号的详细参数信息。

示例：

查询 iPhone 15 Pro 的参数

参数：

• model: 手机型号名称

支持的型号：

• iPhone 15 Pro / iPhone 15 / iPhone 15 Plus
• Samsung Galaxy S24 Ultra
• 小米 14 Pro
• 华为 Mate 60 Pro

返回信息：

• 📱 品牌和型号
• 📅 发布日期
• 📺 屏幕参数
• ⚙️ 处理器
• 💾 内存和存储
• 🔋 电池容量
• 📷 相机配置
• 🖥️ 操作系统

---

4. 🆔 身份证号解析

工具名称: parse_id_card

解析中国18位身份证号码，提取地区、出生日期、性别等信息，并验证合法性。

示例：

解析身份证号：110101199003078515

参数：

• idCard: 18位身份证号码

功能特性：

• ✅ 校验码验证（国家标准算法）
• 📍 地区识别（全国所有省份）
• 🎂 出生日期解析
• 👤 性别识别
• 📅 年龄计算
• 🔒 隐私保护（日志脱敏）

返回信息：

• 🆔 身份证号码
• 📍 所属地区（省份）
• 🎂 出生日期
• 👤 性别
• 📅 年龄

---

5. 🌐 User-Agent 解析

工具名称: parse_user_agent

解析浏览器 User-Agent 字符串，提取设备型号、系统版本、应用信息等。

示例：

解析这个 UA: Mozilla/5.0 (iPhone; CPU iPhone OS 18_3_2 like Mac OS X)...

参数：

• userAgent: User-Agent 字符串

支持识别：

• 📱 iPhone 型号识别（iPhone 11 ~ iPhone 15 系列）
• 💻 iOS/Android 系统版本
• 📱 设备品牌（Apple、Samsung、Xiaomi 等）
• 📺 屏幕分辨率和缩放比例
• 🌐 网络类型（Wi-Fi、蜂窝网络）
• 📦 应用信息（名称、版本、Build 号）

返回信息：

• 📱 设备品牌、型号、代号
• 💻 操作系统和版本
• 📦 应用名称和版本
• 📺 屏幕分辨率和缩放比例
• 🌐 网络类型和浏览器信息

🏗️ 项目结构

lkx-mcp/
├── src/                    # 源代码目录
│   ├── index.ts           # 主入口文件
│   ├── service.ts         # MCP 服务器创建
│   │
│   ├── types/             # 📦 类型定义层
│   │   ├── index.ts      # 统一导出
│   │   ├── weather.ts    # 天气相关类型
│   │   ├── github.ts     # GitHub 相关类型
│   │   ├── phone.ts      # 手机相关类型
│   │   ├── idCard.ts     # 身份证相关类型
│   │   └── userAgent.ts  # User-Agent 相关类型
│   │
│   ├── utils/             # 🛠️ 工具函数层
│   │   ├── index.ts      # 统一导出
│   │   ├── weather.ts    # 天气数据处理
│   │   ├── github.ts     # GitHub 数据格式化
│   │   ├── phone.ts      # 手机数据库和格式化
│   │   ├── idCard.ts     # 身份证解析和校验
│   │   └── userAgent.ts  # User-Agent 解析
│   │
│   └── tools/             # 🔧 MCP 工具层
│       ├── index.ts      # 工具注册入口
│       ├── weather.ts    # 天气警报工具
│       ├── github.ts     # GitHub 仓库查询工具
│       ├── phone.ts      # 手机型号查询工具
│       ├── idCard.ts     # 身份证解析工具
│       └── userAgent.ts  # User-Agent 解析工具
│
├── build/                  # 编译输出目录
├── verify.js              # 🧪 功能验证脚本
├── test.sh                # 🧪 服务器测试脚本
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript 配置
└── README.md              # 项目文档

架构特点

• 清晰的分层架构 - Types、Utils、Tools 三层分离
• 模块化设计 - 每个功能独立文件，便于维护
• 易于扩展 - 添加新工具只需创建对应的三个文件
• 统一导出 - 通过 index.ts 统一管理导出
• 完善的验证 - 内置验证脚本，确保功能正常

NPM Scripts

命令	说明	使用场景
pnpm build	编译 TypeScript 代码	首次安装、发布前、CI/CD
pnpm run dev	开发模式（监听文件变化）	开发新功能、调试问题
pnpm start	运行 MCP 服务器	本地测试服务器
node verify.js	运行功能验证脚本	验证所有功能是否正常
./test.sh	测试服务器启动	检查服务器能否启动

🔧 开发

安装和编译

# 安装依赖
pnpm install

# 编译项目
pnpm build

# 开发模式（自动监听文件变化并重新编译）
pnpm run dev

本地验证

方法 1：快速验证所有功能（推荐）

运行内置的验证脚本，自动测试所有核心功能：

node verify.js

验证内容：

• ✅ 身份证解析功能
• ✅ User-Agent 解析功能
• ✅ 手机信息查询功能
• ✅ GitHub 仓库格式化功能

输出示例：

🧪 开始验证 lkx-mcp 工具...

📝 测试 1: 身份证解析
✅ 身份证号码有效
...
✅ 测试通过

📊 测试结果汇总:
✅ 通过: 4
❌ 失败: 0
🎉 所有测试通过！代码功能正常！

方法 2：在 Cursor 中测试

1. 确保已配置 MCP（参考上面的配置章节）
2. 重启 Cursor
3. 在对话框中测试各个工具：

# 测试 GitHub 查询
"查询 facebook/react 仓库的信息"

# 测试手机查询
"查询 iPhone 15 Pro 的参数"

# 测试身份证解析
"解析这个身份证号: 110101199003078515"

# 测试 User-Agent 解析
"解析这个 UA: Mozilla/5.0 (iPhone; CPU iPhone OS 18_3_2...)"

方法 3：测试服务器启动

检查 MCP 服务器是否能正常启动：

./test.sh

开发模式说明

pnpm run dev 的作用：

• 🔍 自动监听 src/ 目录下所有 .ts 文件的变化
• ⚡ 增量编译 只编译修改的文件，速度更快
• 💡 实时反馈 保存文件后立即看到编译结果和错误

推荐工作流程：

# 终端 1: 启动开发模式（保持运行）
pnpm run dev

# 终端 2: 修改代码后验证
node verify.js

# 或在 Cursor 中实时测试

性能对比：

• 首次编译：pnpm build ~3秒，pnpm run dev ~3秒
• 修改文件后：pnpm build ~3秒，pnpm run dev ~0.5秒 ⚡

📝 添加新工具

按照模块化结构，添加新工具只需四步：

步骤 1：创建类型定义

创建 src/types/newTool.ts：

export interface NewToolInfo {
    // 定义你的数据类型
    name: string;
    value: string;
}

在 src/types/index.ts 中导出：

export * from './newTool.js';

步骤 2：创建工具函数

创建 src/utils/newTool.ts：

import { NewToolInfo } from '../types/index.js';

export function processNewTool(input: string): NewToolInfo {
    // 实现你的业务逻辑
    return { name: 'test', value: input };
}

export function formatNewTool(info: NewToolInfo): string {
    // 格式化输出
    return `名称: ${info.name}\n值: ${info.value}`;
}

在 src/utils/index.ts 中导出：

export * from './newTool.js';

步骤 3：创建 MCP 工具

创建 src/tools/newTool.ts：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { processNewTool, formatNewTool } from '../utils/index.js';

export function registerNewTool(server: McpServer) {
    server.registerTool(
        "new_tool_name",
        {
            description: "工具描述",
            inputSchema: {
                input: z.string().describe("参数说明"),
            },
        },
        async ({ input }) => {
            const result = processNewTool(input);
            const formatted = formatNewTool(result);
            
            return {
                content: [{ type: "text", text: formatted }],
            };
        }
    );
}

步骤 4：注册到 MCP 服务器

在 src/tools/index.ts 中注册：

import { registerNewTool } from './newTool.js';

export default function registerTools(server: McpServer) {
    // ... 其他工具
    registerNewTool(server);  // 添加这行
}

步骤 5：验证新工具

# 编译
pnpm build

# 验证（可选：在 verify.js 中添加测试用例）
node verify.js

# 在 Cursor 中测试
# 重启 Cursor 后使用新工具

就这么简单！ 🎉

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

ISC License

👤 作者

liukexin - liukexin@xiaohongshu.com

🔗 相关链接

• GitHub 仓库
• MCP 官方文档
• Cursor 官网

---

⭐ 如果这个项目对你有帮助，请给一个 Star！