SearchAPI.site - MCP サーバー
このプロジェクトは、 SearchAPI.siteを介して AI アシスタントを外部データ ソース (Google、Bing など) に接続するモデル コンテキスト プロトコル (MCP) サーバーを提供します。
利用可能なプラットフォーム
- [x] Google - ウェブ検索
- [x] Google - 画像検索
- [x] Google - YouTube検索
- [ ] Googleマップ検索
- [x] Bing - ウェブ検索
- [ ] Bing - 画像検索
- [ ] レディット
- [ ] X/ツイッター
- [ ] Facebook検索
- [ ] Facebookグループ検索
- [ ] インスタグラム
- [ ] ティックトック
SearchAPI.site
サポートされているトランスポート
- [x] "stdio"トランスポート - CLI 使用時のデフォルトのトランスポート
- [x]「ストリーミング可能なHTTP」トランスポート - Webベースのクライアント向け
- [ ] 認証を実装する（
Bearer <token>を使用した「Authorization」ヘッダー）
- [ ]
「sse」輸送(非推奨) - [ ] テストを書く
使い方
コマンドライン
# 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とは何ですか?
モデル コンテキスト プロトコル (MCP) は、AI システムが外部ツールやデータ ソースに安全かつコンテキストに応じて接続できるようにするオープン スタンダードです。
このボイラープレートは、任意の API またはデータ ソース用のカスタム MCP サーバーを構築するために拡張できる、クリーンな階層化アーキテクチャを使用して MCP 仕様を実装します。
この定型句を使用する理由
- 実稼働対応アーキテクチャ: 公開された MCP サーバーで使用されるのと同じパターンに従い、CLI、ツール、コントローラー、およびサービスが明確に分離されています。
- 型の安全性: 開発者エクスペリエンス、コード品質、保守性を向上させるために TypeScript を使用して構築されています。
- 動作例: CLI から API 統合までの完全なパターンを示す、完全に実装された IP 検索ツールが含まれています。
- テスト フレームワーク: カバレッジ レポートを含む、ユニット テストと CLI 統合テストの両方のテスト インフラストラクチャが付属しています。
- 開発ツール: ESLint、Prettier、TypeScript、および MCP サーバー開発用に事前構成されたその他の高品質ツールが含まれています。
はじめる
前提条件
- Node.js (>=18.x)(https://nodejs.org/)
- 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 トランスポートを使用して開発モードでサーバーを起動します (デフォルト)。
または、ストリーミング可能な HTTP トランスポートを使用する場合:
これにより、ホットリロードで MCP サーバーが起動し、 http://localhost:5173で MCP インスペクターが有効になります。
⚙️ プロキシ サーバーはポート 6277 で待機しています 🔍 MCP Inspector はhttp://127.0.0.1:6274で稼働しています
HTTP トランスポートを使用する場合、サーバーはデフォルトでhttp://127.0.0.1:8080/mcpで利用できるようになります。
ステップ3: サンプルツールをテストする
CLI からサンプル 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
階層と責任
CLI レイヤー ( src/cli/*.cli.ts )
- 目的: 引数を解析してコントローラを呼び出すコマンドラインインターフェースを定義する
- 命名: ファイル名は
<feature>.cli.tsとします - テスト:
<feature>.cli.test.ts内の CLI 統合テスト
- 目的: AIアシスタント用のスキーマと説明を備えたMCPツールを定義する
- 命名: ファイルは
<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. サービス層を定義する
外部 API と対話するためにsrc/services/に新しいサービスを作成します。
// 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. CLIサポートを追加する
src/cli/に 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検査官
ビジュアル MCP インスペクターにアクセスしてツールをテストし、リクエスト/レスポンスの詳細を表示します。
npm run dev:server実行します。- ブラウザでhttp://localhost:5173を開きます。
- ツールをテストし、UI で直接ログを表示します
サーバーログ
開発用のデバッグ ログを有効にします。
# Set environment variable
DEBUG=true npm run dev:server
# Or configure in ~/.mcp/configs.json
MCPサーバーの公開
カスタム MCP サーバーを公開する準備ができたら、次の手順を実行します。
- 詳細を記載したpackage.jsonを更新します
- ツールのドキュメントをREADME.mdに更新する
- プロジェクトをビルドします:
npm run build - 本番ビルドをテストする:
npm run start:server - npmに公開:
npm publish
ライセンス
ISCライセンス
{
"searchapi": {
"environments": {
"DEBUG": "true",
"SEARCHAPI_API_KEY": "value"
}
}
}
**注:**後方互換性のため、 searchapiキーが見つからない場合、サーバーは完全なパッケージ名 ( searchapi-mcp-server ) またはスコープ外のパッケージ名 ( searchapi-mcp-server ) の設定も認識します。ただし、新しい設定では短縮形のsearchapiキーを使用することをお勧めします。