SciSpark Client MCP

这是一个基于 Model Context Protocol (MCP) 的客户端工具，用于连接和交互 SciSpark 研究平台。它允许 AI 助手（如 Claude）直接提交研究任务、监控进度并下载研究成果。

✨ 功能特性

本 MCP 服务器提供以下四个核心工具：

• submit_research_task: 提交新的研究主题，启动自动化研究流程
• list_local_tasks: 查看本地记录的所有任务及其状态
• check_remote_status: 查询远程服务器的实时任务状态
• download_task_result: 下载并解压已完成任务的研究成果，支持自定义下载目录和工作区目录

🚀 快速开始

环境要求

• Python 3.12+
• pip、uv 或 uvx (推荐)

安装方式

方式1：从 PyPI 安装（推荐）

# 安装 scispark-client
pip install scispark-client

# 运行服务器
scispark-client

方式2：使用 uvx（推荐）

# 运行STDIO模式（默认）
uvx scispark-client

# 运行HTTP模式
uvx scispark-client-http --host 0.0.0.0 --port 3024

# 运行SSE模式
uvx scispark-client-sse --host 127.0.0.1 --port 3024

方式3：从源码安装

# 克隆项目
git clone https://github.com/your-repo/scispark_client.git
cd scispark_client

# 安装依赖
uv sync

# 运行服务器
uv run scispark-client

配置选项

通过环境变量进行配置：

# SSL 控制（开发环境推荐禁用）
export SSL_VERIFY=false

# 服务器配置
export MCP_SERVER_HOST=coze.tashan.ac.cn
export MCP_SERVER_PORT=8000
export MCP_SSE_URL=https://coze.tashan.ac.cn/scispark/sse

# 本地存储配置
export SCISPARK_WORKSPACE_DIR=./workspace
export SCISPARK_DOWNLOAD_DIR=./downloads

📁 下载目录 vs 工作区目录

download_task_result 工具支持两个重要的目录参数，它们有不同的用途：

🔽 下载目录 (download_dir)

• 用途: 存储原始ZIP压缩文件
• 默认位置: src/scispark_client/downloads/
• 存储内容: 从服务器下载的 task_id.zip 文件
• 生命周期: 可长期保留，作为备份

📂 工作区目录 (workspace_dir)

• 用途: 存储解压后的研究成果文件
• 默认位置: src/scispark_client/workspace/
• 存储内容: 解压后的研究文档、数据、图片等
• 目录结构: workspace_dir/task_id/

使用示例：

# 使用默认配置
# ZIP文件: src/scispark_client/downloads/12345.zip
# 解压内容: src/scispark_client/workspace/12345/

# 使用自定义配置
download_task_result(
    task_id="12345",
    download_dir="/tmp/my_downloads",
    workspace_dir="/home/user/my_workspace"
)
# ZIP文件: /tmp/my_downloads/12345.zip
# 解压内容: /home/user/my_workspace/12345/

运行模式

支持三种传输协议：

1. STDIO 模式（默认）

uv run scispark-client

2. HTTP 模式

uv run scispark-client-http --host 0.0.0.0 --port 3024

3. SSE 模式

uv run scispark-client-sse --host 127.0.0.1 --port 3024

🔧 Claude Desktop 集成

编辑 Claude Desktop 配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scispark-client": {
      "command": "uvx",
      "args": [
        "scispark-client"
      ]
    }
  }
}

📁 项目结构

scispark_client/
├── src/
│   └── scispark_client/
│       ├── __init__.py          # 包初始化
│       ├── server.py           # MCP 服务器实现和工具定义
│       └── config.py           # 配置管理和核心业务逻辑
├── workspace/                  # 研究成果存储目录
├── downloads/                  # 原始下载文件存储
├── pyproject.toml             # 项目配置和依赖
└── README.md                  # 项目文档

核心组件

• SciSparkConfig: 配置管理，支持环境变量覆盖
• AsyncMCPClient: MCP 客户端封装，支持SSL控制和URL重写
• TaskOrchestrator: 任务编排器，处理远程通信和状态管理
• TaskStore: 本地任务数据存储，使用JSON格式

🛠️ 开发

代码质量

项目使用以下工具保证代码质量：

# 代码格式化和检查
uvx run ruff check . --fix
uvx run black .

测试

HTTP模式测试：

# 启动服务器
SSL_VERIFY=false nohup uvx run scispark-client-http &

# 测试工具调用
curl -X POST http://localhost:3024/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

🔄 版本历史

v0.1.4 (质量优化版本)

• ✅ 修复 download_task_result 工具的 MCP 响应解析问题
• ✅ 改进嵌套 CallToolResult 格式的处理能力
• ✅ 增强下载功能的稳定性和兼容性
• ✅ 通过 ruff 代码质量检查，优化代码格式
• ✅ 完善多传输模式下的下载功能测试

v0.1.3 (功能优化版本)

• ✅ 删除冗余的下载工具，只保留一个功能完整的 download_task_result
• ✅ 完善 README.md 文档，详细说明下载目录和工作区目录的区别
• ✅ 优化工具参数说明，提供清晰的使用示例
• ✅ 改进用户体验，简化工具选择

v0.1.2 (代码清理版本)

• ✅ 清理项目中所有关于"重构"的冗余注释和说明
• ✅ 删除临时测试文件和冗余脚本
• ✅ 优化代码格式，通过ruff质量检查
• ✅ 统一版本号配置，确保一致性

v0.1.1 (命名优化版本)

• ✅ 优化包名和命令名统一为 scispark-client
• ✅ 简化 uvx 使用方式：直接使用 uvx scispark-client
• ✅ 改进用户体验，消除命名混淆

v0.1.0 (初始版本)

• ✅ 基于 FastMCP 2.13.2 构建的纯MCP服务器
• ✅ 升级到 Python 3.12
• ✅ 简化架构，专注核心MCP工具功能
• ✅ 添加多传输协议支持 (STDIO/SSE/HTTP)
• ✅ 修复SSL证书问题，支持开发环境
• ✅ 优化代码质量，符合现代Python规范
• ✅ 实现四个核心MCP工具：任务提交、状态查询、任务列表、结果下载
• ✅ 发布到 PyPI (https://pypi.org/project/scispark-client/)
• ✅ 支持 uvx 一键运行

📦 PyPI

• PyPI 项目页面: https://pypi.org/project/scispark-client/
• 包下载统计: https://pypi.org/pypi/scispark-client/json

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请通过 GitHub Issues 联系我们。