本地嵌入式ETABS-MCP服务器

Name: 本地嵌入式ETABS-MCP服务器
Author: PriyankGodhat

作者：PriyankGodhat9 星标更新：2025-05-06

安装使用来源：spider==github.com

项目介绍

ETABS 文档助手 MCP 服务器（本地嵌入）

该项目提供了一个模型上下文协议（MCP）服务器，允许AI模型（如Anthropic的Claude通过Claude Desktop）在用户提供的ETABS文档中进行语义搜索。它使用本地句子转换器模型生成嵌入（通过@xenova/transformers.js），并使用ChromaDB存储向量，初始设置后即可免费运行。

核心功能：

暴露一个名为search_etabs_docs的MCP工具。
接受关于ETABS的自然语言查询。
使用语义相似性在用户的索引ETABS文档中找到最相关的部分。
将文档中的文本片段（带有源文件引用）返回给MCP客户端（例如Claude Desktop），供AI模型作为上下文使用。

🚨 重要免责声明 🚨

不包含ETABS文档： 本仓库不包含任何ETABS文档文件。ETABS文档是Computers & Structures, Inc. (CSI)拥有的专有软件。
用户必须提供文档： 要使用此服务器，您必须拥有合法获取的ETABS文档副本，通常为.chm格式。
无关联： 本项目与Computers & Structures, Inc. (CSI)无关、未经其认可或赞助。
自行承担风险： 本软件按原样提供，不附带任何保证。确保您遵守所有相关的ETABS及其文档的软件许可。

架构概述

本项目由两部分组成：

Python索引器（index_chm_py/）： 一个脚本，从您的.chm ETABS文档文件中提取内容，将其转换为文本，分块，使用Sentence Transformers本地生成嵌入，并将所有内容存储在本地ChromaDB数据库中。需要在初次运行时执行一次。
Node.js MCP服务器（src/）： 实际运行的MCP服务器。它通过search_etabs_docs工具接收搜索查询，本地生成查询嵌入，查询ChromaDB数据库以查找相似的块，并将结果返回给连接的MCP客户端。

graph LR
    U[用户] --> Client[MCP客户端，例如Claude Desktop]
    Client -- MCP (标准输入输出) --> Server[Node.js MCP服务器]
    Server -- HTTP --> DB[(通过Docker的ChromaDB)]
    User -- 提供 --> CHM[ETABS .chm文件]
    CHM -- 被用于 --> Indexer[Python索引器脚本]
    Indexer --> DB

先决条件

开始之前，请确保已安装以下内容：

Node.js： 建议版本18或更高版本（下载）。
npm： 通常随Node.js一起提供。
Python： 建议版本3.9或更高版本（下载）。确保python和pip已在您的PATH中。
Docker： 需要运行ChromaDB向量数据库（下载Docker Desktop）。确保Docker守护进程/服务正在运行。
ETABS文档文件： 您合法获取的etabs.chm（或其他类似名称）文件。
CHM提取工具： 一个外部命令行工具，能够提取.chm文件的内容。该脚本尝试使用7z（来自7-Zip）或chmextract。
- Windows： 安装7-Zip。确保在安装过程中或之后将7z.exe添加到系统PATH环境变量中。
- macOS： 通过Homebrew安装：brew install p7zip chmextract（提供7z和chmextract）。
- Linux (Debian/Ubuntu)： sudo apt update && sudo apt install p7zip-full libchm-bin（提供7z和chmextract）。

（在继续操作前，请验证终端中可以调用该工具）。

设置说明

克隆仓库：

git clone https://github.com/<your-github-username>/etabs-mcp-server-local-embeddings.git
cd etabs-mcp-server-local-embeddings

（将<your-github-username>替换为您实际的用户名）

安装Node.js依赖项：

npm install

设置Python环境及安装依赖项：

# 导航到Python索引器目录
cd index_chm_py

# 创建Python虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows (命令提示符)：.venv\Scripts\activate.bat
# Windows (PowerShell)：.venv\Scripts\Activate.ps1
# macOS/Linux：source .venv/bin/activate

# 安装Python依赖项
pip install -r requirements.txt

# 重要：在索引步骤期间保持激活此环境！

# 完成Python设置/索引后返回到项目根目录
# cd ..

配置

复制示例环境文件：从项目根目录：

cp .env.example .env

编辑.env：使用文本编辑器打开项目根目录中的.env文件。

查看CHROMA_COLLECTION_NAME。默认值etabs_docs_local通常是合适的。
查看LOCAL_EMBEDDING_MODEL。Xenova/all-MiniLM-L6-v2是一个好的默认选项。您可以更改为此处列出的其他兼容模型（如果更改则需重新索引）。
查看CHROMA_HOST。默认值http://localhost:8000与下面的Docker命令匹配。确保索引器可以从这里访问。

运行依赖项（ChromaDB）

启动Docker Desktop：确保Docker应用程序/服务正在运行。

启动ChromaDB容器：在项目根目录打开终端并运行：

# 如果存在先前运行的容器，则移除
docker rm -f etabs_chroma_local

# 运行ChromaDB，映射本地数据目录以实现持久化
# （如果需要，在PowerShell中使用` `进行行续）
docker run -d -p 8000:8000 --name etabs_chroma_local \
  -v "$(pwd)/chroma_data:/chroma/chroma" \
  chromadb/chroma

这会分离运行ChromaDB（-d），映射端口8000，命名容器，并映射本地chroma_data文件夹以实现持久化。

索引过程（一次性设置）

此步骤将提取您的.chm文件，处理内容，生成嵌入，并填充ChromaDB数据库。除非您的ETABS文档文件发生重大变化，否则只需执行一次。

确保依赖项正在运行： 必须运行Docker Desktop，并且etabs_chroma_local ChromaDB容器必须已启动（如果之前停止过，使用docker start etabs_chroma_local）。
激活Python虚拟环境： 如果尚未激活，请导航至index_chm_py并激活.venv（source .venv/bin/activate或Windows等效命令）。
运行索引器脚本： 在index_chm_py目录内（虚拟环境激活状态下）执行以下命令，将<PATH_TO_YOUR_ETABS.CHM>替换为您的文档文件的实际完整路径：

python indexer.py --chm-file "<PATH_TO_YOUR_ETABS.CHM>"

路径周围使用引号，特别是如果路径中包含空格。

示例（Windows）：

python indexer.py --chm-file "C:\Program Files\Computers and Structures\ETABS 21\etabs.chm"

示例（macOS）：

python indexer.py --chm-file "/Applications/ETABS.app/Contents/Resources/etabs.chm"

示例（Linux）：

python indexer.py --chm-file "/opt/CSI/ETABS/Documentation/etabs.chm"

等待：此过程可能耗时（几分钟到几小时）。监控控制台输出以查看进度和错误。

运行MCP服务器

一旦索引完成并且ChromaDB正在运行：

导航到项目根目录： 确保您的终端位于主etabs-mcp-server-local-embeddings目录中。
构建Node.js服务器（如果您进行了代码更改）：
```
npm run build
```
启动服务器：
```
npm start
```
或者，为了开发时自动重载：npm run dev

服务器将加载嵌入模型（首次运行npm start或npm run dev后可能会花费一些时间），然后在控制台的标准错误输出中打印...正在通过标准输入输出运行。。现在它正在等待MCP客户端连接。

连接到客户端（示例：Claude Desktop）

定位/创建Claude Desktop配置：
- Windows： %APPDATA%\Claude\claude_desktop_config.json
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
编辑配置： 在mcpServers对象中添加您的服务器条目，使用编译后的build/server.js文件的绝对路径。

{
  "mcpServers": {
    // 在此处添加其他服务器，如果有
    "etabs-local-docs": {
      "command": "node", // 或者如果需要，使用node.exe的完整路径
      "args": [
        // --- 替换为您的绝对路径 ---
        // Windows 示例："C:\\Users\\YourUser\\Projects\\etabs-mcp-server-local-embeddings\\build\\server.js"
        // macOS 示例："/Users/youruser/Projects/etabs-mcp-server-local-embeddings/build/server.js"
        // Linux 示例："/home/youruser/projects/etabs-mcp-server-local-embeddings/build/server.js"
        "YOUR_ABSOLUTE_PATH_TO_PROJECT/etabs-mcp-server-local-embeddings/build/server.js"
      ]
      // "env": {} // 如果未正确使用.env，可以在服务器需要环境变量时在此处添加
    }
  }
}

（记得在Windows路径内的JSON字符串中使用双反斜杠\\）

保存配置文件。

完全重启Claude Desktop。确保它完全退出（检查系统托盘/菜单栏）后再重新打开。

验证： 查找Claude Desktop中的锤子图标 <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style="display: inline; margin: 0; height: 1.3em;" />。点击它确认您的search_etabs_docs工具是否列出。

故障排除

索引失败：

检查Python错误消息。
确认.chm文件路径正确。
确保CHM提取工具（7z或chmextract）正确安装并在系统PATH中。尝试手动从命令行对测试文件运行该工具。
确认ChromaDB容器（etabs_chroma_local）正在运行（docker ps）。
确保Python虚拟环境已激活且pip install -r requirements.txt成功。

服务器无法启动（`npm start`）：

npm run build是否顺利完成？检查终端输出。
可能是加载嵌入模型的问题（需要足够的RAM/CPU）。检查终端输出中的错误。

Claude Desktop连接失败（“失败”状态在设置 > 开发者）：

再次检查claude_desktop_config.json中的build/server.js绝对路径。确保路径分隔符正确（Windows上为\\）。
Node.js是否已安装并在PATH中？尝试在配置的命令字段中使用node.exe/node的完整路径。
服务器脚本是否提前退出？尝试在终端中手动运行npm start，查看是否持续运行或打印错误。
ChromaDB容器是否正在运行？如果Node.js服务器无法连接，可能会崩溃。
检查Claude日志：点击Claude开发者设置中的“打开日志文件夹”。查看mcp.log和mcp-server-etabs-local-docs.log（或您的服务器名称）。console.error消息将出现在这里。

许可证

本项目根据MIT许可证发布。详情见LICENSE文件。请注意，此许可证仅适用于本仓库中的代码，而不适用于ETABS文档本身。