Suppr-MCP (超能文献)

# **Suppr MCP - README.md**

```markdown
# Suppr MCP

---

## Overview

**Suppr MCP** is a Model Context Protocol (MCP) server that provides professional document translation and academic literature search capabilities. Built by the [WildData](https://wilddata.cn) team, it enables AI assistants to translate documents across 11 languages and search PubMed literature databases seamlessly.

## Features

### 📄 **Intelligent Document Translation**
- **Multi-format support**: PDF, DOCX, PPTX, XLSX, HTML, TXT, EPUB
- **11 languages**: English, Chinese, Japanese, Korean, French, German, Spanish, Russian, Arabic, Portuguese, Italian
- **Mathematical formula optimization**: Special handling for academic papers with complex equations
- **Batch processing**: Asynchronous task queue for multiple documents
- **Translation history**: Track and manage all translation tasks

### 🔍 **Academic Literature Search**
- **AI-driven search**: Semantic understanding for precise literature discovery
- **PubMed integration**: Direct access to biomedical research database
- **Rich metadata**: Returns title, abstract, authors, DOI, PMID, publication info
- **Smart filtering**: Auto-select most relevant results

---

## Quick Start

### One-Click Install (Cursor)

Click the button below to install Suppr MCP in Cursor:

[](cursor://anysphere.cursor-deeplink/mcp/install?name=suppr&config=ewogICJjb21tYW5kIjogIm5weCIsCiAgImFyZ3MiOiBbIi15IiwgInN1cHByLW1jcCJdLAogICJlbnYiOiB7CiAgICAiU1VQUFJfQVBJX0tFWSI6ICIiCiAgfQp9)

After installation:
1. Get your API key from [https://suppr.wilddata.cn/api-keys](https://suppr.wilddata.cn/api-keys)
2. Open Cursor Settings → **MCP** → Find **"suppr"** → Add your API key to `SUPPR_API_KEY`

---

## Installation

### Prerequisites
- Node.js >= 18.0.0
- A Suppr API key (get one at [https://suppr.wilddata.cn/api-keys](https://suppr.wilddata.cn/api-keys))

### Method 1: NPX (Recommended)

Add to your MCP client configuration:

```json
{
"mcpServers": {
"suppr": {
"command": "npx",
"args": ["-y", "suppr-mcp"],
"env": {
"SUPPR_API_KEY": "your_api_key_here"
}
}
}
}
```

### Method 2: Global Installation

```bash
npm install -g suppr-mcp
```

Configuration:
```json
{
"mcpServers": {
"suppr": {
"command": "suppr-mcp",
"env": {
"SUPPR_API_KEY": "your_api_key_here"
}
}
}
}
```

### Method 3: Claude Desktop

For macOS, edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
"mcpServers": {
"suppr": {
"command": "npx",
"args": ["-y", "suppr-mcp"],
"env": {
"SUPPR_API_KEY": "your_api_key_here"
}
}
}
}
```

For Windows, edit `%APPDATA%\Claude\claude_desktop_config.json` with the same configuration.

---

## Tools

Suppr MCP provides 4 powerful tools:

### 1. `create_translation`
Create a document translation task.

**Parameters:**
- `file_path` (optional): Local file path
- `file_url` (optional): Remote file URL
- `to_lang` (required): Target language code (e.g., `"en"`, `"zh"`, `"ja"`)
- `from_lang` (optional): Source language code (default: `"auto"` for auto-detection)
- `optimize_math_formula` (optional): Optimize mathematical formulas (boolean)

**Example:**
```json
{
"file_url": "https://example.com/research-paper.pdf",
"to_lang": "en",
"from_lang": "zh",
"optimize_math_formula": true
}
```

**Returns:**
```json
{
"task_id": "02a6c6d1-3f70-4a5a-80bc-971d53a37bb1",
"status": "INIT",
"consumed_point": 453,
"source_lang": "zh",
"target_lang": "en"
}
```

---

### 2. `get_translation`
Query translation task status and retrieve results.

**Parameters:**
- `task_id` (required): Translation task ID

**Example:**
```json
{
"task_id": "02a6c6d1-3f70-4a5a-80bc-971d53a37bb1"
}
```

**Returns:**
```json
{
"task_id": "02a6c6d1-3f70-4a5a-80bc-971d53a37bb1",
"status": "DONE",
"progress": 1.0,
"source_file_url": "https://example.com/source.pdf",
"target_file_url": "https://example.com/translated.pdf",
"error_msg": null
}
```

**Status codes:**
- `INIT`: Task initialized
- `PROGRESS`: Processing
- `DONE`: Completed
- `ERROR`: Failed

---

### 3. `list_translations`
List translation history.

**Parameters:**
- `offset` (optional): Pagination offset (default: 0)
- `limit` (optional): Number of results (default: 20)

**Example:**
```json
{
"offset": 0,
"limit": 10
}
```

---

### 4. `search_documents`
AI-powered academic literature search via PubMed.

**Parameters:**
- `query` (required): Search keywords
- `topk` (optional): Number of results (1-100, default: 20)
- `return_doc_keys` (optional): Fields to return (e.g., `["title", "abstract", "doi"]`)
- `auto_select` (optional): Auto-select best results (default: `true`)

**Example:**
```json
{
"query": "CRISPR gene editing mechanisms",
"topk": 5,
"return_doc_keys": ["title", "abstract", "authors", "doi"],
"auto_select": true
}
```

**Returns:**
```json
{
"search_items": [
{
"doc": {
"title": "CRISPR-Cas9 editing...",
"abstract": "...",
"authors": ["Smith J", "Doe A"],
"doi": "10.1234/example"
},
"search_gateway": "pubmed"
}
],
"consumed_points": 20
}
```

---

## Supported Languages

| Code | Language | Code | Language |
|------|----------|------|----------|
| `en` | English | `zh` | Chinese |
| `ja` | Japanese | `ko` | Korean |
| `fr` | French | `de` | German |
| `es` | Spanish | `ru` | Russian |
| `ar` | Arabic | `pt` | Portuguese |
| `it` | Italian | `auto` | Auto-detect |

---

## Usage Examples

### Example 1: Translate a Research Paper

```
User: "Translate this PDF to English: https://example.com/paper.pdf"

Assistant uses:
1. create_translation with file_url and to_lang="en"
2. Returns task_id
3. Periodically checks with get_translation
4. Provides download link when status="DONE"
```

### Example 2: Search Literature

```
User: "Find recent papers about quantum computing"

Assistant uses:
search_documents with query="quantum computing" and topk=10
Returns: List of relevant papers with titles, abstracts, and DOIs
```

---

## Error Handling

| Code | Message | Solution |
|------|---------|----------|
| **401** | Invalid API key | Check your `SUPPR_API_KEY` environment variable |
| **400** | Invalid parameters | Review parameter format and requirements |
| **404** | Task not found | Verify the task_id is correct |

---

## FAQ

### Q: How do I get an API key?
**A:** Visit [https://suppr.wilddata.cn/api-keys](https://suppr.wilddata.cn/api-keys) to generate your free API key.

### Q: What file formats are supported?
**A:** PDF, DOCX, PPTX, XLSX, HTML, TXT, and EPUB files.

### Q: How long does translation take?
**A:** Processing time varies by file size. Use `get_translation` to check progress.

### Q: Can I translate without uploading files?
**A:** Yes, provide a publicly accessible `file_url` instead of `file_path`.

### Q: Is there a file size limit?
**A:** Limits depend on your account tier. Check [API documentation](https://openapi.suppr.wilddata.cn/introduction) for details.

---

## Resources

- 🌐 **Web Platform**: [https://suppr.wilddata.cn](https://suppr.wilddata.cn)
- 📚 **API Documentation**: [https://openapi.suppr.wilddata.cn/introduction](https://openapi.suppr.wilddata.cn/introduction)
- 🔬 **PubMed Search**: [https://suppr.wilddata.cn/](https://suppr.wilddata.cn/)
- 🧪 **Deep Research**: [https://suppr.wilddata.cn/deep-research](https://suppr.wilddata.cn/deep-research)
- 🔌 **Zotero Plugin**: [https://github.com/WildDataX/suppr-zotero-plugin](https://github.com/WildDataX/suppr-zotero-plugin)

---

## Support

- **GitHub**: [https://github.com/WildDataX](https://github.com/WildDataX)
- **Email**: [[email protected]](mailto:[email protected])
- **Website**: [https://wilddata.cn](https://wilddata.cn)

---

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

```

---

## **额外提供的文件内容：**

### **package.json 示例** (如果需要)
```json
{
"name": "suppr-mcp",
"version": "1.0.0",
"description": "AI-powered document translation and academic literature search MCP server",
"keywords": [
"mcp",
"translation",
"academic",
"pubmed",
"research",
"ai"
],
"author": "WildData Team",
"license": "MIT",
"homepage": "https://github.com/WildDataX/suppr-mcp",
"repository": {
"type": "git",
"url": "https://github.com/WildDataX/suppr-mcp.git"
},
"bugs": {
"url": "https://github.com/WildDataX/suppr-mcp/issues"
}
}
```