FreeSearch MCP Server

FreeSearch MCP Server 是一个模型上下文协议（MCP）服务器，通过 DuckDuckGo 的 API 提供免费的网络搜索功能。它还包含智能摘要功能，利用 MCP 客户端内置的语言模型。

项目目的

本项目提供一个 JSON-RPC 2.0 服务器，具有以下功能：

• 免费网络搜索：无需 API 密钥 - 使用 DuckDuckGo 的公共 API
• 智能摘要：利用 MCP 客户端的语言模型进行搜索结果摘要
• 可定制提示词：轻松修改提示模板以实现不同的摘要风格
• 零成本：完全免费使用，无需任何 API 订阅

功能特性

• JSON-RPC 端点: /rpc - 客户端通过 JSON-RPC 协议调用服务器功能
• 健康检查端点: /ping - 用于服务器健康状态检测
• 搜索工具: search - 通过 DuckDuckGo 进行免费网络搜索
• 摘要工具: summarize - 使用 MCP 客户端的语言模型生成搜索结果摘要

技术栈

• Node.js & Express.js: 作为服务器框架。
• jsonrpc-lite: 用于解析和构建 JSON-RPC 请求和响应。
• dotenv: 管理和加载环境变量配置。

安装步骤

系统需求

• Node.js (>= 14.x) 和 npm
• 本地安装 @modelcontextprotocol/sdk

项目安装

1. 克隆代码仓库:

   git clone https://your-repo-url.git
   cd freesearch-mcpserver
   

2. 安装项目依赖:

   npm install
   

3. 配置环境变量 (可选):

   • 复制 .env.example 为 .env 文件，配置端口号。

   PORT=3000
   # OpenAI API key 当前不需要，已预留给未来扩展
   # OPENAI_KEY=your-openai-api-key
   

4. 编译项目:

   npm run build
   

5. 启动服务器:

   npm start
   

   服务器将运行在你配置的端口上 (默认 3000)。

6. 运行测试来验证功能:

   npm run test:rpc
   

一键配置示例

你可以使用以下示例代码实例化和配置 MCP 服务器：

import express, { Request, Response } from 'express';
import bodyParser from 'body-parser';
import jsonrpc from 'jsonrpc-lite';
import dotenv from 'dotenv';

const { McpServer } = require('@modelcontextprotocol/sdk');

// 加载环境变量
dotenv.config();

const app = express();
app.use(bodyParser.json());

// 健康检查
app.get('/ping', (_req: Request, res: Response) =e {
    res.status(200).send('PONG');
});

// JSON-RPC 端点
app.post('/rpc', async (req: Request, res: Response) =e {
    try {
        const rpcRequest = jsonrpc.parseObject(req.body);
        if (rpcRequest.type === 'request' && rpcRequest.payload) {
            const response = await server.handle(rpcRequest.payload);
            res.json(jsonrpc.success(rpcRequest.payload.id, response));
        } else {
            res.status(400).send('Invalid RPC request');
        }
    } catch (error) {
        res.status(500).send(error.message);
    }
});

// 启动服务器
const port = process.env.PORT || 3000;
app.listen(port, () =e {
    console.log(`Server started on port ${port}`);
});

此代码片段适合用于快速配置在类似 Cursor 这样的客户端中使用的 MCP 服务器。

在 Cursor 中配置 MCP 服务器

1. 前往 Cursor 设置 -> MCP -> 添加新 MCP 服务器。
2. 以你喜欢的名称命名。
3. 使用命令类型配置如下：

   {
     "mcpServers": {
       "freesearch": {
         "command": "npx",
         "args": [
           "freesearch-mcpserver@latest"
         ]
       }
     }
   }
   

4. 通过点击 "Edit" 验证配置或添加命令参数。

如果你还需要有关如何在特定平台（例如 Windows、Linux）上进行配置的具体说明或需要进一步帮助，请随时告知我！

快速开始

安装

npm install

开发

npm run dev    # 监视模式
npm run build  # 构建项目

代码质量

npm run lint        # 运行 ESLint
npm run lint:fix    # 修复 ESLint 问题
npm run format      # 使用 Prettier 格式化
npm run format:check # 检查格式
npm run type-check  # 类型检查（不构建）

JSON-RPC 请求示例

搜索

{
  "jsonrpc": "2.0",
  "method": "search",
  "params": {
    "query": "人工智能"
  },
  "id": 1
}

摘要

{
  "jsonrpc": "2.0",
  "method": "summarize",
  "params": {
    "query": "最新技术",
    "results": [
      {
        "title": "AI 及其影响",
        "url": "https://example.com/ai",
        "snippet": "AI 正在改变各个行业..."
      }
    ]
  },
  "id": 2
}

如何自定义提示模板

您可以通过修改 src/config/prompts.yml 文件来自定义提示模板：

# 提示词配置
summarize: |
  请用要点形式总结以下关于"{{query}}"的搜索结果：
  {{#each results}}
  - {{this.title}}: {{this.snippet}}
  {{/each}}

也可以通过命令行参数指定自定义提示文件：

npm run dev -- --prompt-file /path/to/your/prompts.yml

搜索场景限制

DuckDuckGo API 限制

• 请求频率：DuckDuckGo API 对请求频率有限制，建议控制调用频率，避免过度频繁的搜索请求
• 搜索结果数量：单次搜索返回的结果数量有限，通常包含即时答案、摘要、定义和相关主题
• 搜索内容类型：主要支持文本搜索，对于特殊格式（如图片、视频）的搜索结果支持有限

技术限制

• 网络依赖：需要稳定的互联网连接才能正常工作
• 重试机制：内置最多3次重试机制，使用指数退避策略处理网络错误
• 响应时间：搜索响应时间取决于网络状况和 DuckDuckGo 服务器响应速度

使用建议

• 合理控制频率：建议在应用中实现适当的请求间隔，避免触发 API 限制
• 错误处理：务必在代码中实现完善的错误处理机制，处理网络超时、API 错误等情况
• 结果验证：搜索结果的准确性和时效性依赖于 DuckDuckGo，建议对重要信息进行验证
• 缓存策略：对于相同的搜索查询，建议实现本地缓存以减少重复请求

OpenAPI 风格文档片段

搜索端点

paths:
  /rpc:
    post:
      summary: "执行 JSON-RPC 命令"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  example: "2.0"
                method:
                  type: string
                  example: "search"
                params:
                  type: object
                  properties:
                    query:
                      type: string
                      example: "人工智能"
                id:
                  type: integer
                  example: 1

摘要端点

paths:
  /rpc:
    post:
      summary: "执行 JSON-RPC 命令"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  example: "2.0"
                method:
                  type: string
                  example: "summarize"
                params:
                  type: object
                  properties:
                    query:
                      type: string
                      example: "最新技术"
                    results:
                      type: array
                      items:
                        type: object
                        properties:
                          title:
                            type: string
                            example: "AI 及其影响"
                          url:
                            type: string
                            example: "https://example.com/ai"
                          snippet:
                            type: string
                            example: "AI 正在改变各个行业..."
                id:
                  type: integer
                  example: 2

项目结构

freesearch-mcpserver/
├── src/                # 源代码文件
├── dist/               # 编译输出
├── package.json        # 项目配置
├── tsconfig.json       # TypeScript 配置
├── .eslintrc.json      # ESLint 配置
└── .prettierrc.json    # Prettier 配置