Local Flow

Un servidor RAG mínimo, local y acelerado por GPU para la ingesta y consulta de documentos.

Documentación

Local Flow

RAG mínimo, local, con aceleración por GPU. Realmente funciona. Viene con más dependencias que la lista de importaciones del Vaticano. Se ejecuta en Windows y WSL.

Arquitectura

MCP Server + FAISS + SentenceTransformers + LangChain + FastMCP

La base de datos vectorial se almacena en ./vector_db (o donde apunte RAG_DATA_DIR). No la elimines a menos que disfrutes reindexando todo. El valor predeterminado es un directorio en Windows. Deberías editar RAG_DATA_DIR si usas WSL porque el argumento no siempre funciona.

JSON-RPC sobre stdin/stdout, pero registramos todo en stderr porque no somos cobardes.

Inicio rápido

Porque el inicio lento no es suficiente para todos ustedes, aceleracionistas.

1. Plataforma

Windows: Configuración nativa de Windows con el kit de CUDA → Ver INSTALL_WINDOWS.md
WSL2: Antes teníamos una guía para instalar el stack de CUDA en WSL2, pero creo que eso es masoquismo -- ahora tenemos configuración que llama a Python de Windows desde WSL.

2. Instalar dependencias

Asumiendo que ya tienes CUDA Toolkit y CUDA Runtime instalados. Si no, ver INSTALL_WINDOWS.md, otra vez.

git clone <repo_url>
# shocking, I know
python -m venv flow-env
flow-env\Scripts\activate.bat
pip install sentence-transformers langchain-community langchain-text-splitters faiss-cpu pdfplumber requests beautifulsoup4 gitpython nbformat pydantic fastmcp

# PyTorch with CUDA (check https://pytorch.org/get-started/locally/ for your version)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# -- CUDA 12.9 (selected 12.8) I used `cu128`

Nota: Usando faiss-cpu porque faiss-gpu es alérgico a versiones recientes de CUDA.

3. Configurar MCP en Cursor

Agrega esto a tu archivo mcp.json - también accesible a través del menú "configuración de MCP":

Windows (%APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json):

Ajusta las rutas a tu configuración (o no funcionará, como era de esperar).

{
  "mcpServers": {
    "LocalFlow": {
      "command": "C:\\Users\\user.name\\Documents\\git\\local_flow\\flow-env\\Scripts\\python.exe",
      "args": ["C:\\Users\\user.name\\Documents\\git\\local_flow\\rag_mcp_server.py"],
      "env": {
        "RAG_DATA_DIR": "C:\\Users\\user.name\\Documents\\flow_db"
      },
      "scopes": ["rag_read", "rag_write"],
      "tools": ["add_source", "query_context", "list_sources", "remove_source"]
    }
  }
}

WSL2 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "LocalFlow": {
      "command": "/mnt/c/Users/your.name/Documents/git/local_flow/flow-env/Scripts/python.exe",
      "args": [
        "C:\\Users\\your.name\\Documents\\git\\local_flow\\rag_mcp_server.py"
      ],
      "env": {
        "RAG_DATA_DIR": "C:\\Users\\your.name\\Documents\\flow_db"
      }
    }
  }
}

Al usar la configuración de WSL, cannot execute binary file indica que la interoperabilidad de WSL está deshabilitada. Arrégralo:

# Add to /etc/wsl.conf
[interop]
enabled = true
appendWindowsPath = true

Luego reinicia WSL desde PowerShell: wsl --shutdown. UNC paths no es compatible es una advertencia relacionada. Si esto no persiste en los reinicios, puedes registrarlo manualmente desde tu distribución WSL2 objetivo.

sudo sh -c 'echo ":WSLInterop:M::MZ::/init:PF" > /proc/sys/fs/binfmt_misc/register'

Si RAG_DATA_DIR no se está recogiendo (la ruta de vector_db muestra \\wsl.localhost\... en los registros), fuerza la ruta de respaldo en rag_mcp_server.py -- el respaldo actual es mi ruta local:

VECTOR_DB_PATH = os.environ.get("RAG_DATA_DIR") or "C:\\Users\\your.name\\Documents\\flow_db"

El servidor se ejecuta en http://localhost:8081.

4. Reinicia Cursor

Si eres un cobarde.

Uso

Agregar documentos

Dile a Cursor que use la herramienta add_source, como magia, pero con más dependencias.

PDFs:

Tipo de origen: pdf
Ruta: /path/to/your/document.pdf (Linux) o C:\path\to\document.pdf (Windows)
ID de origen: Lo que te haga feliz (opcional)

Páginas web:

Tipo de origen: webpage
URL: https://stackoverflow.com/questions/definitely-not-copy-pasted
ID de origen: Opcional

Repositorios Git:

Tipo de origen: git_repo
URL: https://github.com/someone/vibed/tree.git o ruta local
ID de origen: Opcional

Consultas (ejemplos abajo)

Usa la herramienta query_context:

Consulta: "¿Qué hace realmente esta cosa?"
Top K: Cuántos resultados quieres (por defecto: 5)
IDs de origen: Filtrar a fuentes específicas (opcional)

Gestión de fuentes

list_sources - Ver qué le has dado de comer a la máquina
remove_source - Pretende eliminar cosas (solo metadatos)

Solución de problemas

Problemas universales

"Herramienta no encontrada": ¿Reiniciaste Cursor? Reinicia Cursor. "CUDA fuera de memoria": Tu GPU está teniendo sentimientos. Prueba con tamaños de lote más pequeños o documentos menos ambiciosos. "No funciona": Eso no es una pregunta. Pero sí, estoy de acuerdo.

Ejemplos de cosas que puedes indexar

Tus indicaciones deberían indicar uno de los siguientes comportamientos:

Listar las fuentes actualmente disponibles.
Indexar una nueva fuente (dada alguna ruta local)
Eliminar una fuente (de metadatos, no de embeddings)
Consultar fuente(s) existente(s) según algún prompt, a partir del cual se generan palabras clave o frases. Puedes modular parámetros como top_k, solicitando una muestra más grande de los fragmentos de documentos mejor clasificados.

Ejemplo de fuente

"¿Qué fuentes están disponibles en la herramienta Local Flow?" Azure y Machine Learning

ID de fuente	Tipo	Descripción	Fragmentos
`azure_ml_api_docs`	PDF	Documentación de API de Azure Machine Learning	4,713
`azureml_examples_local_new`	Repositorio Git	Repositorio de ejemplos de Azure ML	24,290
`grounding_dino_repo`	Repositorio Git	Repositorio de GroundingDINO	240
`folder_9`	Carpeta	Documentación de HuggingFace Hub	19,706

Vivado / Desarrollo FPGA

ID de fuente	Tipo	Descripción	Fragmentos
`vivado_2019_1_ip_guide`	PDF	UG896 - Guía de usuario de Vivado IP	154
`vivado_2019_1_design_flows`	PDF	UG892 - Descripción general de flujos de diseño Vivado	170
`vivado_2019_1_synthesis_guide`	PDF	UG901 - Guía de síntesis Vivado	320
`pdf_11`	PDF	UG894 - Scripting TCL de Vivado	164
`pdf_8`	PDF	Configuración de licencia de IP ADEAS	9

Ejemplo de consulta 1

"Dame un ejemplo de un parámetro de síntesis que pueda editar en Vivado para mejorar mi velocidad de compilación." -> Ejecutado query_context:LocalFlow -> Consulta:

"query": "synthesis parameters settings options improve build speed runtime performance"
"source_ids": [
  "vivado_2019_1_synthesis_guide"
],
"top_k": 10

-> Respuesta (bruta, esto se usa para informar la respuesta):

{
"results": [
{
"content": "MAX_FANOUT option described in Chapter 2, Synthesis Attributes.\nNote: The -fanout_limit switch does not impact control signals (such as set, reset, clock\nenable): use MAX_FANOUT to replicate these signals if needed.\n-directive: Replaces the -effort_level option. When specified, this option runs\n°\nVivado synthesis with different optimizations. See Table 1-2 for a list of all\nstrategies and settings. Values are:\n- Default: Default settings. See Table 1-2.\n- RuntimeOptimized: Performs fewer timing optimizations and eliminates some\nRTL optimizations to reduce synthesis run time.\n- AreaOptimized_high: Performs general area optimizations including forcing\nternary adder implementation, applying new thresholds for use of carry chain in\ncomparators, and implementing area-optimized multiplexers.\nSynthesis 12\nSend Feedback\nUG901 (v2019.1) June 12, 2019 www.xilinx.com",
"source": "C:\\Users\\helios.lyons\\Documents\\flow_src\\ug901-20191-vivado-synthesis.pdf",
"metadata": {
"source": "C:\\Users\\helios.lyons\\Documents\\flow_src\\ug901-20191-vivado-synthesis.pdf",
"page": 12,
"source_type": "pdf",
"source_id": "vivado_2019_1_synthesis_guide"
}
[...]

-> Completado del prompt (usando fragmentos de la respuesta):

Based on the Vivado Synthesis Guide (UG901), here's a great example:
-directive RuntimeOptimized
This is the most impactful single parameter for reducing synthesis time. It performs fewer timing optimizations and eliminates some RTL optimizations to reduce run time.