etabs -local-embeddings

This MCP server provides a dedicated tool named search_etabs_docs that enables semantic search over your locally stored ETABS documentation. The server uses a local embedding model to convert both the user’s natural language query and the documentation chunks into vector representations, then queries a local ChromaDB instance to retrieve the most relevant snippets. The results returned to the MCP client include text snippets with their source references, which the AI model can use as context to generate accurate, evidence-backed responses about ETABS content. Use cases include quickly finding sections on modeling, frame design, load combinations, or other ETABS topics without exposing your documents to external services.

To use the tool, connect with your MCP client (for example Claude Desktop) and issue a natural language query such as “How do I model a shear wall in ETABS?” The server will compute the embedding for your query, search the local vector store for similar content, and return the most relevant passages. The MCP client then presents these passages to the AI model as context, enabling it to craft informed answers and guide your workflow using your own ETABS documentation.

Prerequisites:

• Node.js 18 or newer installed on your system
• npm supplied with Node.js
• Python 3.9+ for the indexing steps (if you intend to index ETABS CHM content locally)
• Docker installed and running (for ChromaDB container)
• Access to ETABS documentation file (CHM) to index locally

Install and setup steps:

1. Clone the repository and install Node dependencies

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

2. (Optional if using local indexing) Set up Python environment and install dependencies for indexing

cd index_chm_py
python -m venv .venv
# Activate virtual environment depending on your OS
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

3. Start ChromaDB (Docker) to host vector embeddings

docker rm -f etabs_chroma_local
docker run -d -p 8000:8000 --name etabs_chroma_local -v "$(pwd)/chroma_data:/chroma/chroma" chromadb/chroma

4. Index ETABS CHM content (one-time)

# From project root, with Python venv activated
cd index_chm_py
python indexer.py --chm-file "/path/to/your/etabs.chm"

5. Run the MCP server

npm run build   # if you need to build before starting
npm start

6. Verify the server is running. Look for a startup message indicating the MCP server is listening on stdio.

Note: The workflow assumes you will index your own ETABS CHM documentation into ChromaDB. The Node.js server will then load embeddings from ChromaDB and respond to search_etabs_docs queries from your MCP client.

Environment variables you may customize:

• CHROMA_HOST: URL of the ChromaDB service (default http://localhost:8000).
• CHROMA_COLLECTION_NAME: The Chroma collection name to use (default etabs_docs_local).
• LOCAL_EMBEDDING_MODEL: Local embedding model name from Hugging Face (default Xenova/all-MiniLM-L6-v2). Changing this requires re-indexing your CHM content. Common issues:
• Docker daemon not running: Ensure Docker Desktop is started before launching the ChromaDB container.
• Mismatched CHROMA_HOST or collection name: Ensure the .env values align with your running ChromaDB instance.
• First run latency: The first startup may be slow as the model and environment load.
• Access permissions: Ensure the ETABS CHM file and indexing workflow have read permissions where needed.
• Indexing refresh: If you update the documentation, re-run the indexing step to refresh embeddings in ChromaDB.