scispark-client 0.1.1

基于 Model Context Protocol (MCP) 的研究任务管理服务器

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

运行模式

支持三种传输协议：

1. STDIO 模式（默认）

uv run scispark-client
# 或
uv run python -m scispark_client.server

2. HTTP 模式

uv run scispark-client-http
# 或自定义
uv run python -m scispark_client.server --transport streamable-http --host 0.0.0.0 --port 3024

3. SSE 模式

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

{
  "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 .
uvx run mypy .

测试

HTTP模式测试：

# 启动服务器
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

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

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