Half-Life MCP

概述

简介

HL-MCP 是一个专为 AMX Mod X 和 GoldSrc（Half-Life 1 引擎）插件和模组开发工作流程进行加速的专用 MCP（模型上下文协议）服务器。它与 Cline 或 Cursor 等 AI 驱动的 IDE 无缝集成，利用由 Milvus Lite（一种轻量级向量数据库）支持的精选知识库，提供精确且上下文感知的帮助，特别针对 GoldSrc 生态系统。

---

流程

<img width="344" height="645" alt="image" src="https://gips1.baidu.com/it/u=3673034268,619296666&fm=3081&app=3081&f=PNG?w=344&h=645" />

<br> 该系统实现了一个检索增强生成（RAG）工作流，使 Cursor IDE（等）能够通过语义搜索访问最新的领域特定知识。流程包括离线数据摄取阶段和运行时推理阶段。 <br>

1. 数据摄取（一次性或定期）

• 数据来源：过程始于来自各种来源（如文档、代码库、内部维基或公共网站）的结构化或非结构化数据。
• 使用 Crawl4AI 进行抓取：此组件爬取并提取来源中的干净相关文本内容。
• 将文本结果转换为向量：提取的文本通过嵌入模型处理，将每个文档转换为密集向量表示。
• 将向量写入 Milvus Lite 数据库：生成的嵌入及其原始文本元数据存储在 Milvus Lite 中，这是一个轻量级嵌入式向量数据库。这一步通常执行一次（或当源更改时定期执行），而不是在查询时执行。

2. 运行时交互（按需）

• HL MCP 作为 LLM 代理的工具使用。该工具检索有效的数据搜索查询并返回相关结果。检索到的内容随后被注入到 LLM 提示中，使 Cursor 能够提供准确、基于事实且领域感知的响应。 因为向量数据库是预先构建的，查询延迟保持较低，并且系统可以高效地扩展以提供开发时间辅助，而无需在每次请求时重新处理源数据。

---

数据集概述

数据集是从与 AMX Mod X 和 Half-Life 模组相关的社区驱动和技术资源的多样化集合中编译而成。以下来源对数据集做出了贡献，每种来源提取的页面数如下所示：

• amxx-bg.info: 2,517 页
• amxmodx.org: 784 页
• amxxmodx.ru: 564 页
• wiki.alliedmods.net: 48 页
• dev-cs.ru: 15 页
• VipModular Wiki: 10 页
• aghl.ru: 10 页
• hlds.run: 5 页
• amxmodx.ucoz.ru: 5 页
• GitHub READMEs（选定的仓库）: 4 页
• amx-x.ru: 2 页
• 其他次要来源: 5 页

总计: 约 3,975 个独特页面

这一集合涵盖了广泛的文档、教程、插件参考和社区讨论，使其非常适合语义搜索、检索增强生成（RAG）或基于嵌入的应用程序，在旧版模组生态系统背景下使用。

---

使用方法

安装

按照以下步骤设置和配置项目：

1. 克隆仓库

git clone https://github.com/your-username/hl-mcp.git
cd hl-mcp

2. 配置环境变量

通过复制示例模板创建 .env 文件：

cp .env.example .env

编辑 .env 文件并根据需要更新以下设置：

# Milvus 设置
MILVUS_URI="/path/to/db-file"                 # 到本地 Milvus 数据库文件的路径
MILVUS_COLLECTION_NAME="valve"                # 要使用的 Milvus 集合名称
MILVUS_MAX_RESULTS=5                          # 返回的最大搜索结果数量

# 嵌入模型配置
EMBEDDING_MODEL="path/to/embedding/model/dir"
# 您也可以直接使用 Hugging Face 模型名称，例如：
# EMBEDDING_MODEL="sentence-transformers/distiluse-base-multilingual-cased-v2"

3. 安装依赖项

安装所需的 Python 包：

pip install -r requirements.txt

4. 与您的 IDE 集成（MCP 服务器设置）

该项目作为一个 [MCP（模型控制协议）] 服务器运行。要在您首选的 IDE 中使用它，请相应地配置 MCP 客户端。

例如，在 Cline 中，向您的 cline_mcp_settings.json 添加以下条目：

{
  "mcpServers": {
    "hl-mcp": {
      "command": "python3",
      "args": ["/path/to/hl-mcp/server.py"],
      "timeout": 3600,
      "env": {},
      "transportType": "stdio"
    }
  }
}

用您克隆的仓库中 server.py 的实际绝对路径替换 /path/to/hl-mcp/server.py。

配置完成后，集成将在您的 IDE 中显示如下：

---

嵌入模型

您可能已经注意到，目录 database/{version}/ 包含多个 .db 文件。这些数据库中的每一个都是使用不同的文本嵌入模型生成的。以下是支持的模型列表，按计算复杂度和模型大小递增排序。

如果您希望使用未在此列表中列出的嵌入模型，则需要使用您选择的模型生成的新向量数据库。

数据库文件	模型名称	模型卡片 / Hugging Face 链接	嵌入维度	最大序列长度	主要特性
hlr-distiluse-cv2-{version}.db	distiluse-base-multilingual-cased-v2	sentence-transformers/distiluse-base-multilingual-cased-v2	512	128	轻量级，快速推理；适合基本多语言语义搜索
hlr-e5-large-{version}.db	multilingual-e5-large-instruct	intfloat/multilingual-e5-large-instruct	1024	512	指令调优；在检索任务上表现出色；支持 100 种语言
hlr-alibaba-gte-{version}.db	gte-multilingual-base	Alibaba-NLP/gte-multilingual-base	768	8192	处理长上下文；支持密集和稀疏嵌入；跨语言检索良好
hlr-baai-bge-m3-{version}.db	BGE-M3	BAAI/bge-m3	1024	8192	多功能（密集、稀疏、ColBERT）；支持 100+ 种语言；在多语言基准测试中表现最佳

注意：要整合上述未列出的自定义嵌入模型，您必须重新嵌入您的文档集合并相应地创建新的向量数据库。

---

数据集扩展

如果您想扩展数据集或使用自己的嵌入模型与 Milvus 集成，请使用位于 Jupyter 目录中的准备好的 Colab 笔记本。它包含添加新数据和集成自定义嵌入模型所需的所有代码。