lkx-mcp

# 🛠️ lkx-mcp [](https://www.npmjs.com/package/lkx-mcp) [](LICENSE) 一个功能丰富的 MCP (Model Context Protocol) 服务器，提供多种实用工具，包括天气查询、GitHub 仓库分析、手机信息查询、身份证解析和 User-Agent 解析等功能。 ## ✨ 特性 - 🌤️ **天气警报查询** - 获取美国各州的实时天气警报 - 🔍 **GitHub 仓库信息** - 查询任何 GitHub 仓库的详细统计信息 - 📱 **手机型号查询** - 查询主流手机型号的详细参数 - 🆔 **身份证号解析** - 解析中国身份证号码，获取地区、年龄、性别等信息 - 🌐 **User-Agent 解析** - 解析浏览器 UA 字符串，识别设备型号和系统版本 ## 📦 安装 ```bash # 克隆仓库 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` ```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` | 测试服务器启动 | 检查服务器能否启动 | ## 🔧 开发 ### 安装和编译 ```bash # 安装依赖 pnpm install # 编译项目 pnpm build # 开发模式（自动监听文件变化并重新编译） pnpm run dev ``` ### 本地验证 #### 方法 1：快速验证所有功能（推荐） 运行内置的验证脚本，自动测试所有核心功能： ```bash node verify.js ``` **验证内容**： - ✅ 身份证解析功能 - ✅ User-Agent 解析功能 - ✅ 手机信息查询功能 - ✅ GitHub 仓库格式化功能 **输出示例**： ``` 🧪 开始验证 lkx-mcp 工具... 📝 测试 1: 身份证解析 ✅ 身份证号码有效 ... ✅ 测试通过 📊 测试结果汇总: ✅ 通过: 4 ❌ 失败: 0 🎉 所有测试通过！代码功能正常！ ``` #### 方法 2：在 Cursor 中测试 1. 确保已配置 MCP（参考上面的配置章节） 2. 重启 Cursor 3. 在对话框中测试各个工具： ```bash # 测试 GitHub 查询 "查询 facebook/react 仓库的信息" # 测试手机查询 "查询 iPhone 15 Pro 的参数" # 测试身份证解析 "解析这个身份证号: 110101199003078515" # 测试 User-Agent 解析 "解析这个 UA: Mozilla/5.0 (iPhone; CPU iPhone OS 18_3_2...)" ``` #### 方法 3：测试服务器启动 检查 MCP 服务器是否能正常启动： ```bash ./test.sh ``` ### 开发模式说明 **`pnpm run dev` 的作用**： - 🔍 **自动监听** `src/` 目录下所有 `.ts` 文件的变化 - ⚡ **增量编译** 只编译修改的文件，速度更快 - 💡 **实时反馈** 保存文件后立即看到编译结果和错误 **推荐工作流程**： ```bash # 终端 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`： ```typescript export interface NewToolInfo { // 定义你的数据类型 name: string; value: string; } ``` 在 `src/types/index.ts` 中导出： ```typescript export * from './newTool.js'; ``` ### 步骤 2：创建工具函数 创建 `src/utils/newTool.ts`： ```typescript 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` 中导出： ```typescript export * from './newTool.js'; ``` ### 步骤 3：创建 MCP 工具 创建 `src/tools/newTool.ts`： ```typescript 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` 中注册： ```typescript import { registerNewTool } from './newTool.js'; export default function registerTools(server: McpServer) { // ... 其他工具 registerNewTool(server); // 添加这行 } ``` ### 步骤 5：验证新工具 ```bash # 编译 pnpm build # 验证（可选：在 verify.js 中添加测试用例） node verify.js # 在 Cursor 中测试 # 重启 Cursor 后使用新工具 ``` **就这么简单！** 🎉 ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ ## 📄 许可证 ISC License ## 👤 作者 **liukexin** - [liukexin@xiaohongshu.com](mailto:liukexin@xiaohongshu.com) ## 🔗 相关链接 - [GitHub 仓库](https://github.com/liukexina/lkx-mcp) - [MCP 官方文档](https://modelcontextprotocol.io/) - [Cursor 官网](https://cursor.sh/) --- ⭐ 如果这个项目对你有帮助，请给一个 Star！