@hybridlabor-api/bdb-antigravity-skills 1.2.1 → 1.2.2

package/skills/global_config/bdb-vectorworks-mcp.md

@@ -0,0 +1,110 @@
+---
+name: bdb-vectorworks-mcp
+description: Utilizes the Vectorworks RAG + MCP server to search and retrieve Python and VectorScript API documentation.
+---
+
+# 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:
+
+```json
+// 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:
+
+```pascal
+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:
+```bash
+# 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:
+```bash
+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.