内容
# sparkit-mcp
SPARKIT 的 MCP 服务器 — 从 Claude Desktop、Cursor、Claude Code 或任何其他 MCP 兼容的客户端调用科学研究代理。
提供了两个工具：
- **`research`** — 提交一个科学问题。SPARKIT 搜索文献，阅读相关论文，并返回一个带有引用的 Markdown 报告。在作业完成之前阻塞（默认 4 分钟），并将完整的报告内联返回。
- **`get_job_status`** — 通过 ID 获取以前提交的作业。在 `research` 返回之前作业未完成时，或重新访问过去的报告时很有用。
## 安装
```bash
uv tool install sparkit-mcp
```
或使用 pip：
```bash
pip install sparkit-mcp
```
两者都安装了一个 `sparkit-mcp` 控制台脚本。（预发布：直接从 GitHub 安装
``uv tool install "git+https://github.com/SPARKIT-science/sparkit-mcp.git"``
直到第一个 PyPI 版本发布。）
## 获取 API 密钥
1. 在 https://app.sparkit.science/signup 注册（Try-it 费用为 10 美元，限 5 次查询；订阅起价为 50 美元/月）。
2. 访问 https://app.sparkit.science/keys 并创建密钥。
3. 复制密钥 — 它只显示一次。
## 配置您的 MCP 客户端
### Claude Desktop
编辑 `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
添加：
```json
{
"mcpServers": {
"sparkit": {
"command": "sparkit-mcp",
"env": {
"SPARKIT_API_KEY": "sk_sparkit_..."
}
}
}
}
```
重启 Claude Desktop。你应该会在聊天输入框旁边的工具图标中看到 `sparkit`。
如果 `sparkit-mcp` 不在 Claude Desktop 的 PATH 上（通常使用 `uv tool` 时会出现这种情况），
请使用绝对路径：
```json
"command": "/Users/you/.local/bin/sparkit-mcp"
```
（在 `uv tool install` 后使用 `which sparkit-mcp` 查找路径。）
### Cursor
编辑 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"sparkit": {
"command": "sparkit-mcp",
"env": {
"SPARKIT_API_KEY": "sk_sparkit_..."
}
}
}
}
```
重新加载 Cursor（`Cmd+Shift+P` → "Reload Window"）。
### Claude Code
```bash
claude mcp add sparkit -e SPARKIT_API_KEY=sk_sparkit_... -- sparkit-mcp
```
## 试用
配置完成后，询问 LLM：
> 使用 SPARKIT 查询 WRNIP1 作为癌症合成致死靶点的最新文献。
LLM 将调用 `research`。预计等待 60-180 秒，然后是带有内联引用的 Markdown 报告和编号的来源列表。
## 配置
| 环境变量 | 默认值 | 描述 |
|-------------------------------|------------------------------------------------------|-------------|
| `SPARKIT_API_KEY` | （必填） | https://app.sparkit.science/keys 的 Bearer 密钥。 |
| `SPARKIT_API_BASE` | `https://jlsteenwyk--sparkit-api-web.modal.run` | 覆盖 API 基本 URL。对于分段或自托管部署很有用。 |
| `SPARKIT_API_TIMEOUT_SECONDS` | `30` | 每 HTTP 请求超时。不影响 `research` 的总等待时间；那是 `max_wait_seconds`。 |
## 工具参考
### `research(question, response_format?, include_citations?, max_wait_seconds?)`
| 参数 | 类型 | 默认值 | 描述 |
|--------------------|---------------------|---------|-------------|
| `question` | 字符串 | — | 科学问题。必填。具体一些。 |
| `response_format` | `"full"` 或 `"brief"` | `"full"` | 返回的 Markdown 报告长度。 |
| `include_citations`| 布尔值 | `true` | 保留 `true` 以获取来源报告。 |
| `max_wait_seconds` | 整数（30-540） | `240` | 在返回 job_id 并提供轮询指令之前阻塞等待的最长时间。 |
返回 Markdown。如果超时，则返回包含 job_id 的状态行，以便 LLM 稍后可以调用 `get_job_status`。
### `get_job_status(job_id)`
如果作业已完成，则返回引用的 Markdown 报告；如果作业仍在运行，则返回状态行；否则返回错误消息。
## 故障排除
**身份验证失败** — `SPARKIT_API_KEY` 未设置或无效。
在编辑后检查 `claude_desktop_config.json` 是否有拼写错误；重启 Claude Desktop。
**配额耗尽** — 每月查询数 / Try-it 积分用完。访问 https://app.sparkit.science/billing。
**工具未出现在 Claude Desktop 中** — 检查 Claude Desktop 日志：
- macOS: `~/Library/Logs/Claude/mcp-server-sparkit.log`
- Windows: `%LOCALAPPDATA%\Claude\Logs\mcp-server-sparkit.log`
最常见的问题是 `command: sparkit-mcp` 不在 PATH 上；
使用 `which sparkit-mcp` 替换绝对路径。
**作业超时** — `max_wait_seconds` 限制为 540 秒（9 分钟）。对于非常深入的问题，
提交后轮询 `get_job_status` 而不是内联等待。 SPARKIT 还会自动取消超过其内部限制的作业。
## 许可证
MIT。
