Sofya

sofya-mcp

适用于 Sofya 的 MCP 服务——通过 Model Context Protocol 为 AI Agent 提供网页搜索、抓取、提取和深度研究功能。

可任选以下方式使用：

• 托管（无需安装）： 使用 API 密钥作为 Bearer token，将客户端连接到 https://sofya.co/mcp。该服务已在 MCP 注册表中列出，名称为 co.sofya/sofya。
• 本地： 通过 stdio 运行此 sofya-mcp 包。它是 Sofya REST API 的轻量封装，提供相同的工具。

这四种工具均为只读。符合条件的 GitHub 账号每月可获得 2,000 个免费额度。

工具

工具	功能	费用
search	搜索网页并获取提取后的页面内容（不只是摘要）。支持 news 主题、域名筛选、新鲜度筛选，以及可选的 AI 综合回答 answer。	1-2 个额度（启用 include_answer 另加 10 个）
fetch	将最多 10 个 URL 抓取为简洁的 Markdown。也支持 PDF、DOCX、XLSX、PPTX、EPUB 等格式。	每个 URL 2 个额度
extract	抓取页面，并使用 AI 提取特定结构化信息。	10 个额度
research	将问题拆解为多个子查询，并行阅读多个来源，综合生成带引用的报告。	50 个额度

托管服务（VS Code / Copilot 等）

在 sofya.co 获取 API 密钥（密钥格式类似 ay_live_...），然后将客户端指向托管端点。

VS Code / GitHub Copilot（.vscode/mcp.json）：

{
  "servers": {
    "sofya": {
      "type": "http",
      "url": "https://sofya.co/mcp",
      "headers": { "Authorization": "Bearer ay_live_..." }
    }
  }
}

Claude Code：

claude mcp add --transport http sofya https://sofya.co/mcp --header "Authorization: Bearer ay_live_..."

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "sofya": {
      "url": "https://sofya.co/mcp",
      "headers": { "Authorization": "Bearer ay_live_..." }
    }
  }
}

然后可以向 Agent 提问，例如“搜索最新的 Node.js LTS 版本发布说明”“抓取这个 PDF 并总结”或“研究欧盟 AI 法案如何对待开放权重模型”。完整 API 文档：sofya.co/docs。

本地服务（npm）

前置条件

• Node.js 18+
• Sofya API 密钥——在 sofya.co 获取（密钥格式类似 ay_live_...）

快速开始

直接使用 npx 运行——无需安装：

SOFYA_API_KEY=ay_live_... npx -y sofya-mcp

配置

Claude Code

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）：

{
  "mcpServers": {
    "sofya": {
      "command": "npx",
      "args": ["-y", "sofya-mcp"],
      "env": {
        "SOFYA_API_KEY": "ay_live_..."
      }
    }
  }
}

Codex

使用 Codex CLI 添加：

codex mcp add sofya --env SOFYA_API_KEY=ay_live_... -- npx -y sofya-mcp

也可以直接编辑 ~/.codex/config.toml。注意，Codex 会将环境变量放在嵌套的 [mcp_servers.<name>.env] 表中：

[mcp_servers.sofya]
command = "npx"
args = ["-y", "sofya-mcp"]

[mcp_servers.sofya.env]
SOFYA_API_KEY = "ay_live_..."

然后在 Codex 中运行 /mcp，确认服务已连接。

环境变量

变量	必需	默认值	说明
SOFYA_API_KEY	是	-	你的 Sofya API 密钥（ay_live_...）。
SOFYA_BASE_URL	否	https://sofya.co	覆盖 Sofya API 基础 URL。

CLI 参数 --api-key 和 --base-url 的优先级高于环境变量。 运行 npx sofya-mcp --list-tools 可打印工具架构，运行 --help 可查看选项。

开发

git clone https://github.com/sofya-co/sofya-mcp.git
cd sofya-mcp
npm install          # also builds via the prepare script
npm run build        # compile TypeScript to build/
npm run watch        # recompile on change
npm run inspector    # debug with @modelcontextprotocol/inspector

服务只有一个文件：src/index.ts。工具定义与 Sofya 的托管 MCP 服务完全一致（名称、参数和默认值相同）。

许可证

MIT——详见 LICENSE。