# Metaso MCP Server

基于Metaso AI搜索引擎的MCP (Model Context Protocol) Server，为大语言模型提供AI搜索、网页内容读取和AI问答功能。

## 功能特性

- **🔍 AI搜索**: 支持网页、文档、学术、图片、视频、播客等多种搜索范围
- **📖 网页读取**: 提取网页完整内容，支持Markdown和JSON格式输出
- **💬 AI问答**: 基于搜索增强的智能问答，支持多种AI模型
- **🔒 安全验证**: URL安全检查、API密钥验证、输入长度限制
- **🚀 高性能**: 内置重试机制、连接池、错误处理

## 安装

### 从源码构建

```bash
# 克隆项目
git clone https://github.com/csrts/metaso-mcp
cd metaso-mcp

# 安装依赖
npm install

# 构建项目
npm run build
```


## 配置

### 环境变量

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `METASO_API_KEY` | ✅ | - | Metaso API密钥（格式：mk-[32位字符]） |
| `METASO_BASE_URL` | ❌ | `https://metaso.cn` | API基础URL |
| `METASO_TIMEOUT` | ❌ | `30000` | 请求超时时间（毫秒） |
| `METASO_DEBUG` | ❌ | `false` | 启用调试日志 |

### 获取API密钥

1. 访问 [Metaso官网](https://metaso.cn)
2. 注册账户并获取API密钥
3. 设置环境变量：
   ```bash
   export METASO_API_KEY="mk-YOUR_API_KEY_HERE"
   ```

## MCP客户端配置

详情请看->[MCP-CONFIG](https://github.com/csrts/metaso-mcp/blob/main/MCP-CONFIG.md)

### Claude Desktop

在Claude Desktop的配置文件中添加：

```json
{
  "mcpServers": {
    "metaso": {
      "command": "node",
      "args": ["/path/to/metaso-mcp-server/dist/index.js"],
      "env": {
        "METASO_API_KEY": "mk-YOUR_API_KEY_HERE"
      }
    }
  }
}
```

### 开发模式

```json
{
  "mcpServers": {
    "metaso": {
      "command": "npx",
      "args": ["-y", "tsx", "/path/to/metaso-mcp-server/src/index.ts"],
      "env": {
        "METASO_API_KEY": "mk-YOUR_API_KEY_HERE",
        "METASO_DEBUG": "true"
      }
    }
  }
}
```

## 可用工具

### 1. metaso_search - AI搜索

搜索互联网内容，支持多种搜索范围。

**参数**：
- `query` (必需): 搜索查询内容
- `scope` (可选): 搜索范围，支持 `webpage`、`document`、`scholar`、`image`、`video`、`podcast`
- `page` (可选): 页数（与size互斥）
- `size` (可选): 结果数量（与page互斥）
- `include_summary` (可选): 是否包含AI摘要（默认true）
- `include_row_content` (可选): 是否包含原文内容（默认false）

**示例**：
```json
{
  "query": "人工智能最新发展",
  "scope": "scholar",
  "size": 10,
  "include_summary": true
}
```

### 2. metaso_reader - 网页读取

读取指定网页的完整内容。

**参数**：
- `url` (必需): 要读取的网页URL
- `format` (可选): 返回格式，支持 `markdown`、`json`（默认markdown）

**示例**：
```json
{
  "url": "https://example.com/article",
  "format": "markdown"
}
```

### 3. metaso_chat - AI问答

与Metaso AI助手对话，获得基于搜索增强的智能回答。

**参数**：
- `query` (必需): 问题或提示内容
- `model` (可选): AI模型，支持 `fast`、`fast_thinking`、`ds-r1`（默认fast）
- `scope` (可选): 搜索范围，支持 `document`、`scholar`、`video`、`podcast`
- `format` (可选): 响应格式，支持 `chat_completions`、`simple`（默认chat_completions）
- `stream` (可选): 启用流式输出（默认false）

**示例**：
```json
{
  "query": "解释量子计算的基本原理",
  "model": "ds-r1",
  "scope": "scholar"
}
```

## 开发

### 项目结构

```
metaso-mcp/
├── src/
│   ├── index.ts                 # 主入口文件
│   ├── server.ts                # MCP服务器实现
│   ├── tools/                   # 工具实现
│   │   ├── search.ts            # 搜索工具
│   │   ├── reader.ts            # 读取工具
│   │   └── chat.ts              # 问答工具
│   ├── types/                   # 类型定义
│   │   └── requests.ts          # 请求和响应类型
│   └── utils/                   # 工具函数
│       ├── config.ts            # 配置管理
│       └── http-client.ts       # HTTP客户端
├── tests/                       # 测试文件
└── dist/                        # 编译输出
```

### 开发命令

```bash
# 开发模式运行
npm run dev

# 构建项目
npm run build
```

### 运行测试

```bash
# 运行所有测试
npm test

# 运行特定测试
npm test -- search.test.ts

# 监视模式
npm run test:watch
```

## 故障排除

### 常见错误

1. **配置验证失败**
   ```
   Configuration validation failed: apiKey: Required
   ```
   **解决方案**: 确保设置了`METASO_API_KEY`环境变量

2. **API密钥格式错误**
   ```
   Invalid API key format. Expected format: mk-[32 alphanumeric characters]
   ```
   **解决方案**: 检查API密钥格式是否正确

3. **网络连接错误**
   ```
   Network error: Unable to connect to Metaso API
   ```
   **解决方案**: 检查网络连接和API基础URL设置

### 调试模式

启用调试日志以获取更多信息：

```bash
export METASO_DEBUG=true
```

## 安全性

- 🔐 API密钥通过环境变量安全管理
- 🚫 阻止访问私有IP和localhost
- 📏 查询内容长度限制
- 🔍 URL安全性验证
- 🚨 敏感信息日志屏蔽

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 更新日志

### v1.0.0
- 初始版本发布
- 支持AI搜索、网页读取、AI问答功能
- 完整的MCP协议兼容性
- 安全性和错误处理