内容
# sofya-mcp
[](https://www.npmjs.com/package/sofya-mcp)
用于 [Sofya](https://sofya.co) 的 MCP 服务器 - 为 AI 代理提供网页**搜索**、**获取**、**提取**和深度**研究**，通过 [模型上下文协议](https://modelcontextprotocol.io) 公开。
它在本地通过标准输入/输出运行，并且是 Sofya REST API 的薄封装。您可以自带 Sofya API 密钥。
## 工具列表
| 工具 | 功能描述 | 费用 |
|------|--------------|------|
| `search` | 搜索网页并获取提取的页面内容（不仅限于摘要）。支持 `新闻` 主题、域名过滤、新鲜度和可选的 AI 综合 `答案`。 | 1-3 积分（+5 积分用于 `include_answer`） |
| `fetch` | 获取最多 10 个 URL 的干净 Markdown。还支持 PDF、DOCX 等格式。 | 1 积分/URL |
| `extract` | 获取页面并使用 AI 提取特定结构化信息。 | 5 积分 |
| `research` | 将问题分解为子查询、并行读取多个来源并综合引用报告。 | 25 积分 |
## 前置条件
- Node.js 18+
- Sofya API 密钥 - 在 [sofya.co](https://sofya.co) 获取（密钥格式为 `ay_live_...`）
## 快速开始
直接使用 `npx` 运行，无需安装：
```bash
SOFYA_API_KEY=ay_live_... npx -y sofya-mcp
```
## 配置
### Claude Code
```bash
claude mcp add sofya --env SOFYA_API_KEY=ay_live_... -- npx -y sofya-mcp
```
### Claude Desktop / Cursor / Windsurf / VS Code
将以下内容添加到您的 MCP 配置文件（例如 `claude_desktop_config.json` 或 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"sofya": {
"command": "npx",
"args": ["-y", "sofya-mcp"],
"env": {
"SOFYA_API_KEY": "ay_live_..."
}
}
}
}
```
### Codex
使用 Codex CLI 添加：
```bash
codex mcp add sofya --env SOFYA_API_KEY=ay_live_... -- npx -y sofya-mcp
```
或直接编辑 `~/.codex/config.toml`：
```toml
[mcp_servers.sofya]
command = "npx"
args = ["-y", "sofya-mcp"]
[mcp_servers.sofya.env]
SOFYA_API_KEY = "ay_live_..."
```
然后在 Codex 中运行 `/mcp` 以确认服务器已连接。
> **您已经在使用 Sofya 的托管 MCP？** Sofya 还在 `https://sofya.co/mcp` 提供远程 MCP 端点（Bearer 认证，无需安装）。当您需要客户端启动的本地标准输入/输出服务器时，请使用此 `sofya-mcp` 包。
## 环境变量
| 变量 | 是否必填 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `SOFYA_API_KEY` | 是 | - | 您的 Sofya API 密钥（`ay_live_...`）。 |
| `SOFYA_BASE_URL` | 否 | `https://sofya.co` | 自定义 Sofya API 基地址。 |
CLI 标志 `--api-key` 和 `--base-url` 优先于环境变量。
运行 `npx sofya-mcp --list-tools` 以打印工具模式，或运行 `--help` 以查看选项。
## 开发
```bash
git clone https://github.com/sofya-ai/sofya-mcp.git
cd sofya-mcp
npm install # 同时通过 prepare 脚本构建
npm run build # 将 TypeScript 编译到 build/
npm run watch # 监听变化并重新编译
npm run inspector # 使用 @modelcontextprotocol/inspector 进行调试
```
服务器是一个单独的文件，[`src/index.ts`](src/index.ts)。工具定义与 Sofya 的托管 MCP 服务器完全相同（相同的名称、参数和默认值）。
## 许可证
MIT - 请参阅 [LICENSE](LICENSE)。
