MCP 服务器

Fuel Network & Sway Language MCP Server

一个 Fuel MCP 服务器，它为 Fuel 文档和各种编码 IDE（例如 Cursor）提供支持。

FuelLabs

开发者工具

README

Fuel Network & Sway 语言 MCP 服务器

本项目提供了一个专为 Fuel Network 和 Sway 语言生态系统设计的 Multi-Component Protocol (MCP) 服务器。它允许 IDE（例如带有适当扩展的 VS Code）连接并无缝地与 Fuel 文档交互，从而更容易在 Fuel 项目中进行搜索、理解和开发。

该服务器使用开源嵌入（通过 Transformers.js）将 Fuel 和 Sway 文档（包括 markdown 文件）索引到 Qdrant 向量数据库中。这使得可以直接在开发环境中进行强大的语义搜索。

项目结构

.
├── docs/                     # 包含示例 markdown 文件的目录
│   └── fuel-docs.md          # 示例文档
├── src/
│   ├── chunker.ts            # 将 markdown 分割成块的逻辑
│   ├── chunker.test.ts       # chunker 的测试
│   ├── indexer.ts            # 将文档索引到 QdrantDB 的主脚本
│   ├── indexer.test.ts       # indexer 的测试
│   ├── query.ts              # 查询 QdrantDB 集合的脚本
│   ├── query.vest.ts         # 查询的测试
│   └── mcp-server.ts         # MCP 服务器实现
├── node_modules/             # 项目依赖
├── qdrant_storage/           # 本地 Qdrant 数据持久化（如果使用 Docker 卷）
├── Xenova/                   # 缓存的嵌入模型
├── .env.example              # 示例环境变量
├── .gitignore
├── bun.lockb                 # Bun lockfile
├── package.json
├── tsconfig.json
├── vitest.config.ts          # Vitest 配置
└── README.md

前提条件

Bun: 从 https://bun.sh/ 安装
QdrantDB: 需要一个正在运行的实例。最简单的方法是使用 Docker：
```
# 拉取 Qdrant 镜像
docker pull qdrant/qdrant

# 运行带有持久存储的 Qdrant（创建 ./qdrant_storage）
docker run -p 6333:6333 -p 6334:6334 \\
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \\
    qdrant/qdrant
```
脚本假定 QdrantDB 可在 http://localhost:6333 访问。您可以使用 QDRANT_URL 环境变量配置此项。如果您的 Qdrant 实例需要 API 密钥（例如，Qdrant Cloud），请设置 QDRANT_API_KEY 环境变量。

使用 Docker 运行（推荐）

本项目包含一个 docker-compose.yml 文件，可以轻松地在容器中运行 Qdrant 数据库和 MCP 服务器。

前提条件：

Docker: 从 https://www.docker.com/ 安装
Docker Compose: 通常包含在 Docker Desktop 中。

步骤：

克隆存储库（如果尚未克隆）。
(可选) 创建一个 .env 文件： 将 .env.example 复制到 .env 并根据需要配置环境变量（例如，Qdrant Cloud 的 QDRANT_API_KEY）。注意： QDRANT_URL 由 Docker Compose 自动处理，用于服务器和 Qdrant 容器之间的通信。您可以在此处添加 mcp-server 需要的其他变量（例如 EMBEDDING_MODEL、QDRANT_COLLECTION）。
构建并启动容器： 在项目根目录中打开一个终端并运行：
```
docker compose up --build -d
```
- --build：基于 Dockerfile 构建 mcp-server 镜像。
- -d：在分离模式下（在后台）运行容器。此命令将：
- 如果不存在，则拉取 qdrant/qdrant 镜像。
- 构建 mcp-server 镜像。
- 启动 Qdrant 和 MCP 服务器的容器。
- 设置一个网络供容器通信。
- 挂载 ./qdrant_storage 以实现持久 Qdrant 数据。
索引文档： 要在运行的 mcp-server 容器内部运行索引器脚本：
```
# 使用容器中定义的默认设置索引 ./docs 中的文件
docker compose exec mcp-server-app bun run src/indexer.ts

# 索引文件并指定参数（在容器内运行）
docker compose exec mcp-server-app bun run src/indexer.ts /app/docs my_collection Xenova/bge-small-en-v1.5
```
- 请记住，文件路径（例如 /app/docs）相对于容器的文件系统（/app 是 Dockerfile 中定义的 WORKDIR）。如果您需要索引主机上的文件，则可能需要在 docker-compose.yml 中挂载其他卷。
- 如果您在 docker-compose.yml 的 environment 部分下定义了环境变量，则您的 .env 文件中的环境变量应由 mcp-server 容器自动拾取。
MCP 服务器正在运行： docker compose up 命令已按照 Dockerfile 中的定义启动了 MCP 服务器 (CMD ["bun", "run", "mcp-server"])。它可以通过 docker compose exec 进行访问，以进行标准输入/输出通信。

与 Cursor 连接：

按照之前的说明连接 Cursor，但使用以下 stdio 命令：

{
  "cursor.mcp.servers": [
    {
      "name": "Fuel MCP Server (Docker)",
      "type": "stdio",
      "command": "docker compose exec -T mcp-server-app bun run mcp-server",
      "cwd": "/Users/nickalexander/Github/fuel-mcp-server" // <-- 重要：使用主机上项目的绝对路径
    }
    // ... 其他服务器
  ]
}

将 /Users/nickalexander/Github/fuel-mcp-server 替换为 docker-compose.yml 文件所在的项目的实际绝对路径。cwd 告诉 Cursor 从哪里运行 docker compose exec 命令。

停止容器： 要停止并删除 docker-compose.yml 中定义的容器、网络和卷：
```
docker compose down
```
要停止而不删除：
```
docker compose stop
```

安装

克隆存储库。
安装依赖项：
```
bun install
```
(可选) 创建一个 .env 文件： 将 .env.example 复制到 .env 并根据需要配置 QDRANT_URL 和 QDRANT_API_KEY。

用法

添加文档： 将您的 markdown 文件 (.md) 放在 docs/ 目录中（或在运行索引器时指定其他目录）。
运行测试（可选）：
```
bun test
```
索引文档： 运行索引器脚本。这将从指定目录（或默认情况下为 ./docs）读取文件，将其分块，使用配置的模型生成嵌入，并将它们添加到 Qdrant 集合中。
```
# 使用默认设置索引 ./docs 中的文件
bun run src/indexer.ts

# 索引自定义目录中的文件，指定集合和模型
bun run src/indexer.ts ./path/to/my/markdown my_qdrant_collection Xenova/bge-small-en-v1.5
```
Indexer 的脚本参数：
- docsDir（可选，位置参数）：包含 markdown 文件的目录的路径（默认值：./docs）。
- collectionName（可选，位置参数）：要使用的 Qdrant 集合的名称（默认值：bun_qdrant_docs）。
- modelName（可选，位置参数）：来自 Hugging Face 的 Sentence Transformer 模型（默认值：Xenova/all-MiniLM-L6-v2）。
- targetChunkSize（可选，位置参数）：块的目标 token 大小（默认值：2000）。
Indexer 的环境变量：
- QDRANT_URL：您的 Qdrant 实例的 URL（默认值：http://localhost:6333）。
- QDRANT_API_KEY：Qdrant 的 API 密钥（如果需要）。
查询文档： 运行查询脚本，并将您的问题作为命令行参数。您必须在查询之前包含 --run 标志。
```
bun run src/query.ts --run "什么是 FuelVM？"
```
Query 的环境变量：
- QDRANT_URL：您的 Qdrant 实例的 URL（默认值：http://localhost:6333）。
- QDRANT_API_KEY：Qdrant 的 API 密钥（如果需要）。
- QDRANT_COLLECTION：指定要查询的集合（默认值：bun_qdrant_docs）。应与用于索引的集合匹配。
- EMBEDDING_MODEL：指定嵌入模型（默认值：Xenova/all-MiniLM-L6-v2）。应与用于索引的模型匹配。
- NUM_RESULTS：要检索的结果数（默认值：5）。
使用自定义集合和结果数的示例：
```
QDRANT_COLLECTION=my_qdrant_collection NUM_RESULTS=3 bun run src/query.ts --run "谓词如何工作？"
```

MCP 服务器（用于 IDE 集成）

本项目包含一个 MCP（模型上下文协议）服务器 (src/mcp-server.ts)，它将 Fuel 文档搜索功能公开为一个工具。这允许兼容的客户端（例如 Cursor）连接并直接在 IDE 中使用搜索功能。

运行 MCP 服务器

确保 QdrantDB 正在运行并且您已索引您的文档（请参阅上述步骤）。

要启动 MCP 服务器，请运行以下命令。根据需要配置环境变量（特别是 QDRANT_URL、QDRANT_API_KEY、QDRANT_COLLECTION、EMBEDDING_MODEL，如果您在索引/查询期间使用了非默认值）。

# 使用默认设置的示例
bun run mcp-server

# 使用自定义设置的示例
QDRANT_URL=http://your-qdrant-host:6333 QDRANT_COLLECTION=my_docs bun run mcp-server

服务器将通过标准输入/输出 (stdio) 连接并等待客户端连接。

与 Cursor 连接

打开 Cursor。
打开命令面板（macOS 上为 Cmd+Shift+P，Windows/Linux 上为 Ctrl+Shift+P）。
搜索并选择“MCP: 通过命令添加 MCP 服务器”。
输入命令以运行服务器。由于服务器使用 bun run，并且 Cursor 需要 bun 的完整路径，因此您通常需要首先找到 bun 的路径（在您的终端中 which bun）。您还需要项目目录的完整路径。
- 构造命令：
  - 从 bun 的完整路径开始。
  - 添加 run。
  - 添加 mcp-server 脚本的完整路径（例如，/path/to/fuel-mcp-server/src/mcp-server.ts）。
  - (至关重要) 在 bun 命令之前添加任何必需的环境变量。
- 示例（根据需要替换路径和变量）：
```
QDRANT_COLLECTION=my_docs /path/to/your/bun run /path/to/fuel-mcp-server/src/mcp-server.ts
```
- 重要提示： 确保您提供完整的绝对路径并直接在命令字符串中正确设置任何必需的环境变量。
在提示时为服务器命名（例如，“Fuel 文档搜索”）。

连接后，您应该能够通过 Cursor 的聊天或代码操作使用 searchFuelDocs 工具（或 MCP 服务器公开的任何工具）。

实现细节

分块 (src/chunker.ts)： 首先按代码块 (\`\`\`) 分割 markdown。然后，文本部分按段落 (\\n\\n) 进一步分割，以达到目标 token 大小。
索引 (src/indexer.ts)： 读取 markdown，将内容分块，使用 Transformers.js 生成嵌入，并将点（向量 + 有效负载）更新到指定的 Qdrant 集合中。使用批处理以提高效率。
查询 (src/query.ts)： 接受文本查询，生成其嵌入，并针对 Qdrant 集合执行相似性搜索以检索最相关的文档块。
MCP 服务器 (src/mcp-server.ts)： 实现 MCP 协议，监听 stdio。将 queryDocs 功能公开为 MCP 工具，处理与客户端（例如 Cursor）的请求/响应周期。
嵌入： 使用 Sentence Transformer 模型（例如，Xenova/all-MiniLM-L6-v2）通过 Transformers.js 库创建文本块的向量表示。