# AMiner MCP Server

[English](README.md) | [中文](README_CN.md)

> 💡 **Core Advantage: Free Academic Data Access**
> 
> Currently, AMiner's core search interfaces (Scholar, Paper, and Patent Search) are **free to use**. This allows you to integrate massive global research data into your AI workflow with zero API costs, making it the most cost-effective solution for academic automation.

This directory provides a Model Context Protocol (MCP) server for accessing AMiner's open platform API.

## Quick Install

### Installation

```bash
pip install -e .
```

### Configuration

Set your AMiner API token as an environment variable:

**Windows (PowerShell)**:
```powershell
$env:AMINER_TOKEN="your_token_here"
```

**Linux/Mac**:
```bash
export AMINER_TOKEN="your_token_here"
```

Or create a `.env` file in your project root:
```
AMINER_TOKEN=your_token_here
```

### Usage

Run the server:
```bash
python -m aminer_mcp
```

Or use the command-line shortcut:
```bash
aminer-mcp
```

## Features

- **Scholar Search**: Find researchers by name or organization.
- **Paper Search**: Find papers by title.
- **Patent Search**: Search patents by keywords.

## Setup

1. **Install Dependencies**:
   ```bash
   pip install "mcp[cli]" requests
   ```

2. **Get API Token**:
   - Register at [AMiner Open Platform](https://www.aminer.cn/open/board?tab=control).
   - Generate your API Key/Token.

3. **Configure Environment**:
   You can either set the `AMINER_TOKEN` environment variable manually or use the provided `.env` file.
   
   **Option A: Using .env (Recommended)**
   A `.env` file has been created for you with your token. The server will automatically load it.
   
   **Option B: Manual Environment Variable**
   
   **Windows (PowerShell)**:
   ```powershell
   $env:AMINER_TOKEN="your_token_here"
   ```
   
   **Linux/Mac**:
   ```bash
   export AMINER_TOKEN="your_token_here"
   ```

## Running the Server

You can run the server directly or use it with an MCP client (like Claude Desktop or generic IDEs).

### Quick Start (Recommended)

For a guided startup experience with environment and dependency checks:

**Windows**:
```powershell
.\start_server.ps1
```

**Linux/Mac**:
```bash
chmod +x start_server.sh
./start_server.sh
```

### Direct Run (stdio)

```bash
python server.py
```

### Inspecting with MCP CLI

You can use the MCP CLI to inspect and test the server.

```bash
mcp dev server.py
```

## Tools Available

1.  **search_scholar**:
    *   `name`: Scholar name.
    *   `org`: Organization.
    *   `offset`: Pagination offset.
    *   `size`: Result count.

2.  **search_paper**:
    *   `title`: Paper title.
    *   `page`: Page number.
    *   `size`: Result count.

3.  **search_patent**:
    *   `query`: Search query.
    *   `page`: Page number.
    *   `size`: Result count.

4.  **get_papers_by_ids**:
    *   `ids`: Comma-separated list of paper IDs.

5.  **search_paper_pro** (0.01 CNY/call):
    *   **Fallback Tool**: Use only when strictly necessary.
    *   `title`, `keyword`, `author`, `page`, `size`.

## API References

*   Scholar Search: [Docs](https://www.aminer.cn/open/docs?id=671a19a46e728a29db292f73)
*   Paper Search: [Docs](https://www.aminer.cn/open/docs?id=64f03e746221825d961dbde4)
*   Paper Search Pro: [Docs](https://www.aminer.cn/open/docs?id=66471a81d0efa2bb8d4e8c08)
*   Patent Search: [Docs](https://www.aminer.cn/open/docs?id=64f03bf46221825d961dbde3)
*   Paper Info: [Docs](https://www.aminer.cn/open/docs?id=64f0386a6221825d961dbde2)

## Configuration for Cursor IDE

To use this MCP server in Cursor editor, add the following configuration:

**Windows (Cursor config path: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`)**:

```json
{
  "mcpServers": {
    "aminer": {
      "command": "python",
      "args": ["-m", "aminer_mcp"],
      "env": {
        "AMINER_TOKEN": "<YOUR_AMINER_TOKEN>"
      }
    }
  }
}
```

**Linux/Mac**:

```json
{
  "mcpServers": {
    "aminer": {
      "command": "python3",
      "args": ["-m", "aminer_mcp"],
      "env": {
        "AMINER_TOKEN": "<YOUR_AMINER_TOKEN>"
      }
    }
  }
}
```

**Note**: Replace `<YOUR_AMINER_TOKEN>` with your actual AMiner API token from [AMiner Open Platform](https://www.aminer.cn/open/board?tab=control).

## Contributing

Issues and Pull Requests are welcome!

## Usage as an Agent Skill

This repository also includes an Agent Skill definition, allowing AI agents (like Cursor's Agent) to use AMiner search capabilities directly without a full MCP server setup for local tasks.

**Skill Location**: `.agent/skills/aminer-search/`

### How it works
The skill wraps the AMiner client code into a simple CLI tool that agents can invoke to perform searches.

### Prerequisite
Ensure the `AMINER_TOKEN` environment variable is set in your terminal or `.env` file.

### Skill Capabilities
- **Paper Search**: `python .agent/skills/aminer-search/scripts/search_tool.py paper --title "..."`
- **Scholar Search**: `python .agent/skills/aminer-search/scripts/search_tool.py scholar --name "..."`
- **Patent Search**: `python .agent/skills/aminer-search/scripts/search_tool.py patent --query "..."`

Agents detecting this skill will automatically know how to use these commands to fetch academic data for you.

## License

MIT License