Fuel Network & Sway Language

Fuel Network & Sway Language MCP Server

Este proyecto proporciona un servidor de Model Context Protocol (MCP) para el ecosistema de Fuel Network y Sway Language. Permite a los IDE (como Cursor) buscar e interactuar con la documentación de Fuel directamente dentro del entorno de desarrollo.

El servidor indexa la documentación de Fuel y Sway en una base de datos vectorial local de Vectra utilizando embeddings de código abierto (a través de Transformers.js) para potentes capacidades de búsqueda semántica.

Características

• Búsqueda semántica local del contenido de docs.fuel.network
• Sin dependencia de Docker: se ejecuta solo con Bun
• Almacenamiento vectorial rápido basado en archivos con Vectra
• Filtrado y formato mejorados de resultados
• Búsqueda híbrida con respaldo por palabras clave

Instalación rápida

# Clone the repo
git clone https://github.com/FuelLabs/fuel-mcp-server
cd fuel-mcp-server

# Install dependencies
bun install

# Index documentation
bun run src/indexer.ts ./docs

# Test search
bun run src/query.ts --run "What is FuelVM?"

# Start MCP server
bun run src/cli.ts

Uso

Transporte STDIO (predeterminado)

bun run src/cli.ts
# or explicitly
bun run src/cli.ts --transport stdio

Transporte HTTP

bun run src/cli.ts --transport http --port 3500
# Server runs at http://127.0.0.1:3500/mcp
# Health check: http://127.0.0.1:3500/health

Opciones de CLI

bun run src/cli.ts --help
bun run src/cli.ts --transport http --port 3500
bun run src/cli.ts --transport stdio

Integración con Claude/Cursor

Añade a tu archivo de configuración de MCP:

{
  "mcpServers": {
    "fuel-server": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/fuel-mcp-server/src/cli.ts", "--transport", "stdio"]
    }
  }
}

Estructura del proyecto

.
├── docs/                     # Markdown documentation files
├── src/
│   ├── cli.ts                # Main CLI entry point
│   ├── server.ts             # MCP server factory
│   ├── transports/
│   │   ├── stdio.ts          # STDIO transport
│   │   └── http.ts           # HTTP transport
│   ├── chunker.ts            # Markdown chunking logic
│   ├── indexer.ts            # Document indexing script
│   ├── query.ts              # Search query script
│   └── *.test.ts             # Test files
├── vectra_index/             # Local vector database (created after indexing)
├── package.json
└── README.md

Requisitos previos

• Bun: Instala desde bun.sh

Uso

1. Indexar documentos

Coloca los archivos markdown en ./docs o especifica un directorio diferente:

# Index docs in ./docs (default)
bun run src/indexer.ts

# Index custom directory
bun run src/indexer.ts /path/to/your/docs

# With custom settings
EMBEDDING_MODEL=Xenova/bge-small-en-v1.5 bun run src/indexer.ts ./docs

2. Buscar documentos

# Basic search
bun run src/query.ts --run "What is the FuelVM?"

# Custom number of results
NUM_RESULTS=10 bun run src/query.ts --run "smart contracts"

3. Ejecutar el servidor MCP

# Start MCP server (stdio-mode)
bun run src/cli.ts

# With HTTP transport
bun run src/cli.ts --transport http --port 3500

4. Ejecutar pruebas

bun test

Variables de entorno

Variable	Predeterminado	Descripción
VECTRA_INDEX_PATH	./vectra_index	Ubicación de la base de datos vectorial
EMBEDDING_MODEL	Xenova/all-MiniLM-L6-v2	Modelo de Hugging Face
CHUNK_SIZE	2000	Tokens objetivo por fragmento
NUM_RESULTS	5	Número de resultados de búsqueda
LOG_LEVEL		Establecer en debug para salida detallada

Detalles de implementación

• Fragmentación: conserva bloques de código, divide por párrafos con conciencia de contexto
• Indexación: genera embeddings con metadatos mejorados para una mejor búsqueda
• Consultas: búsqueda semántica con filtrado de calidad y respaldo por palabras clave
• Servidor MCP: expone la búsqueda como herramienta mediante comunicación stdio
• Almacenamiento: índice Vectra basado en archivos (no se requiere base de datos externa)

API

Herramientas MCP

searchFuelDocs

• query (string): Consulta de búsqueda
• nResults (number, opcional): Número de resultados (predeterminado: 5)
• includeScore (boolean, opcional): Incluir puntuaciones de relevancia

provideStdContext

• Devuelve rutas y tipos de la biblioteca estándar de Sway

Desarrollo

# Install dependencies
bun install

# Run tests
bun test

# Index sample docs
bun run src/indexer.ts ./docs

# Test search functionality
bun run src/query.ts --run "test query"

# Start MCP server for development (STDIO)
bun run src/cli.ts

# Start MCP server for development (HTTP)
bun run src/cli.ts --transport http --port 3500