VirtualFlyBrain

VFB3-MCP 服务

用于 Virtual Fly Brain（VFB）的模型上下文协议（MCP）服务：可通过 Claude、Copilot 或任何其他 MCP 客户端查询 Drosophila melanogaster 的神经解剖学、连接组学、表达数据和试剂数据。

规范仓库： VirtualFlyBrain/VFB3-MCP（当前仓库）——由 Virtual Fly Brain 团队维护。 托管服务： https://vfb3-mcp.virtualflybrain.org——无需安装、无需 API 密钥、无需账户。

claude mcp add --transport http virtual-fly-brain https://vfb3-mcp.virtualflybrain.org

位于 Robbie1977/VFB3-MCP 的早期副本已归档于 v1.3.0，不再维护；请使用此仓库和上述 URL。

此服务提供工具，用于查询 VFB 数据、执行查询以及搜索术语。在 HTTP 模式下，它以无状态方式运行（不跟踪会话），因此任何副本都可以处理任何请求，并且可使用标准负载均衡。

🚀 快速开始

使用在线服务（推荐）

使用 VFB3-MCP 最简单的方式是通过我们的托管服务 https://vfb3-mcp.virtualflybrain.org。无需在你的计算机上安装或设置任何内容。

Claude Desktop 设置

1. 打开 Claude Desktop 并进入“设置”
2. 导航至 MCP 部分
3. 添加一个新的 MCP 服务，并使用以下设置：
   • 服务名称：virtual-fly-brain（或你喜欢的名称）
   • 类型：HTTP
   • 服务 URL：https://vfb3-mcp.virtualflybrain.org

配置 JSON（替代方法）：

{
  "mcpServers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org",
      "tools": ["*"]
    }
  }
}

Claude Code 设置

1. 找到你的 Claude 配置文件：

   • macOS/Linux：~/.claude.json
   • Windows：%USERPROFILE%\.claude.json

2. 将 VFB3-MCP 服务添加到你的配置中：

{
  "mcpServers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org",
      "tools": ["*"]
    }
  }
}

3. 重启 Claude Code 以使更改生效

GitHub Copilot 设置

1. 打开已安装 GitHub Copilot 的 VS Code
2. 打开设置（Ctrl/Cmd + ,）
3. 在设置搜索中搜索“MCP”
4. 找到 MCP Servers 设置
5. 添加服务 URL：https://vfb3-mcp.virtualflybrain.org
6. 为其命名，例如“Virtual Fly Brain”

替代 JSON 配置（位于 mcp.json 中）：

{
  "servers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org"
    }
  }
}

Visual Studio Code（使用 MCP 扩展）

1. 从市场中为 VS Code 安装 MCP 扩展
2. 打开命令面板（Ctrl/Cmd + Shift + P）
3. **输入“MCP: Add server”**并选择该项
4. **选择“HTTP”**作为服务类型
5. 输入服务详情：
   • 名称：virtual-fly-brain
   • URL：https://vfb3-mcp.virtualflybrain.org
6. 保存并重启 VS Code（如有提示）

其他 MCP 客户端

对于任何支持 HTTP 服务的 MCP 兼容客户端：

{
  "mcpServers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org",
      "tools": ["*"]
    }
  }
}

Gemini 设置

要将 Virtual Fly Brain（VFB）模型上下文协议（MCP）服务与 Google Gemini 配合使用，可以通过支持 MCP 的自定义 Python/Node.js 客户端进行连接。

注意：目前不支持直接将 MCP 集成到 Gemini 网页界面中。需要借助开发者工具来连接两者。

选项 1：使用 Python

开发应用程序时，可使用 mcp 和 google-genai 库进行连接。

设置：pip install google-genai mcp

实现：使用 JSON 响应模式的流式 HTTP 传输（例如 enableJsonResponse: true）连接到 VFB URL，列出其工具，并将其架构作为函数声明传递给 Gemini 模型。

测试连接

配置完成后，可以向 AI 助手提出以下问题，测试 VFB3-MCP 是否正常工作：

基础查询：

• “获取神经元 VFB_jrcv0i43 的信息”
• “搜索与果蝇大脑中髓质相关的术语”
• “触角叶中有哪些神经元？”

高级查询：

• “查找所有与蘑菇体连接的神经元”
• “展示基因 repo 的表达模式”
• “哪些脑区参与嗅觉处理？”
• “对神经元 VFB_00101567 运行连接分析”

搜索示例：

• “搜索视觉系统中的成虫神经元”
• “查找中央复合体中表达的基因”
• “展示 VFB 中所有可用的模板”

如果你看到包含 VirtualFlyBrain 数据的回复，例如神经元名称、脑区、基因表达或连接信息，则表示设置成功！

更多详细用法示例和 API 调用，请参阅 examples.md。

示例工作流

1. 搜索术语：“搜索视叶中的神经元”
2. 获取详细信息：“获取 VFB_00101567 的信息”
3. 运行特定查询：“展示 VFB_00101567 的连接情况”
4. 探索关系：“哪些神经元在蘑菇体中形成突触？”

🛠️ 可用工具

MCP 服务会向 Claude 和 Copilot 等助手提供以下工具：

• get_term_info — 获取 VFB ID 的详细元数据
• run_query — 对 VFB ID 运行预计算分析查询（参见 get_term_info 中的 Queries 字段）
• search_terms — 通过文本搜索 VFB 实体，并支持筛选和加权选项。这与 virtualflybrain.org 自身使用的搜索相同
• list_search_facets — 列出 search_terms 的 filter_types / exclude_types / boost_types / demote_types 可接受的 facets_annotation 类型名称；也可按子字符串筛选
• resolve_entity — 将未解析的 FlyBase 相关查询字符串（例如 P{VT054895-GAL4.DBD} 或驱动系 / 细胞类型标签）解析为 VFB/FlyBase ID 和元数据（与 VFB 术语搜索不同）
• resolve_combination — 将未解析的 split-GAL4 组合名称或同义词解析为其组成 ID
• list_connectome_datasets — 列出可用的连接组数据集（例如 Hemibrain、FAFB）
• query_connectivity — 使用上游 / 下游筛选条件查询跨连接组数据集的连接情况；结果按强度从高到低分页，并提供基于所有已找到连接计算出的摘要
• get_predicted_neurotransmitters — 获取基于各实例连接组预测的神经元类别（及其子类别）的预测神经递质；可按实例返回，也可汇总并计算平均置信度，还可按数据集拆分
• get_known_neurotransmitters — 根据本体分类获取神经元类别及其子类别的已知（经整理）神经递质（无置信度）
• get_hierarchy — 遍历 VFB ID 的本体层级：part_of（区域 / 组织结构）和 / 或 subclass_of（细胞类型分类），可遍历祖先和 / 或后代

🛠️ 本地安装

前置条件

• Node.js 18 或更高版本
• npm 或 yarn

分步安装

1. 克隆仓库：

   git clone https://github.com/VirtualFlyBrain/VFB3-MCP.git
   cd VFB3-MCP
   

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

4. 启动服务：

   npm start
   

平台专属设置

Claude Desktop（本地开发）

要在 Claude Desktop 中进行本地开发，请将以下内容添加到 MCP 配置中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vfb3-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/VFB3-MCP/dist/index.js"]
    }
  }
}

Claude Code

添加到 claude.json 文件中：

{
  "mcpServers": {
    "vfb3-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/VFB3-MCP/dist/index.js"]
    }
  }
}

Visual Studio Code

1. 安装适用于 VS Code 的 MCP 扩展
2. 按 Cmd + Shift + P（macOS）或 Ctrl + Shift + P（Windows/Linux）
3. 选择 MCP: 添加服务器…
4. 选择 Command 类型
5. 输入：
   • 名称：vfb3-mcp
   • 命令：node
   • 参数：/absolute/path/to/VFB3-MCP/dist/index.js

GitHub Copilot

在 Copilot 设置中配置 MCP 服务 URL，使其指向本地服务：

http://localhost:3000

用于 HTTP 模式测试：

MCP_MODE=http PORT=3000 node dist/index.js

Docker 安装

使用 Docker Compose（推荐）：

docker-compose up --build

手动构建 Docker：

# Build the image
docker build -t vfb3-mcp .

# Run the container
docker run -p 3000:3000 vfb3-mcp

拉取预构建镜像：

docker pull virtualflybrain/vfb3-mcp:latest
docker run -p 3000:3000 virtualflybrain/vfb3-mcp:latest

可用工具

get_term_info

使用 VFB 术语的 ID 获取详细信息。

参数：

• id（字符串）：VFB ID（例如 "VFB_jrcv0i43"）
• force_refresh（布尔值，可选）：绕过响应缓存并重新计算（有关开销和白名单限制，请参阅下文的 run_query）

run_query

对 VFB 数据执行预定义查询。

参数：

• id（字符串或数组）：一个或多个 VFB ID（例如 "VFB_00101567"）
• query_type（字符串）：实体 Queries 数组中的查询类型（例如 "PaintedDomains"）
• queries（数组，可选）：用于混合批量查询的 {id, query_type} 对
• limit（数字，可选）：每次调用的最大行数（默认值为 25）。始终通过 count 返回实际总数；设为 0 可获取所有行（仍限制为约 25000 行）
• offset（数字，可选）：分页的行偏移量（默认值为 0）；获取下一页时，重新运行并设置 offset += limit
• include_images（布尔值，可选）：包含 thumbnail 列（默认值为 false — 为节省空间会移除该列，响应中的 _note 会说明如何重新添加）
• force_refresh（布尔值，可选）：绕过响应缓存并重新计算。开销较大；仅用于对返回过期或失败结果的调用进行一次性重试。失败的查询已自动重试一次。要求将服务的出口 IP 添加到 v3-cached 的白名单中 — 对于未列入白名单的主机，nginx 会忽略该标头，并原样提供缓存条目。

响应会在 count 旁报告 count_status：exact（count 为实际总数）、row_count（未提供总数 — count 仅为返回的行数）或 unavailable（上游查询失败，count 为 -1）。-1 表示错误，而非空结果集，_note 中会以文字说明这一点。

FlyBase stocks 和 split-GAL4 组合文献也属于 run_query 查询类型：FindStocks 和 FindComboPublications。对于 split 组合（FBco），如果存在同时包含两个半驱动子的 stocks，FindStocks 会返回这些 stocks；否则会回退为分别返回每个半驱动子的 stocks；match 列会说明匹配情况。

search_terms

搜索 VFB 术语。此工具会调用 VFBquery 的 /search，这正是 virtualflybrain.org 网站自身使用的搜索方式——相同的 Solr 查询、相同的筛选条件和加权规则，以及相同的最终排序——因此，此处的结果就是用户在网站上看到的结果。已弃用的术语已在服务端排除，无需另行要求排除。

参数：

• query（字符串）：搜索查询（例如，“medulla”）
• filter_types（数组，可选）：仅保留与这些 facets_annotation 类型全部匹配的结果（AND 逻辑）
• exclude_types（数组，可选）：排除与这些 facets_annotation 类型中任意一种匹配的结果（OR 逻辑）
• boost_types（数组，可选）：提升与这些类型匹配的结果排名，但不排除其他结果
• demote_types（数组，可选）：将与这些类型匹配的结果降至排名末尾，但不排除这些结果。如果某类型也出现在 boost_types 中，则忽略此设置
• unique（布尔值，可选）：每个术语返回一行（默认值为 true）。设为 false 时，每个匹配的同义词返回一行，这会显示匹配的是哪个名称，但 ID 会重复
• start（数字，可选）：页面起始索引（默认值为 0）
• rows（数字，可选）：返回行数（默认值为 150，最大值为 1000）
• minimize_results（布尔值，可选）：仅返回排名靠前的 10 条结果，并减少字段，以便初步查看（默认值为 false）
• auto_fetch_term_info（布尔值，可选）：当查询与某个术语名称完全匹配时，同时获取该术语的信息（默认值为 false）

类型名称来自实时词汇表——目前有 200 多种，并会随着数据添加而变化，因此请调用 list_search_facets，不要猜测。响应会分别报告 returned（已返回的行数）、total（排序列表的长度）、distinct_terms 和 solr_matches（Solr 在排序前匹配的术语），因此即使页面结果被截断，也不会误以为结果集很小。

list_search_facets

列出上述四种类型筛选器的有效 facets_annotation 类型名称，这些名称读取自实时词汇表。

参数：

• contains（字符串，可选）：不区分大小写和分隔符的子字符串筛选条件（例如，“neuron”“nervous system”）

如果部署的 VFBquery 版本早于 /facets 端点，此工具会改用服务器附带的快照，并说明这一点——快照结果中未列出的名称仍可能有效。

query_connectivity

查询所有 connectome 数据集中的神经元类别之间的突触连接。upstream_type 和 downstream_type 至少需要指定一个。结果按连接强度从高到低排序并分页：工具会返回 limit 行，以及基于找到的所有连接计算的 summary——权重最小值/最大值/总和/平均值、每个数据集的计数、不同神经元的数量，以及排名靠前的类别对——因此即使行数被截断，总数仍然准确。宽泛的查询可能找到数万条连接，因此默认启用分页。

参数：

• upstream_type / downstream_type（字符串，可选）：神经元类别 OWL ID 或标签。不接受解剖区域
• weight（数字，可选）：最小突触数（建议设为 5；两端都已指定时建议使用 ≥50）
• group_by_class（布尔值，可选）：按类别对而非神经元对汇总——宽泛查询时通常更适合作为首次调用
• exclude_dbs（数组，可选）：要排除的数据集符号（建议使用 ["hb","fafb"]）；参见 list_connectome_datasets
• limit（数字，可选）：返回的行数，按强度从高到低排序（默认值为 50；0 表示返回全部）
• offset（数字，可选）：从排名中的哪一行开始（默认值为 0）

get_predicted_neurotransmitters

根据每个神经元实例的连接组预测结果，获取某个神经元类别（包括该类别本身及其子类）预测的神经递质。每个重建的神经元都带有一个预测的神经递质及其置信度。默认聚合为扁平的类别级行（每种细胞类型 × 神经递质一行，包含 instances、percent_of_class、mean_confidence）；aggregate=false 则每个神经元一行。split_by_dataset=true 会添加 dataset 列，以便查看不同连接组间的一致性。神经递质是 GO 分泌术语（nt_id/nt_label），与 get_known_neurotransmitters 使用相同的 ID 空间。此工具不同于 get_known_neurotransmitters，后者提供经整理的分类结果，不含置信度。

参数：

• neuron_type（字符串，必填）：神经元类别的 OWL ID 或标签（包括该类别及其子类）
• aggregate（布尔值，可选）：true（默认）返回类别级行；false 返回实例级行
• split_by_dataset（布尔值，可选）：true（仅聚合时）按（细胞类型、神经递质、数据集）各返回一行
• exclude_dbs（数组，可选）：要排除的数据集符号（默认 ["hb","fafb"]；[] 表示全部包含）
• min_confidence（数字，可选）：舍弃低于此置信度的预测（0..1）

get_known_neurotransmitters

根据本体分类获取某个神经元类别及其子类的已知（经整理的）神经递质，而非基于实例的预测，因此不含置信度。每种（细胞类型、神经递质）组合返回一行：{cell_type_id, cell_type, nt_id, nt_label}，其中 nt_id 是 GO 分泌术语。如果本体未声明任何神经递质，则返回空结果（如需查看数据驱动的结果，请尝试 get_predicted_neurotransmitters）。

参数：

• neuron_type（字符串，必填）：神经元类别的 OWL ID 或标签（包括该类别及其子类）

🧠 关于 VirtualFlyBrain

VirtualFlyBrain（VFB）是一个全面的果蝇（Drosophila melanogaster）神经生物学知识库，提供 3D 图像、基因表达数据、神经连接信息，以及用于果蝇脑研究的标准化术语。

📖 文档

• 大模型指南：介绍 AI 助手如何有效使用此 MCP
• 示例：使用示例和集成指南
• 技术文档：基础设施、部署和开发详情

📄 许可证

MIT