使用说明

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

该项目提供了一个模型上下文协议（MCP）服务器，允许AI模型（如Anthropic的Claude通过Claude Desktop）在 用户提供 ETABS文件。它使用局部句子变换器模型进行嵌入生成（通过 @xenova/transformers.js)ChromaDB用于矢量存储，使其在初始设置后可以自由运行。

核心功能：

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

🚨 重要免责声明🚨

不包括ETABS文件： 此存储库不包含任何ETABS文档文件。ETABS文档是股份有限公司计算机与结构公司（CSI）拥有的专有软件。
用户必须提供文件： 要使用此服务器，您必须持有合法获得的ETABS文件副本，通常在 .chm 格式。
无隶属关系： 本项目不隶属于股份有限公司计算机与结构公司（CSI），也不由其背书或赞助。
使用风险自负： 本软件按“原样”提供，不提供保修。确保您遵守ETABS及其文档的所有相关软件许可证。

架构概述

该项目由两个主要部分组成：

Python索引器(index_chm_py/): 从您的网页中提取内容的脚本 .chm ETABS文档文件，将其转换为文本，将其分块，使用句子转换器在本地生成嵌入，并将所有内容存储在本地ChromaDB数据库中。 最初需要运行一次。
Node.js MCP服务器(src/): 持续运行的实际MCP服务器。它通过以下方式接收搜索查询 search_etabs_docs 工具，在本地为查询生成嵌入，在ChromaDB数据库中查询类似的块，并将结果返回给连接的MCP客户端。

graph LR
    U[User] --> Client[MCP Client e.g., Claude Desktop]
    Client -- MCP (stdio) --> Server[Node.js MCP Server]
    Server -- HTTP --> DB[(ChromaDB via Docker)]
    User -- Provides --> CHM[ETABS .chm File]
    CHM -- Used by --> Indexer[Python Indexer Script]
    Indexer --> DB

先决条件

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

Node.js： 推荐版本18或更高版本(下载).
npm： 通常包含在Node.js中。
python 建议使用3.9或更高版本(下载).确保 python 和 pip 在你的路径。
Docker： 需要轻松运行ChromaDB矢量数据库(下载Docker桌面).确保Docker守护进程/服务正在运行。
ETABS文档文件： 您合法获得的 etabs.chm （或类似名称）文件。
CHM提取工具： 一个能够提取的外部命令行工具 .chm 文件内容。此脚本试图使用 7z （来自7-Zip）或 chmextract.
- 窗户： 安装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环境并安装依赖项：

# Navigate to the Python indexer directory
cd index_chm_py

# Create a Python virtual environment
python -m venv .venv

# Activate the virtual environment
# Windows (Command Prompt): .venv\Scripts\activate.bat
# Windows (PowerShell):   .venv\Scripts\Activate.ps1
# macOS/Linux:            source .venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# IMPORTANT: Stay in this activated environment for the indexing step!

# Go back to the project root when done with Python setup/indexing
# cd ..

配置

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

cp .env.example .env

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

查看 CHROMA_COLLECTION_NAME.默认值 etabs_docs_local 通常很好。
查看 LOCAL_EMBEDDING_MODEL. Xenova/all-MiniLM-L6-v2 这是一个很好的默认设置。您可以从Hugging Face将其更改为其他兼容型号（如果以后更改，则需要重新索引）。
审查 CHROMA_HOST.默认值 http://localhost:8000 匹配下面的Docker命令。确保可以从运行索引器的位置访问它。

运行依赖关系（ChromaDB）

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

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

# Remove container if it exists from a previous run
docker rm -f etabs_chroma_local

# Run ChromaDB, mapping local data directory for persistence
# (Use ` ` for line continuation in PowerShell if needed)
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桌面必须正在运行，并且 etabs_chroma_local ChromaDB容器必须启动（使用 docker start etabs_chroma_local 如果之前已停止）。
激活Python虚拟环境： 如果尚未激活，请导航到 index_chm_py 并激活 .venv (source .venv/bin/activate 或Windows等效物）。
运行索引器脚本： 从中执行以下命令 index_chm_py 目录（当venv处于活动状态时），替换 <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 克隆后），然后打印 ...running on stdio. 到控制台的标准错误输出。它现在正在等待MCP客户端连接。

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

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

{
  "mcpServers": {
    // Add other servers here if you have them
    "etabs-local-docs": {
      "command": "node", // Or full path to node.exe if needed
      "args": [
        // --- REPLACE WITH YOUR ABSOLUTE PATH ---
        // Windows Example: "C:\\Users\\YourUser\\Projects\\etabs-mcp-server-local-embeddings\\build\\server.js"
        // macOS Example: "/Users/youruser/Projects/etabs-mcp-server-local-embeddings/build/server.js"
        // Linux Example: "/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": {} // Environment variables needed by the Node.js server can be added here if not using .env properly
    }
  }
}

（记得使用双反睫毛 \\ 在JSON字符串中的Windows路径上）

保存配置文件。

完全重新启动克劳德桌面。重新打开之前，确保完全退出（检查系统托盘/菜单栏）。

验证： 寻找锤子图标在克劳德桌面。单击它以确认您的 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桌面连接失败（“设置”>“开发人员”中的“失败”状态）：

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

许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。请记住，此许可证仅适用于此存储库中的代码，不适用于ETABS文档本身。

使用说明

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

架构概述

先决条件

安装说明

克隆存储库：

安装Node.js依赖关系：

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

配置

运行依赖关系（ChromaDB）

索引过程（一次性设置）

运行MCP服务器

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

故障排除

索引失败：

服务器无法启动(npm start):

Claude桌面连接失败（“设置”>“开发人员”中的“失败”状态）：

许可证

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务

Laravel文档聚合工具

服务器无法启动(`npm start`):