Fuel Network & Sway Language

Servidor MCP Fuel Network & Sway Language

Este projeto fornece um servidor Model Context Protocol (MCP) para o ecossistema Fuel Network e Sway Language. Ele permite que IDEs (como Cursor) pesquisem e interajam com a documentação do Fuel diretamente no ambiente de desenvolvimento.

O servidor indexa a documentação do Fuel e Sway em um banco de dados vetorial local Vectra usando embeddings de código aberto (via Transformers.js) para poderosas capacidades de busca semântica.

Recursos

• Busca semântica local do conteúdo de docs.fuel.network
• Sem dependência de Docker - executa apenas com Bun
• Armazenamento vetorial rápido baseado em arquivos com Vectra
• Filtragem e formatação aprimoradas de resultados
• Busca híbrida com fallback de palavras-chave

Instalação 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 (Padrão)

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

Opções de CLI

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

Integração com Claude/Cursor

Adicione ao seu arquivo de configuração MCP:

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

Estrutura do Projeto

.
├── 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

Pré-requisitos

• Bun: Instale a partir de bun.sh

Uso

1. Indexar Documentos

Coloque arquivos markdown em ./docs ou especifique um diretório 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. Executar 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. Executar Testes

bun test

Variáveis de Ambiente

Variável	Padrão	Descrição
VECTRA_INDEX_PATH	./vectra_index	Localização do banco de dados vetorial
EMBEDDING_MODEL	Xenova/all-MiniLM-L6-v2	Modelo Hugging Face
CHUNK_SIZE	2000	Tokens alvo por bloco
NUM_RESULTS	5	Contagem de resultados de busca
LOG_LEVEL		Defina como debug para saída detalhada

Detalhes de Implementação

• Fragmentação: Preserva blocos de código, divide por parágrafos com consciência de contexto
• Indexação: Gera embeddings com metadados aprimorados para melhor busca
• Consulta: Busca semântica com filtragem de qualidade e fallback de palavras-chave
• Servidor MCP: Expõe a busca como ferramenta via comunicação stdio
• Armazenamento: Índice Vectra baseado em arquivos (sem banco de dados externo necessário)

API

Ferramentas MCP

searchFuelDocs

• query (string): Consulta de busca
• nResults (número, opcional): Número de resultados (padrão: 5)
• includeScore (booleano, opcional): Incluir pontuações de relevância

provideStdContext

• Retorna caminhos e tipos da biblioteca padrão Sway

Desenvolvimento

# 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