神经影像数据集MCP接口

Nipoppy MCP服务器

模型上下文协议（MCP）接口 尼帕比 神经影像数据集 框架。此服务器通过MCP公开允许AI代理的工具 以更慎重的方式与Nipoppy研究进行互动。

什么是Nipoppy？

Nipoppy是一个轻量级的标准化组织框架 神经影像临床数据集的处理。它跟随大脑 成像数据结构（BIDS）标准，并提供管理工具 数据集和处理管道。

什么是MCP？

模型上下文协议（MCP）是一种标准化的协议 允许AI应用程序（LLM）访问外部工具和资源 通过一致的界面。此服务器公开了以下工具 总结了Nipoppy研究的当前加工状态。

特性

该MCP服务器通过以下两种方式提供对Nipoppy神经影像数据集的全面访问 工具 和 资源:

MCP资源（自动上下文）

无需函数调用，AI代理即可自动获取上下文信息：

• nipoppy://config -全局数据集配置和元数据
• nipoppy://manifest -数据集结构清单（参与者/会话/数据类型）
• nipoppy://status/curation -不同管理阶段的数据可用性
• nipoppy://status/processing -跨参与者/会议的管道完成状态
• nipoppy://pipelines/{pipeline_name}/{version}/config -单个管道配置
• nipoppy://pipelines/{pipeline_name}/{version}/descriptor -精品店管道描述符
• nipoppy://demographics -已去标识的参与者人口统计信息
• nipoppy://bids/description -BIDS数据集描述和元数据

MCP工具（按需功能）

主要工具（重构和增强）

• get_participants_sessions -按数据阶段过滤的统一参与者/会话查询
• get_dataset_info -通过可配置的详细级别增强数据集概述
• navigate_dataset -具有智能路径解析的文件路径和配置访问

旧版工具（已弃用）

• list_manifest_participants_sessions -使用 get_participants_sessions(data_stage="all") 相反
• list_manifest_imaging_participants_sessions -使用 get_participants_sessions(data_stage="imaging") 相反
• get_pre_reorg_participants_sessions -使用 get_participants_sessions(data_stage="downloaded") 相反
• get_post_reorg_participants_sessions -使用 get_participants_sessions(data_stage="organized") 相反
• get_bids_participants_sessions -使用 get_participants_sessions(data_stage="bidsified") 相反
• list_processed_participants_sessions -使用 get_participants_sessions(data_stage="processed", ...) 相反

安装

先决条件

• Python 3.10或更高版本

选项1：安装软件包

# Clone the repository
git clone https://github.com/nipoppy/mcp.git
cd mcp

# Install dependencies
pip install -e .

[待发布]选项2:Docker容器

您还可以使用GitHub容器注册表中的预构建Docker容器：

# Pull the latest version
docker pull ghcr.io/bcmcpher/nipoppy-mcp:latest

# Pull a specific version
docker pull ghcr.io/bcmcpher/nipoppy-mcp:v0.1.0

用法

运行MCP服务器

服务器可以根据您的用例以不同的模式运行：

1.STDIO模式（适用于Claude desktop等本地桌面应用程序）

# Set the dataset root (optional, defaults to current directory)

# Run the server
python -m nipoppy_mcp.server

[待定]2。Docker模式

# Run with local dataset mounted
docker run -v /path/to/your/nipoppy/dataset:/data ghcr.io/bcmcpher/nipoppy-mcp:latest

# Run with specific version and custom dataset path
docker run \
  -v /path/to/dataset:/data \
  -e NIPOPPY_DATASET_ROOT=/data \
  ghcr.io/bcmcpher/nipoppy-mcp:v0.1.0

2.使用克劳德桌面/OpenCode进行配置

添加到您的Claude Desktop配置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
	"nipoppy": {
	  "command": "python",
	  "args": ["-m", "nipoppy_mcp.server"]
	}
  }
}

使用工具和资源

连接到MCP兼容客户端后，您可以通过自动上下文和显式工具调用访问Nipoppy数据集信息。

设置数据集根： 服务器需要 NIPOPPY_DATASET_ROOT 为资源工作设置的环境变量：

export NIPOPPY_DATASET_ROOT=/path/to/your/nipoppy/dataset

查询示例：

数据集概述（使用工具）

• “获取有关此数据集的信息”
• “此数据集中有多少参与者和会话？”
• “安装了哪些管道，它们的状态如何？”

参与者/会话查询（使用工具）

• “列出数据集中的所有参与者和会话”
• “向我展示具有成像数据的参与者”
• “哪些参与者已经完成了fMRIPrep处理？”
• “获取BIDS转换数据的参与者”

导航和配置（使用工具）

• “导航到fMRIPrep输出目录”
• “显示最新MRIQC管道的配置”
• “获取衍生品目录的路径”

上下文访问（使用资源）

• 服务器通过资源自动提供上下文，因此您可以询问：
  • “此数据集的全局配置是什么？”
  • “显示数据集清单”
  • “数据的管理状态如何？”
  • “获取BIDS数据集描述”

管道信息（使用资源）

• “获取fMRIPrep 23.2.0版本的配置”
• “显示MRIQC管道的精品店描述符”

发展

运行测试

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Or run basic import tests
python -c "from nipoppy_mcp.server import mcp; print('✅ MCP server imports successfully')"

测试实施

重构的实现包括全面的错误处理和验证。测试：

# Test basic functionality
python -c "
from nipoppy_mcp.server import get_participants_sessions, get_dataset_info, navigate_dataset
print('✅ Refactored tools imported successfully')

# Test validation (these should raise appropriate errors)
get_participants_sessions('/fake/path', data_stage='invalid_stage')
navigate_dataset('/fake/path', path_type='invalid_type')
"

# Test resource functions
python -c "
from nipoppy_mcp.server import get_dataset_config, get_dataset_manifest
print('✅ Resource functions imported successfully')
"

项目结构

nipoppy-mcp/
├── nipoppy_mcp/
│   ├── __init__.py
│   └── server.py          # Main MCP server implementation
│                          # - 8 MCP resources (automatic context)
│                          # - 3 refactored tools (unified interface)
│                          # - 7 deprecated tools (backward compatibility)
├── tests/                 # Test files
├── pyproject.toml        # Project configuration
└── README.md

实现细节

重构后的服务器提供：

• 8 MCP资源：数据集元数据、配置和状态的自动上下文加载
• 3统一工具：用统一界面替换7个以前的专用工具
• 7废弃工具：保持与弃用警告的向后兼容性
• 严格验证：全面的错误处理和参数验证
• 类型安全：完整类型提示和结构化数据返回

迁移指南

对于从旧工具迁移的现有用户：

示例用法

存储库包括 example_usage.py 演示重构后的功能：

# Set your dataset path
export NIPOPPY_DATASET_ROOT=/path/to/your/nipoppy/dataset

# Run the example
python example_usage.py

此脚本演示：

• 增强的数据集信息检索
• 按数据阶段统一参与者/会话过滤
• 数据集导航和路径解析
• 错误处理和验证

资源快速入门

要立即访问数据集信息（需要NIPOPPY_dataset_ROOT）：

import os
os.environ['NIPOPPY_DATASET_ROOT'] = '/path/to/dataset'

from nipoppy_mcp.server import get_dataset_config

# Resources are available as direct function calls
config = get_dataset_config()  # Auto-loads from environment variable
print(f"Dataset has {len(config['installed_pipelines'])} pipelines")

贡献

欢迎投稿！这是Brainhack 2026项目。请随时提交问题和拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

Docker镜像信息

当标记新版本时，Docker容器会自动构建并发布到GitHub容器注册表（GHCR）：

• 注册表: ghcr.io/bcmcpher/nipoppy-mcp
• 建筑：多平台（linux/amd64、linux/arm64）
• 标签:
  • latest -指向最新版本
  • v0.1.0 -完整语义版本
  • v0.1 -次要版本
  • v0 -主要版本

从源头构建

# Build the Docker image locally
docker build -t nipoppy-mcp .

# Run the locally built image
docker run -v /path/to/dataset:/data nipoppy-mcp

资源

• Nipoppy文件
• Nipoppy GitHub
• 模型上下文协议
• MCP Python SDK