From ad2c29a777ea35fb05b7e7fbc5bbb82f836dc043 Mon Sep 17 00:00:00 2001 From: David Blanc Brioir Date: Fri, 26 Dec 2025 19:21:44 +0100 Subject: [PATCH] Fix Library RAG MCP connection issue and add setup documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: - Library RAG MCP server was failing to connect with timeout error - Backend status showed "connected: false" with "MCP error -32001: Request timed out" - Documents uploaded via upload_document tool were never processed Root Cause: - MISTRAL_API_KEY was commented out in .env file - MCP server requires this key for OCR and LLM processing - Without the key, the Python subprocess fails to start - This caused connection timeout in the Node.js backend Solution: - Uncommented MISTRAL_API_KEY in .env (not committed, in .gitignore) - Added LIBRARY_RAG_SETUP.md with complete setup guide - Updated .claude/settings.local.json with bash permissions Changes: - Added LIBRARY_RAG_SETUP.md (setup documentation) - Updated .claude/settings.local.json (auto-approved bash commands) Verified: - MCP server now connects successfully - Status endpoint shows "connected: true" - All 7 Library RAG tools available (upload_document, search_library, etc.) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .claude/settings.local.json | 18 +++++- LIBRARY_RAG_SETUP.md | 106 ++++++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 LIBRARY_RAG_SETUP.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 803927b..d44250f 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -49,7 +49,21 @@ "Bash(claude doctor:*)", "Bash(dir /s /b \".claude_settings.json\")", "Bash(dir /s /b \"settings.local.json\")", - "Bash(python -m json.tool:*)" + "Bash(python -m json.tool:*)", + "Bash(del NUL)", + "Bash(lsof:*)", + "Bash(dir:*)", + "Bash(docker ps:*)", + "Bash(wmic process where \"name=''node.exe'' OR name=''python.exe''\" get ProcessId,CommandLine /format:list)", + "Bash(cmd /c \"cd C:\\\\GitHub\\\\Linear_coding_ikario_body\\\\generations\\\\ikario_body && restart.bat\")", + "Bash(cmd /c \"C:\\\\GitHub\\\\linear_coding_library_rag\\\\generations\\\\library_rag\\\\diagnose_wsl.bat\")", + "Bash(wsl --status:*)", + "Bash(wsl --list:*)", + "Bash(docker version:*)", + "Bash(docker info:*)", + "Bash(docker stats:*)", + "Bash(timeout:*)", + "Bash(docker inspect:*)" ] } -} \ No newline at end of file +} diff --git a/LIBRARY_RAG_SETUP.md b/LIBRARY_RAG_SETUP.md new file mode 100644 index 0000000..185c27c --- /dev/null +++ b/LIBRARY_RAG_SETUP.md @@ -0,0 +1,106 @@ +# Library RAG MCP Setup Guide + +## Quick Setup + +To enable the Library RAG MCP server (document search with Weaviate), you need to configure the following in your `.env` file: + +### Required Environment Variables + +```bash +# Library RAG MCP Configuration +LIBRARY_RAG_ENABLED=true +MCP_LIBRARY_RAG_SERVER_PATH=C:/GitHub/linear_coding_library_rag/generations/library_rag/mcp_server.py +LIBRARY_RAG_PYTHON_COMMAND=python +LIBRARY_RAG_CONNECTION_TIMEOUT=10000 +LIBRARY_RAG_AUTO_RECONNECT=true +LIBRARY_RAG_MAX_RETRIES=3 + +# Weaviate Configuration +WEAVIATE_URL=http://localhost:8080 + +# REQUIRED: Mistral API Key (for OCR functionality) +MISTRAL_API_KEY=your_mistral_api_key_here +``` + +### Why MISTRAL_API_KEY is Required + +The Library RAG MCP server uses Mistral API for: +- **OCR with annotations**: Extracting text from PDF images with layout annotations +- **LLM processing**: Metadata extraction, table of contents generation, semantic chunking + +Without this key, the MCP server **will fail to start** and the backend connection will timeout with error: `MCP error -32001: Request timed out`. + +### Getting Your Mistral API Key + +1. Go to https://console.mistral.ai/ +2. Sign up or log in +3. Navigate to API Keys section +4. Create a new API key +5. Copy the key and add it to your `.env` file + +### Troubleshooting + +**Issue**: Library RAG shows `"connected": false` in status endpoint + +**Solution**: +1. Check that `MISTRAL_API_KEY` is uncommented in `.env` +2. Verify the key is valid +3. Restart the backend server: `npm run dev` + +**Issue**: Connection timeout error + +**Cause**: The MCP server subprocess cannot start without the Mistral API key + +**Fix**: Add the key to `.env` and restart + +### Verifying Connection + +Check the connection status: + +```bash +curl http://localhost:5175/api/library-rag/status | python -m json.tool +``` + +Expected response when connected: +```json +{ + "success": true, + "data": { + "connected": true, + "message": "Library RAG MCP server is connected and ready", + "tools": [...], + "error": null + } +} +``` + +### Available Tools + +Once connected, you'll have access to: + +1. **upload_document** - Upload and index PDF documents with full pipeline (OCR, metadata, chunking, Weaviate ingestion) +2. **search_library** - Semantic search over document chunks +3. **hybrid_search** - Search summaries and high-level content +4. **list_collections** - List all indexed documents +5. **get_document** - Retrieve document metadata +6. **filter_search** - Filter by author, work, or language +7. **extract_text_from_image** - OCR from image URLs + +### Related Configuration + +Make sure Weaviate Docker is running: + +```bash +cd C:\GitHub\linear_coding_library_rag\generations\library_rag +docker-compose up -d +``` + +Check Weaviate status: + +```bash +curl http://localhost:8080/v1/meta +``` + +## Changelog + +**2025-12-26**: Fixed MCP connection issue by adding MISTRAL_API_KEY requirement to documentation. The key must be present in `.env` for the MCP server to start successfully.