tashan-scispark 1.0.8
TaShan SciSpark - Academic Research Assistant MCP Server
License: MIT
Requires Python: >=3.10
Keywords: mcp, academic, research, papers, ai, assistant, arxiv, claude

# TaShan SciSpark

TaShan SciSpark 是一个强大的学术研究助手，基于 MCP (Model Context Protocol) 协议构建，为研究人员提供全面的论文分析和研究支持服务。

## 🌟 核心功能

- 🔍 **论文搜索**: 基于关键词的学术论文检索，支持多个学术数据库
- 🏷️ **关键词提取**: 从文本中智能提取技术关键词和研究要点
- 💡 **研究想法生成**: AI驱动的研究创意生成，帮助发现新的研究方向
- 📝 **研究评审**: 专业的研究想法评估和改进建议
- 📄 **论文压缩**: 学术论文内容的智能摘要和核心信息提取
- 🤖 **MCP集成**: 完全兼容Claude Desktop，提供无缝的AI助手体验

## 🚀 快速开始

### 使用 uvx 安装和运行（推荐）

uvx 是一个现代的 Python 包管理工具，可以直接运行 Python 应用程序而无需手动安装。

#### 安装 uvx

```bash
# 使用 pip 安装 uvx
pip install uvx

# 或使用 pipx 安装
pipx install uvx
```

#### 直接运行 TaShan SciSpark

```bash
# 启动 MCP 服务器（STDIO 传输，用于 Claude Desktop）
uvx tashan-scispark mcp

# 启动 MCP 服务器（HTTP 传输）
uvx tashan-scispark mcp --transport http --port 8000

# 启动 Celery 工作进程
uvx tashan-scispark worker

# 显示版本信息
uvx tashan-scispark --version

# 显示帮助信息
uvx tashan-scispark --help
```

### 传统安装方式

#### 从源码安装

```bash
# 克隆仓库
git clone https://github.com/tashan-scispark/tashan-scispark.git
cd tashan-scispark

# 安装依赖
pip install -e .

# 运行服务器
tashan-scispark mcp
```

#### 使用 pip 安装

```bash
# 从 PyPI 安装（即将支持）
pip install tashan-scispark

# 运行服务器
tashan-scispark mcp
```

## 🔧 配置

### 环境变量

创建 `.env` 文件并配置以下环境变量：

```env
# API 密钥配置
QWEN_API_TOKEN=your_qwen_api_token
DEEPSEEK_API_KEY=your_deepseek_api_key

# Redis 配置（用于 Celery）
REDIS_URL=redis://localhost:6379/0

# 输出路径配置
OUTPUT_PATH=./output
```

### Claude Desktop 集成

如果使用 STDIO 传输模式，需要在 Claude Desktop 配置文件中添加：

```json
{
  "mcpServers": {
    "tashan-scispark": {
      "command": "uvx",
      "args": ["tashan-scispark", "mcp"],
      "env": {
        "QWEN_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

## 📖 使用方法

### 命令行界面

```bash
# 基本用法
tashan-scispark mcp                    # 启动 MCP 服务器
tashan-scispark worker                 # 启动 Celery 工作进程
tashan-scispark --version              # 显示版本信息

# MCP 服务器选项
tashan-scispark mcp --transport stdio  # STDIO 传输（默认）
tashan-scispark mcp --transport http   # HTTP 传输
tashan-scispark mcp --host 0.0.0.0     # 指定主机地址
tashan-scispark mcp --port 8080        # 指定端口

# 详细日志
tashan-scispark -v mcp                 # 启用详细日志输出
```

### Python 模块方式

```python
# 作为 Python 模块运行
python -m tashan_scispark mcp

# 在代码中使用
from tashan_scispark import run_mcp_server
run_mcp_server()
```

### MCP 工具函数

通过 Claude Desktop 或其他 MCP 客户端，您可以使用以下工具：

- `search_papers(keyword, limit)` - 搜索学术论文
- `extract_keywords(text)` - 提取关键词
- `generate_research_idea(keyword, paper_count)` - 生成研究想法
- `review_research_idea(topic, draft)` - 评审研究想法
- `compress_paper_content(title, abstract, content)` - 压缩论文内容
- `get_task_status(task_id)` - 获取任务状态
- `get_server_info()` - 获取服务器信息

## 🏗️ 项目结构

```
tashan-scispark/
├── tashan_scispark/           # 主包目录
│   ├── __init__.py           # 包初始化
│   ├── __main__.py           # 模块入口点
│   ├── cli.py                # 命令行接口
│   ├── mcp_server.py         # MCP 服务器实现
│   ├── celery_worker.py      # Celery 工作进程
│   ├── research_engine.py    # 研究引擎核心
│   └── app/                  # 应用模块
│       ├── api/              # API 接口
│       ├── core/             # 核心功能
│       ├── task/             # 任务处理
│       └── utils/            # 工具函数
├── pyproject.toml            # 项目配置
├── README.md                 # 项目说明
└── requirements_mcp.txt      # 依赖列表
```

## 🔄 开发模式

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/tashan-scispark/tashan-scispark.git
cd tashan-scispark

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码格式化
black tashan_scispark/
isort tashan_scispark/

# 类型检查
mypy tashan_scispark/
```

### 构建和发布

```bash
# 构建包
python -m build

# 发布到 PyPI（需要配置凭据）
python -m twine upload dist/*
```

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 支持

如果您遇到问题或有疑问：

- 📧 邮箱: support@tashan-scispark.com
- 🐛 问题反馈: [GitHub Issues](https://github.com/tashan-scispark/tashan-scispark/issues)
- 📖 文档: [项目文档](https://github.com/tashan-scispark/tashan-scispark#readme)

## 🙏 致谢

感谢所有为 TaShan SciSpark 项目做出贡献的开发者和研究人员！

## Python文件和编码规约

  - `.py` 文件编码为 `utf-8`
  

## Git 贡献提交规范

  - `feat` 增加新功能
  - `fix` 修复问题/BUG
  - `style` 代码风格相关无影响运行结果的
  - `perf` 优化/性能提升
  - `refactor` 重构
  - `revert` 撤销修改
  - `test` 测试相关
  - `docs` 文档/注释
  - `chore` 依赖更新/脚手架配置修改等
  - `ci` 持续集成
  - `types` 类型定义文件更改
  - `wip` 开发中

## 启动服务

### 启动 Celery Worker

#### 方式一：使用优化启动脚本（推荐）

**Windows系统：**
```bash
# 直接运行批处理文件
start_celery_worker.bat

# 或使用Python脚本
python start_celery_worker.py
```

**Linux/Mac系统：**
```bash
python start_celery_worker.py
```

#### 方式二：传统启动方式
```bash
python -m celery -A app.task.paper_assistant worker --pool=solo -l info
```

**注意：** 推荐使用方式一，它包含了内存优化配置，能够有效防止内存爆炸问题。

### MCP工具异步任务支持

**重要提醒：** 当使用MCP工具中的异步功能（如研究想法生成）时，必须先启动Celery Worker：

```bash
# 启动Celery Worker以支持异步任务
python start_celery_worker.py
```

**异步MCP工具包括：**
- `generate_research_idea` - 生成研究想法（需要Celery Worker支持）
- `get_task_status` - 获取异步任务状态

如果未启动Celery Worker，异步MCP工具将无法正常工作。建议在使用MCP服务器前先启动Celery Worker。