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/): 从您的网页中提取内容的脚本.chmETABS文档文件，将其转换为文本，将其分块，使用句子转换器在本地生成嵌入，并将所有内容存储在本地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守护进程/服务正在运行。
- 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//etabs-mcp-server-local-embeddings.git
cd etabs-mcp-server-local-embeddings（替换 `` 使用您的实际用户名）
安装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_localChromaDB容器必须启动（使用docker start etabs_chroma_local如果之前已停止）。 - 激活Python虚拟环境： 如果尚未激活，请导航到
index_chm_py并激活.venv(source .venv/bin/activate或Windows等效物）。 - 运行索引器脚本： 从中执行以下命令
index_chm_py目录（当venv处于活动状态时），替换 `
` 使用文档文件的实际完整路径：
python indexer.py --chm-file "
"在路径两边使用引号，特别是如果它包含空格。
- 示例（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.errorNode.js脚本中的消息显示在此处。
______________________________________________________________________
许可证
该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。请记住，此许可证仅适用于此存储库中的代码，不适用于ETABS文档本身。
______________________________________________________________________