Metadata-Version: 2.4
Name: scispark-client
Version: 0.1.1
Summary: 基于 Model Context Protocol (MCP) 的研究任务管理服务器
Project-URL: Homepage, https://github.com/scispark/scispark-client
Project-URL: Repository, https://github.com/scispark/scispark-client
Project-URL: Documentation, https://github.com/scispark/scispark-client#readme
Project-URL: Issues, https://github.com/scispark/scispark-client/issues
Author-email: SciSpark Team <team@scispark.ai>
License-Expression: MIT
Keywords: ai,mcp,research,scispark,server
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.13.2
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.1.1
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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 <repository-url>
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
```

### 运行模式

支持三种传输协议：

#### 1. STDIO 模式（默认）
```bash
uv run scispark-client
# 或
uv run python -m scispark_client.server
```

#### 2. HTTP 模式
```bash
uv run scispark-client-http
# 或自定义
uv run python -m scispark_client.server --transport streamable-http --host 0.0.0.0 --port 3024
```

#### 3. SSE 模式
```bash
uv run scispark-client-sse
# 或
uv run python -m scispark_client.server --transport 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 .
uvx run mypy .
```

### 测试

HTTP模式测试：

```bash
# 启动服务器
SSL_VERIFY=false nohup uvx run python -m scispark_client.server --transport streamable-http --host 0.0.0.0 --port 3024 &

# 测试工具调用
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.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 联系我们。
