Fuel Network & Sway Language MCP Server

Fuel Network 和 Sway Language MCP 服务

本项目为 Fuel Network 和 Sway Language 生态系统提供 MCP 服务。它支持 IDE（如 Cursor）在开发环境中直接搜索和浏览 Fuel 文档。

该服务使用开源嵌入模型（通过 Transformers.js），将 Fuel 和 Sway 文档索引到本地 Vectra 向量数据库中，从而实现强大的语义搜索能力。

功能

• 对 docs.fuel.network 内容进行本地语义搜索
• 无需依赖 Docker，仅使用 Bun 即可运行
• 使用 Vectra 实现快速的基于文件的向量存储
• 增强结果筛选和格式化功能
• 混合搜索，支持关键词回退

快速安装

# 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

使用方法

STDIO 传输（默认）

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

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

CLI 选项

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

Claude/Cursor 集成

添加到 MCP 配置文件中：

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

项目结构

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

先决条件

• Bun： 从 bun.sh 安装

使用方法

1. 索引文档

将 Markdown 文件放入 ./docs，或指定其他目录：

# 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. 搜索文档

# 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. 运行 MCP 服务

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

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

4. 运行测试

bun test

环境变量

变量	默认值	描述
VECTRA_INDEX_PATH	./vectra_index	向量数据库位置
EMBEDDING_MODEL	Xenova/all-MiniLM-L6-v2	Hugging Face 模型
CHUNK_SIZE	2000	每个分块的目标令牌数
NUM_RESULTS	5	搜索结果数量
LOG_LEVEL		设置为 debug 以输出详细信息

实现细节

• 分块： 保留代码块，并在理解上下文的基础上按段落拆分
• 索引： 生成带有增强元数据的嵌入，以提升搜索效果
• 查询： 结合质量筛选和关键词回退的语义搜索
• MCP 服务： 通过 stdio 通信将搜索功能作为工具提供
• 存储： 基于文件的 Vectra 索引（无需外部数据库）

API

MCP 工具

searchFuelDocs

• query（字符串）：搜索查询
• nResults（数字，可选）：结果数量（默认值：5）
• includeScore（布尔值，可选）：包含相关性分数

provideStdContext

• 返回 Sway 标准库路径和类型

开发

# 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