mcp-baidu-curl/README.md

一个MCP服务，提供获取百度网站HTML内容的功能，支持Cursor、Claude Desktop、Cherry Studio等主流MCP客户端

# 百度Curl MCP服务 🌐

[![npm version](https://badge.fury.io/js/mcp-baidu-curl.svg)](https://badge.fury.io/js/mcp-baidu-curl)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

这是一个标准的Model Context Protocol (MCP) 服务，使用Node.js和MCP SDK构建。该服务提供一个实用的功能：获取百度网站的HTML内容，非常适合作为MCP服务开发的学习示例。

## 🌟 功能特性

- 📡 **标准MCP协议**: 使用官方MCP SDK实现
- 🌐 **网络请求**: 支持获取百度网站的完整HTML内容
- ⚙️ **可配置参数**: 支持自定义超时时间和User-Agent
- 🛡️ **错误处理**: 完善的错误处理和状态反馈
- 📊 **详细信息**: 返回响应状态、头信息等详细数据
- 🔧 **TypeScript**: 使用TypeScript开发，类型安全
- 📦 **npm包**: 支持一键安装和配置

## 🚀 快速开始

### 方式一：npm全局安装（推荐）

```bash
# 全局安装
npm install -g mcp-baidu-curl

# 直接使用
mcp-baidu-curl
```

### 方式二：npx运行（无需安装）

```bash
npx mcp-baidu-curl
```

### 方式三：本地开发

#### 前置要求
- Node.js >= 18.0.0
- npm 或 yarn

#### 安装与运行
```bash
# 克隆项目
git clone <your-repo-url>
cd mcp-baidu-curl

# 安装依赖
npm install

# 构建项目
npm run build

# 运行服务
npm start

# 或开发模式
npm run dev
```

## 🔧 MCP工具说明

### curl_baidu

获取百度网站(www.baidu.com)的HTML内容。

**参数:**
- `timeout` (可选): 请求超时时间（毫秒），默认5000ms
- `userAgent` (可选): 自定义User-Agent字符串

**返回内容:**
- 响应状态码
- HTML内容完整文本
- 响应头信息
- 内容长度等统计信息

## 🔌 客户端集成指南

### Cursor IDE 集成

1. **打开Cursor设置**
   - macOS: `Cursor > Settings > Features > Model Context Protocol`  
   - Windows/Linux: `File > Preferences > Settings > Features > Model Context Protocol`

2. **添加MCP服务器配置**
   ```json
   {
     "mcpServers": {
       "baidu-curl": {
         "command": "npx",
         "args": ["mcp-baidu-curl"],
         "description": "百度网站内容获取服务"
       }
     }
   }
   ```

3. **或者使用全局安装版本**
   ```json
   {
     "mcpServers": {
       "baidu-curl": {
         "command": "mcp-baidu-curl",
         "args": [],
         "description": "百度网站内容获取服务"
       }
     }
   }
   ```

### Claude Desktop 集成

1. **找到配置文件位置**
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. **编辑配置文件**
   ```json
   {
     "mcpServers": {
       "baidu-curl": {
         "command": "npx",
         "args": ["mcp-baidu-curl"]
       }
     }
   }
   ```

### Cherry Studio 集成

1. **打开Cherry Studio设置**
   - 进入 `设置 > 插件 > MCP服务器`

2. **添加新的MCP服务器**
   - 名称: `baidu-curl`
   - 命令: `npx`
   - 参数: `["mcp-baidu-curl"]`
   - 描述: `百度网站内容获取服务`

### Continue.dev 集成

在 `.continue/config.json` 中添加：

```json
{
  "mcpServers": [
    {
      "name": "baidu-curl",
      "command": "npx",
      "args": ["mcp-baidu-curl"]
    }
  ]
}
```

### Zed Editor 集成

在 Zed 设置中添加：

```json
{
  "language_models": {
    "mcp_servers": {
      "baidu-curl": {
        "command": "npx",
        "args": ["mcp-baidu-curl"]
      }
    }
  }
}
```

## 🎯 使用示例

### 在支持MCP的客户端中使用

配置完成后，您可以在对话中直接使用：

```
请帮我获取百度网站的内容
```

或者指定参数：

```
请用10秒超时时间获取百度网站内容，并使用自定义User-Agent
```

### 直接API调用示例

```json
{
  "method": "tools/call",
  "params": {
    "name": "curl_baidu",
    "arguments": {
      "timeout": 10000,
      "userAgent": "Custom-MCP-Client/1.0"
    }
  }
}
```

## 📁 项目结构

\`\`\`
mcp-baidu-curl-demo/
├── src/
│   └── index.ts          # 主服务文件
├── dist/                 # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
└── README.md            # 项目说明
\`\`\`

## 🔍 技术细节

- **传输协议**: 使用stdio传输
- **HTTP客户端**: 使用axios进行网络请求
- **错误处理**: 包含完整的错误捕获和处理机制
- **信号处理**: 支持优雅关闭(SIGINT/SIGTERM)

## 📦 发布到npm

### 开发者指南

如果您想要发布自己的MCP服务到npm，请参考以下步骤：

1. **准备发布**
   ```bash
   # 确保所有测试通过
   npm test
   
   # 构建项目
   npm run build
   
   # 检查包内容
   npm pack --dry-run
   ```

2. **发布到npm**
   ```bash
   # 登录npm（首次需要）
   npm login
   
   # 发布包
   npm publish
   ```

3. **更新版本**
   ```bash
   # 更新补丁版本
   npm version patch
   
   # 更新次要版本
   npm version minor
   
   # 更新主要版本
   npm version major
   
   # 发布新版本
   npm publish
   ```

## 🔧 故障排除

### 常见问题

1. **服务器启动失败**
   - 检查Node.js版本是否 >= 18.0.0
   - 确认网络连接正常
   - 查看错误日志获取详细信息

2. **MCP客户端无法连接**
   - 确认配置文件路径正确
   - 检查命令和参数是否正确
   - 重启MCP客户端应用

3. **请求百度失败**
   - 检查网络连接
   - 尝试增加timeout参数
   - 确认防火墙设置

### 调试模式

```bash
# 启用详细日志
DEBUG=* npm start

# 或者运行演示查看详细输出
npm run demo
```

## 🚀 扩展建议

这个项目可以作为基础，扩展更多功能：

1. 支持更多网站的curl功能
2. 添加POST请求支持
3. 实现请求缓存机制
4. 添加请求头自定义功能
5. 支持代理配置
6. 添加响应内容解析功能
7. 支持批量请求

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📞 支持

- 🐛 [报告Bug](https://github.com/your-username/mcp-baidu-curl/issues)
- 💡 [功能建议](https://github.com/your-username/mcp-baidu-curl/issues)
- 📖 [文档](https://github.com/your-username/mcp-baidu-curl/wiki)

## ⭐ 如果这个项目对您有帮助，请给个Star！