Vectorworks RAG MCP — Integration and AI Agent Guide

This skill file instructs AI agents on how to utilize the Vectorworks RAG (Retrieval-Augmented Generation) and MCP server. It details documentation searches, VectorScript code generation, and troubleshooting steps.

1. Overview and Pipeline Value

The Vectorworks RAG + MCP Server integrates local Vectorworks Python and VectorScript developer documentation. Using sentence-transformers and a FAISS semantic index, it provides immediate API lookups and code generation recommendations directly to AI models. This avoids syntax hallucinations when generating CAD or BIM layout scripts.

Architecture

• FastAPI / WebSocket Server: Exposes search routes (/search, /answer) and a WebSocket JSON-RPC 2.0 interface (default port 8765) acting as the MCP endpoint.
• FAISS Vector Index: Performs local CPU-bound cosine similarity queries against chunked document sources.
• Dockerized Environment: Package compose wraps the indexer, database, and FastAPI applications.

---

2. System Instructions

Workflow Priorities

1. API Validation first: Before generating any VectorScript or Vectorworks Python script, query the RAG database to verify the function signature (e.g. parameter order, return values).
2. Context boundaries: VectorScript (Pascal-based syntax) and Vectorworks Python have specific execution rules. Explicitly query RAG if you are unsure how attributes or records are handled.
3. Drafting Verification: Use vw.answer to receive a detailed breakdown with citations. Do not write complex routines without consulting the retrieved document chunks first.

---

3. Available Tools and API Parameters

The server provides three tools via WebSocket:

Tool	Parameters	Description
vw.search	query: string, k?: int (default 6)	Returns semantic search hits from the Vectorworks SDK/VectorScript references.
vw.answer	query: string, k?: int	Returns a draft explanation or script snippet synthesized from indexed document blocks.
vw.get	doc_id: string, chunk_id: string	Retrieves a specific document chunk to review source context or examples.

---

4. Code Recipes and Prompt Cookbook

Recipe 1: Retrieve Function Signatures

Find details on drawing a standard rectangle with attributes using VectorScript:

// Tool Call: vw.search
{
  "query": "Rect or CreateRectangle or PushAttrs"
}

// Tool Call: vw.answer
{
  "query": "How do I draw a rectangle in VectorScript and set its fill color?"
}

Recipe 2: VectorScript Structure Example

Consulting a search result from vw.get, construct a standard VectorScript block:

Procedure CreateCustomRect;
VAR
    h : HANDLE;
Begin
    { Draw rectangle }
    Rect(0, 0, 150, 100);
    h := LNewObj;
    
    { Set fill style and color to red }
    SetFPat(h, 1); { Solid fill }
    SetFillBack(h, 65535, 0, 0); { RGB 16-bit color }
    
    ReDraw;
End;
Run(CreateCustomRect);

---

5. Troubleshooting and Connection Details

Configuration and Setup

• Web Interface: http://localhost:8000 (FastAPI UI)
• MCP WebSocket URL: ws://localhost:8765
• Port Settings:
  • API_PORT (FastAPI): Default 8000
  • MCP_PORT (WebSocket): Default 8765

Connection Verification

Ensure the Docker containers are running and port 8765 is bound:

# Verify WebSocket port
curl http://localhost:8000/search?q=PushAttrs

Rebuilding index

If you update or add new documentation files inside the data/ folder, rebuild the FAISS database index:

docker compose run --rm app python -m app.indexer --rebuild

Common Errors and Fixes

1. Connection Refused on ws://localhost:8765
   • Cause: The Docker containers are not running, or the app container crashed.
   • Fix: Run docker compose up -d in the vectorworks-mcp directory and inspect container logs via docker compose logs app.
2. API signature hallucination / Incorrect Pascal syntax
   • Cause: The AI did not consult the RAG database before generating the code block.
   • Fix: Force the agent to run vw.search with the specific function name or topic, then review output references.