scispark-client 0.1.4
基于 Model Context Protocol (MCP) 的研究任务管理服务器
Requires Python: >=3.12
Keywords: ai, mcp, research, scispark, server

# SciSpark Client MCP

[![PyPI version](https://img.shields.io/pypi/v/scispark-client.svg)](https://pypi.org/project/scispark-client/)
[![Python versions](https://img.shields.io/pypi/pyversions/scispark-client.svg)](https://pypi.org/project/scispark-client/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/pypi/dm/scispark-client.svg)](https://pypi.org/project/scispark-client/)

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

## ✨ 功能特性

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

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

## 🚀 快速开始

### 环境要求

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

### 安装方式

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

```bash
# 安装 scispark-client
pip install scispark-client

# 运行服务器
scispark-client
```

#### 方式2：使用 uvx（推荐）

```bash
# 运行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：从源码安装

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

# 安装依赖
uv sync

# 运行服务器
uv run scispark-client
```

### 配置选项

通过环境变量进行配置：

```bash
# 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/`

#### 使用示例：
```bash
# 使用默认配置
# 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 模式（默认）
```bash
uv run scispark-client
```

#### 2. HTTP 模式
```bash
uv run scispark-client-http --host 0.0.0.0 --port 3024
```

#### 3. SSE 模式
```bash
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`

```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格式

## 🛠️ 开发

### 代码质量

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

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

### 测试

HTTP模式测试：

```bash
# 启动服务器
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](LICENSE)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 支持

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