giisp-arxiv-search-mcp/README.md

MCP服务器用于通过标题搜索arXiv论文

# Giiisp arXiv搜索 MCP 服务器

[![npm version](https://badge.fury.io/js/giisp-arxiv-search-mcp.svg)](https://badge.fury.io/js/giisp-arxiv-search-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/giisp-arxiv-search-mcp)](https://nodejs.org/)

一个基于模型上下文协议（MCP）的服务器，用于通过标题搜索arXiv论文。该包通过MCP协议为AI助手和研究工具提供无缝集成。

## ✨ 功能特性

- 🔍 **智能论文搜索** - 通过标题搜索arXiv论文数据库
- ⚡ **快速响应** - 30秒超时，性能优化
- 🛡️ **健壮的错误处理** - 全面的错误管理
- 📊 **详细日志记录** - 便于调试的日志系统
- 🔧 **简单集成** - 简洁的MCP协议实现
- 🌍 **多语言支持** - 支持中英文搜索
- 📄 **灵活分页** - 可自定义返回数据数量

## 🚀 快速开始

### 安装

```bash
npm install -g giisp-arxiv-search-mcp
```

### 使用方式

#### 作为全局命令

```bash
giisp-arxiv-search
```

#### 作为MCP服务器

服务器将启动并通过stdio监听MCP协议消息。

#### 与Claude Desktop集成

要在Claude Desktop中使用此MCP服务器，请将以下内容添加到您的Claude Desktop配置文件中：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "giisp-arxiv-search": {
      "command": "npx",
      "args": ["-y", "giisp-arxiv-search-mcp"]
    }
  }
}
```

添加此配置后，重启Claude Desktop，您就可以通过MCP界面直接搜索arXiv论文了。

### 开发安装

```bash
git clone https://github.com/giisp/giisp-arxiv-search-mcp.git
cd giisp-arxiv-search-mcp
npm install
npm start
```

## 📖 使用说明

### MCP工具集成

服务器提供一个`searchArxivByTitle`工具用于搜索arXiv论文：

**参数：**
- `key` (string, 必需): 搜索关键词（论文标题）
- `pageSize` (number, 可选): 返回数据数量，默认为10

**示例：**

基本搜索：
```json
{
  "name": "searchArxivByTitle",
  "arguments": {
    "key": "artificial intelligence"
  }
}
```

带分页的搜索：
```json
{
  "name": "searchArxivByTitle",
  "arguments": {
    "key": "machine learning",
    "pageSize": 20
  }
}
```

**响应格式：**
```json
{
  "success": true,
  "status": 200,
  "data": {
    // API响应数据，包含论文信息
  },
  "message": "arXiv论文搜索完成"
}
```

## 🔧 技术细节

- **超时时间**: 30秒
- **请求头**: 自动设置Content-Type和User-Agent
- **错误处理**: 区分网络、API和超时错误
- **日志记录**: 详细的请求和响应日志

## 🛠️ 错误处理

服务器处理以下错误类型：

- **超时错误**: 请求超过30秒
- **网络错误**: 无法连接到API服务器
- **API错误**: 服务器返回错误状态码
- **参数错误**: 缺少必需参数或类型错误

## 🧪 测试

运行测试套件：

```bash
npm test
```

这将测试：
- API连接性
- 参数验证
- 错误处理

## 📁 项目结构

```
├── server.js              # 主服务器文件
├── package.json           # 项目配置和依赖
├── README.md             # 项目文档
├── LICENSE               # MIT许可证
└── test/
    └── test-api.js       # 测试套件
```

## 🚀 开发

### 调试模式

使用Node.js调试器运行调试模式：

```bash
npm run dev
```

在调试器中设置断点进行开发。

### 贡献

1. Fork仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 提交拉取请求

## 📄 许可证

MIT许可证 - 详见[LICENSE](LICENSE)文件。

## 🤝 支持

- **问题反馈**: [GitHub Issues](https://github.com/giisp/giisp-arxiv-search-mcp/issues)
- **邮箱**: contact@giisp.com

## 🔗 相关链接

- [Giiisp数据库](https://giiisp.com)
- [模型上下文协议](https://modelcontextprotocol.io)
- [npm包](https://www.npmjs.com/package/giisp-arxiv-search-mcp)