ETABS Documentation Assistant MCP Server (Local Embeddings)

This project provides a Model Context Protocol (MCP) server that allows AI models (like Anthropic's Claude via Claude Desktop) to perform semantic searches on user-provided ETABS documentation. It uses local sentence transformer models for embedding generation (via @xenova/transformers.js) and ChromaDB for vector storage, making it free to run after initial setup.

Core Functionality:

• Exposes an MCP tool named search_etabs_docs.
• Accepts a natural language query about ETABS.
• Finds the most relevant sections in the user's indexed ETABS documentation using semantic similarity.
• Returns text snippets from the documentation (with source file references) to the MCP client (e.g., Claude Desktop) to be used as context by the AI model.

🚨 IMPORTANT DISCLAIMERS 🚨

• NO ETABS DOCUMENTATION INCLUDED: This repository DOES NOT contain any ETABS documentation files. ETABS documentation is proprietary software owned by Computers & Structures, Inc. (CSI).
• USER MUST PROVIDE DOCUMENTATION: To use this server, you MUST have a legally obtained copy of the ETABS documentation, typically in .chm format.
• NO AFFILIATION: This project is not affiliated with, endorsed by, or sponsored by Computers & Structures, Inc. (CSI).
• USE AT YOUR OWN RISK: This software is provided "as-is" without warranty. Ensure you comply with all relevant software licenses for ETABS and its documentation.

Architecture Overview

This project consists of two main parts:

1. Python Indexer (index_chm_py/): A script that extracts content from your .chm ETABS documentation file, converts it to text, chunks it, generates embeddings locally using Sentence Transformers, and stores everything in a local ChromaDB database. This needs to be run once initially.
2. Node.js MCP Server (src/): The actual MCP server that runs persistently. It receives search queries via the search_etabs_docs tool, generates an embedding for the query locally, queries the ChromaDB database for similar chunks, and returns the results to the connected MCP client.

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

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: Version 18 or later recommended (Download).
• npm: Usually included with Node.js.
• Python: Version 3.9 or later recommended (Download). Ensure python and pip are in your PATH.
• Docker: Required to easily run the ChromaDB vector database (Download Docker Desktop). Ensure the Docker daemon/service is running.
• ETABS Documentation File: Your legally obtained etabs.chm (or similarly named) file.
• CHM Extraction Tool: An external command-line tool capable of extracting .chm file contents. This script attempts to use 7z (from 7-Zip) or chmextract.
  • Windows: Install 7-Zip. Ensure 7z.exe is added to your system's PATH environment variable during or after installation.
  • macOS: Install via Homebrew: brew install p7zip chmextract (provides both 7z and chmextract).
  • Linux (Debian/Ubuntu): sudo apt update && sudo apt install p7zip-full libchm-bin (provides 7z and chmextract).

(Verify the tool is callable from your terminal before proceeding).

Setup Instructions

Clone the Repository:

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

(Replace <your-github-username> with your actual username)

Install Node.js Dependencies:

npm install

Setup Python Environment & Install Dependencies:

# 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 ..

Configuration

Copy Example Environment File: From the project root directory:

cp .env.example .env

Edit .env: Open the .env file in your project root using a text editor.

• Review the CHROMA_COLLECTION_NAME. The default etabs_docs_local is usually fine.
• Review the LOCAL_EMBEDDING_MODEL. Xenova/all-MiniLM-L6-v2 is a good default. You can change this to other compatible models from Hugging Face (requires re-indexing if changed later).
• Review CHROMA_HOST. The default http://localhost:8000 matches the Docker command below. Make sure this is reachable from where you run the indexer.

Running Dependencies (ChromaDB)

Start Docker Desktop: Ensure the Docker application/service is running.

Start ChromaDB Container: Open a terminal in the project root directory and run:

# 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

This starts ChromaDB detached (-d), maps port 8000, names the container, and maps the local chroma_data folder for persistence.

Indexing Process (One-Time Setup)

This step extracts your .chm file, processes the content, generates embeddings, and populates the ChromaDB database. You only need to do this once, unless your ETABS documentation file changes significantly.

• Ensure Dependencies are Running: Docker Desktop must be running, and the etabs_chroma_local ChromaDB container must be started (use docker start etabs_chroma_local if previously stopped).
• Activate Python Virtual Environment: If not already active, navigate to index_chm_py and activate the .venv (source .venv/bin/activate or Windows equivalent).
• Run the Indexer Script: Execute the following command from within the index_chm_py directory (while the venv is active), replacing <PATH_TO_YOUR_ETABS.CHM> with the actual, full path to your documentation file:

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

Use quotes around the path, especially if it contains spaces.

• Example (Windows):

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

• Example (macOS):

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

• Example (Linux):

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

Wait: This process can take time (minutes to hours). Monitor the console output for progress and errors.

Running the MCP Server

Once indexing is complete and ChromaDB is running:

• Navigate to Project Root: Ensure your terminal is in the main etabs-mcp-server-local-embeddings directory.

• Build the Node.js Server (if you made code changes):

  npm run build
  

• Start the Server:

  npm start
  

  Alternatively, for development with auto-reloading: npm run dev

The server will load the embedding model (this might take a moment the very first time you run npm start or npm run dev after cloning) and then print ...running on stdio. to the console's standard error output. It is now waiting for an MCP client connection.

Connecting to a Client (Example: Claude Desktop)

• Locate/Create Claude Desktop Config:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Edit the Config: Add an entry for your server within the mcpServers object, using the absolute path to the compiled build/server.js file.

{
  "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
    }
  }
}

(Remember to use double backslashes \\ on Windows paths within the JSON string)

Save the config file.

Restart Claude Desktop completely. Ensure it's fully quit (check system tray/menu bar) before reopening.

Verify: Look for the hammer icon in Claude Desktop. Click it to confirm your search_etabs_docs tool is listed.

Troubleshooting

Indexing Fails:

• Check Python error messages.
• Verify the .chm file path is correct.
• Ensure the CHM extraction tool (7z or chmextract) is installed correctly and in your system's PATH. Try running the tool manually from the command line on a test file.
• Confirm the ChromaDB container (etabs_chroma_local) is running (docker ps).
• Make sure the Python virtual environment is activated and pip install -r requirements.txt was successful.

Server Fails to Start (npm start):

• Did npm run build complete without errors? Check the terminal output.
• Could be an issue loading the embedding model (requires sufficient RAM/CPU). Check terminal output for errors.

Claude Desktop Connection Fails ("failed" status in Settings > Developer):

• Double-check the absolute path to build/server.js in claude_desktop_config.json. Ensure correct path separators (\\ for Windows).
• Is Node.js installed and in the PATH? Try using the full path to node.exe/node in the command field of the config.
• Did the server script exit early? Try npm start manually in the terminal to see if it stays running or prints errors.
• Is the ChromaDB container running? The Node.js server might crash if it can't connect.
• Check Claude logs: Click "Open Logs Folder" in Claude's Developer settings. Look at mcp.log and mcp-server-etabs-local-docs.log (or your server name). console.error messages from your Node.js script appear here.

License

This project is licensed under the MIT License. See the LICENSE file for details. Remember that this license applies only to the code in this repository, not to the ETABS documentation itself.