SearchAPI.site - MCP Server

SearchAPI.site - MCP 服务

此项目提供了一个 Model Context Protocol（MCP）服务，通过 SearchAPI.site 将 AI 助手连接到外部数据源（Google、Bing 等）。

作者： Claude

• Glama
• Github
• NPM

可用平台

• Google - 网页搜索
• Google - 图片搜索
• Google - YouTube 搜索
• Google - 地图搜索
• Bing - 网页搜索
• Bing - 图片搜索
• Reddit
• X/Twitter
• Facebook 搜索
• Facebook 群组搜索
• Instagram
• TikTok

SearchAPI.site

• 网站
• API 文档
• Swagger UI 配置
• 在此处创建 Search API 密钥
• GitHub

支持的传输方式

• "stdio" 传输方式 - CLI 使用的默认传输方式
• "Streamable HTTP" 传输方式 - 适用于基于 Web 的客户端
  • 实现身份验证（使用 Bearer <token> 的 "Authorization" 标头）
• "sse" 传输方式 (已弃用)
• 编写测试

使用方法

CLI

# Google search via CLI
npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key"

# Google image search via CLI
npm run dev:cli -- search-google-images --query "your search query" --api-key "your-api-key"

# YouTube search via CLI
npm run dev:cli -- search-youtube --query "your search query" --api-key "your-api-key" --max-results 5

MCP 配置

使用 stdio 传输方式进行本地配置：

{
  "mcpServers": {
    "searchapi": {
      "command": "node",
      "args": ["/path/to/searchapi-mcp-server/dist/index.js"],
      "transportType": "stdio"
    }
  }
}

远程 HTTP 配置：

{
  "mcpServers": {
    "searchapi": {
      "type": "http",
      "url": "http://mcp.searchapi.site/mcp"
    }
  }
}

HTTP 传输方式的环境变量：

你可以使用以下环境变量配置 HTTP 服务：

• MCP_HTTP_HOST：要绑定的主机（默认值：127.0.0.1）
• MCP_HTTP_PORT：要监听的端口（默认值：8080）
• MCP_HTTP_PATH：端点路径（默认值：/mcp）

---

源代码概览

什么是 MCP？

Model Context Protocol（MCP）是一种开放标准，可让 AI 系统以安全且结合上下文的方式连接外部工具和数据源。

此样板项目以清晰的分层架构实现了 MCP 规范，可扩展以便为任何 API 或数据源构建自定义 MCP 服务。

为什么使用此样板项目？

• 可用于生产的架构：遵循已发布 MCP 服务所采用的相同模式，清晰区分 CLI、工具、控制器和服务。

• 类型安全：使用 TypeScript 构建，提升开发体验、代码质量和可维护性。

• 可运行示例：包含一个完整实现的 IP 查询工具，展示从 CLI 到 API 集成的完整模式。

• 测试框架：提供单元测试和 CLI 集成测试所需的测试基础设施，包括覆盖率报告。

• 开发工具：预先配置 ESLint、Prettier、TypeScript 和其他质量工具，便于 MCP 服务开发。

---

快速入门

先决条件

• Node.js（>=18.x）：下载
• Git：用于版本控制

---

第 1 步：克隆并安装

# Clone the repository
git clone https://github.com/mrgoonie/searchapi-mcp-server.git
cd searchapi-mcp-server

# Install dependencies
npm install

---

第 2 步：运行开发服务器

使用 stdio 传输方式（默认）以开发模式启动服务：

npm run dev:server

或使用 Streamable HTTP 传输方式：

npm run dev:server:http

这会启动支持热重载的 MCP 服务，并启用 MCP Inspector，地址为 http://localhost:5173。

⚙️ 代理服务正在端口 6277 上监听 🔍 MCP Inspector 已启动并运行，地址为 http://127.0.0.1:6274

使用 HTTP 传输方式时，服务默认可通过 http://127.0.0.1:8080/mcp 访问。

---

步骤 3：测试示例工具

从命令行运行示例 IP 查询工具：

# Using CLI in development mode
npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key"

# Or with a specific IP
npm run dev:cli -- search-google --query "your search query" --api-key "your-api-key" --limit 10 --offset 0 --sort "date:d" --from_date "2023-01-01" --to_date "2023-12-31"

---

架构

此样板项目采用清晰的分层架构模式，将各项职责分离并提升可维护性。

项目结构

src/
├── cli/              # Command-line interfaces
├── controllers/      # Business logic
├── resources/        # MCP resources: expose data and content from your servers to LLMs
├── services/         # External API interactions
├── tools/            # MCP tool definitions
├── types/            # Type definitions
├── utils/            # Shared utilities
└── index.ts          # Entry point

各层及其职责

命令行界面层（src/cli/*.cli.ts）

• 用途：定义命令行界面，用于解析参数并调用控制器
• 命名：文件应命名为 <feature>.cli.ts
• 测试：在 <feature>.cli.test.ts 中编写命令行界面集成测试

工具层（src/tools/*.tool.ts）

• 用途：定义 MCP 工具，并为 AI 助手提供架构和描述
• 命名：文件应命名为 <feature>.tool.ts，类型定义放在 <feature>.types.ts 中
• 模式：每个工具都应使用 zod 验证参数

控制器层（src/controllers/*.controller.ts）

• 用途：实现业务逻辑、处理错误并格式化响应
• 命名：文件应命名为 <feature>.controller.ts
• 模式：应返回标准化的 ControllerResponse 对象

服务层（src/services/*.service.ts）

• 用途：与外部 API 或数据源交互
• 命名：文件应命名为 <feature>.service.ts
• 模式：仅处理 API 交互，尽量减少逻辑

工具函数层（src/utils/*.util.ts）

• 用途：为应用程序提供共享功能
• 主要工具函数：
  • logger.util.ts：结构化日志记录
  • error.util.ts：错误处理与标准化
  • formatter.util.ts：Markdown 格式化辅助函数

---

开发指南

开发脚本

# Start server in development mode (hot-reload & inspector)
npm run dev:server

# Run CLI in development mode
npm run dev:cli -- [command] [args]

# Build the project
npm run build

# Start server in production mode
npm run start:server

# Run CLI in production mode
npm run start:cli -- [command] [args]

测试

# Run all tests
npm test

# Run specific tests
npm test -- src/path/to/test.ts

# Generate test coverage report
npm run test:coverage

评估

evals 包会加载一个 MCP 客户端，随后运行 index.ts 文件，因此测试之间无需重新构建。可以在 npx 命令前添加环境变量来加载它们。完整文档请参阅此处。

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/tools/searchapi.tool.ts

代码质量

# Lint code
npm run lint

# Format code with Prettier
npm run format

# Check types
npm run typecheck

---

构建自定义工具

按照以下步骤向服务添加自己的工具：

1. 定义服务层

在 src/services/ 中创建新服务，以便与外部 API 交互：

// src/services/example.service.ts
import { Logger } from '../utils/logger.util.js';

const logger = Logger.forContext('services/example.service.ts');

export async function getData(param: string): Promise<any> {
	logger.debug('Getting data', { param });
	// API interaction code here
	return { result: 'example data' };
}

2. 创建控制器

在 src/controllers/ 中添加控制器以处理业务逻辑：

// src/controllers/example.controller.ts
import { Logger } from '../utils/logger.util.js';
import * as exampleService from '../services/example.service.js';
import { formatMarkdown } from '../utils/formatter.util.js';
import { handleControllerError } from '../utils/error-handler.util.js';
import { ControllerResponse } from '../types/common.types.js';

const logger = Logger.forContext('controllers/example.controller.ts');

export interface GetDataOptions {
	param?: string;
}

export async function getData(
	options: GetDataOptions = {},
): Promise<ControllerResponse> {
	try {
		logger.debug('Getting data with options', options);

		const data = await exampleService.getData(options.param || 'default');

		const content = formatMarkdown(data);

		return { content };
	} catch (error) {
		throw handleControllerError(error, {
			entityType: 'ExampleData',
			operation: 'getData',
			source: 'controllers/example.controller.ts',
		});
	}
}

3. 实现 MCP 工具

在 src/tools/ 中创建工具定义：

// src/tools/example.tool.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { Logger } from '../utils/logger.util.js';
import { formatErrorForMcpTool } from '../utils/error.util.js';
import * as exampleController from '../controllers/example.controller.js';

const logger = Logger.forContext('tools/example.tool.ts');

const GetDataArgs = z.object({
	param: z.string().optional().describe('Optional parameter'),
});

type GetDataArgsType = z.infer<typeof GetDataArgs>;

async function handleGetData(args: GetDataArgsType) {
	try {
		logger.debug('Tool get_data called', args);

		const result = await exampleController.getData({
			param: args.param,
		});

		return {
			content: [{ type: 'text' as const, text: result.content }],
		};
	} catch (error) {
		logger.error('Tool get_data failed', error);
		return formatErrorForMcpTool(error);
	}
}

export function register(server: McpServer) {
	server.tool(
		'get_data',
		`Gets data from the example API, optionally using \`param\`.
Use this to fetch example data. Returns formatted data as Markdown.`,
		GetDataArgs.shape,
		handleGetData,
	);
}

4. 添加命令行支持

在 src/cli/ 中创建命令行命令：

// src/cli/example.cli.ts
import { program } from 'commander';
import { Logger } from '../utils/logger.util.js';
import * as exampleController from '../controllers/example.controller.js';
import { handleCliError } from '../utils/error-handler.util.js';

const logger = Logger.forContext('cli/example.cli.ts');

program
	.command('get-data')
	.description('Get example data')
	.option('--param <value>', 'Optional parameter')
	.action(async (options) => {
		try {
			logger.debug('CLI get-data called', options);

			const result = await exampleController.getData({
				param: options.param,
			});

			console.log(result.content);
		} catch (error) {
			handleCliError(error);
		}
	});

5. 注册组件

更新入口点以注册新组件：

// In src/cli/index.ts
import '../cli/example.cli.js';

// In src/index.ts (for the tool)
import exampleTool from './tools/example.tool.js';
// Then in registerTools function:
exampleTool.register(server);

---

调试工具

MCP Inspector

访问可视化 MCP Inspector，以测试工具并查看请求/响应详情：

1. 运行 npm run dev:server
2. 在浏览器中打开 http://localhost:5173
3. 直接在界面中测试工具并查看日志

服务日志

在开发过程中启用调试日志：

# Set environment variable
DEBUG=true npm run dev:server

# Or configure in ~/.mcp/configs.json

---

发布 MCP 服务

准备好发布自定义 MCP 服务时：

1. 使用你的信息更新 package.json
2. 使用工具文档更新 README.md
3. 构建项目：npm run build
4. 测试生产构建：npm run start:server
5. 发布到 npm：npm publish

---

许可证

ISC 许可证

{
	"searchapi": {
		"environments": {
			"DEBUG": "true",
			"SEARCHAPI_API_KEY": "value"
		}
	}
}

**注意：**为保持向后兼容，如果找不到 searchapi 键，服务也会识别完整包名（searchapi-mcp-server）或非作用域包名（searchapi-mcp-server）下的配置。不过，建议新配置使用简短的 searchapi 键。

共同作者

• Claude Code（Claude AI 助手）
• Goon