essentials

FieldCure MCP Essentials

一度インストールすれば、基本機能がそろいます。あらゆる MCP クライアントで利用できる、20 個の必須ツールを提供するモデルコンテキストプロトコル（MCP）サーバーです。HTTP リクエスト、ウェブ検索と取得、URL からのファイルダウンロード、Wolfram|Alpha による計算知識、シェルコマンド、JavaScript の実行、ファイル入出力、環境情報、永続メモリを利用できます。カテゴリ別検索（ニュース、画像、学術論文、特許）と実行時エンジン切り替え（取得／設定）は常に利用可能で、各機能は呼び出し時にアクティブなエンジンに応じて制御されます。C# と公式のMCP C# SDKを使用して構築されています。

機能

• 20 個の必須ツール — HTTP、ウェブ検索と取得、URL からのファイルダウンロード、実行時の検索エンジン切り替え（取得／設定）、Wolfram|Alpha、シェル、JavaScript サンドボックス、環境情報、ファイルの読み取り／書き込み／検索、永続メモリ、カテゴリ別検索（ニュース、画像、学術論文、特許）
• 設定不要 — 既定の Bing 検索では API キーは不要です。オプションの API キーを設定すると、Serper、Tavily、SerpApi（カテゴリ別検索ツールを含む）、Wolfram|Alpha を利用できます
• ドキュメント解析 — web_fetch と read_file は、PDF、DOCX、HWPX、PPTX、XLSX からテキストを抽出して Markdown に変換します。PDF のテキスト抽出はテキストレイヤーのみが対象です。テキストレイヤーのないスキャン PDF からは空のテキストが返されます。OCR を利用したインデックス作成には、fieldcure-mcp-ragを使用してください。
• サンドボックス化された JavaScript — 厳格な制限（タイムアウト、ステートメント数、再帰の深さ）を備えた Jint エンジン
• SSRF 対策 — HTTP リクエスト、ウェブ取得、ファイルダウンロードでは、プライベート IP 範囲とループバックアドレスへのアクセスをブロックします
• 複数のクライアントに対応 — Claude Desktop、VS Code、AssistStudio、および MCP 互換クライアントで動作します
• Stdio トランスポート — stdin/stdout を介した JSON-RPC による標準的な MCP サブプロセスモデル

インストール

dotnet tool install -g FieldCure.Mcp.Essentials

インストール後、fieldcure-mcp-essentials コマンドをグローバルに利用できます。

ソースからインストール

git clone https://github.com/fieldcure/fieldcure-mcp-essentials.git
cd fieldcure-mcp-essentials
dotnet build

要件

• .NET 8.0 Runtime 以降

ツール

ツール	説明	破壊的操作
http_request	カスタムヘッダーと本文に対応した、完全な HTTP クライアント（GET/POST/PUT/DELETE/PATCH/HEAD）	—
web_search	ウェブを検索し、スニペット（タイトル、URL、説明）を返します	—
web_fetch	URL を取得し、コンテンツを Markdown として抽出します。HTML ページとドキュメント（PDF、DOCX、HWPX、PPTX、XLSX）に対応しています	—
download_file	設定可能なダウンロードディレクトリに、最大 100 MB までの URL コンテンツをアトミックに保存します	はい
run_command	作業ディレクトリ、環境変数、シェルの選択、出力の切り詰め設定を指定してシェルコマンドを実行します	はい
run_javascript	数学、データ処理、JSON、正規表現に使える、サンドボックス化された JavaScript の実行（Jint）	—
wolfram_alpha	Wolfram|Alpha Full Results API — 記号計算、プロット、単位変換、定数に対応します。MathML はそのまま渡され、ネイティブに描画できます	—
get_environment	システム情報 — 現地時刻、タイムゾーン、OS、ホスト名、ユーザー名、.NET のバージョン	—
read_file	ファイルの読み取り — テキスト（オフセット／制限を指定可能）と、Markdown に解析するドキュメント（PDF、DOCX、HWPX、PPTX、XLSX）	—
write_file	ディレクトリを自動作成して、ファイルにテキストを書き込むか追記します	はい
search_files	glob パターンと内容でファイルを検索します（grep のような検索）	—
remember	キーと値のメモリを保存します（SQLite に永続化）	—
forget	キーまたはキーワード検索でメモリを削除します	はい
list_memories	FTS5 とページネーションを使って、保存済みメモリを検索し、一覧表示します	—

カテゴリー検索（SerpApi / Serper / Tavily）

常に登録されています。各ツールは実行時にアクティブなエンジンの機能を確認し、現在のエンジンがそのカテゴリーに対応していない場合は、set_search_engine を案内する説明的なエラーを返します。

ツール	説明	SerpApi	Serper	Tavily
search_news	Google ニュースで最近のニュース記事を検索します	対応	対応	対応
search_images	サイズや種類で絞り込んで画像を検索します	対応	対応	—
search_scholar	引用数付きで学術論文を検索します	対応	対応	—
search_patents	発明者や譲受人で絞り込んで特許文書を検索します	対応	対応	—

実行時のエンジン切り替え

ツール	説明
set_search_engine	実行時にアクティブなエンジン（bing、duckduckgo、serper、tavily、serpapi）を切り替えます。有料エンジンの API キーは、次回の検索時に環境変数または MCP Elicitation から遅延解決されます。切り替え時に必要なのはエンジン名だけです。成功すると notifications/tools/list_changed を発行します。
get_search_engine	現在アクティブなエンジンと、そのカテゴリー機能を返します。読み取り専用です。ホスト UI に現在のエンジン状態を反映する場合や、カテゴリー検索ツールを呼び出す前にカテゴリーへの対応状況を確認する場合に使用します。

web_search と web_fetch、download_file、http_request の違い

	http_request	web_search	web_fetch	download_file
目的	API 呼び出し、HTTP の生データ	ウェブ検索	ウェブページの読み取り	元のファイルを保存
応答	生データ（JSON、HTML など）	{title, url, snippet}[]	Markdown（本文のみ）	保存先のパスを含む JSON メタデータ
変換	なし	なし	SmartReader による HTML から Markdown への変換	なし
長さの上限	max_response_chars（デフォルト：無制限、最大 1MB）	max_results（最大 10 件）	max_length（最大 20000）	100 MB

ドキュメントの解析

web_fetch と read_file は、バイナリドキュメントを解析して Markdown に変換できます。

形式	拡張子	検出方法
PDF	.pdf	Content-Type / URL の拡張子（テキストレイヤーのみ。OCR なし）
Word	.docx	Content-Type / URL の拡張子
ハングル（HWPX）	.hwpx	URL の拡張子（標準の Content-Type なし）
PowerPoint	.pptx	Content-Type / URL の拡張子
Excel	.xlsx	Content-Type / URL の拡張子

出力には、見出し、表、数式（[math: LaTeX]）、スライドやページの区切りが含まれます。

ファイルのダウンロード

download_file は、HTTP(S) URL から元のバイトデータを保存します。save_path が省略された場合、ツールは Content-Disposition、URL パス、または生成されたフォールバック名からファイル名を推定します。相対パスの save_path は、設定された download_directory の下に解決されます。絶対パスは、保護されたシステムディレクトリを除き、そのまま使用されます。

デフォルトのダウンロードディレクトリは ~/Downloads/mcp で、初回使用時に自動的に作成されます。ダウンロードは保存先ディレクトリ内の一時ファイルに書き込まれた後、アトミックな移動または置換によって確定されます。そのため、ダウンロードが失敗またはキャンセルされても、不完全な最終ファイルは残りません。

{
  "url": "https://example.com/report.pdf"
}

{
  "url": "https://example.com/report.pdf",
  "save_path": "reports/report.pdf",
  "overwrite": false
}

ウェブ検索

デフォルトのエンジンは Bing です（無料で、API キーは不要です）。より信頼性の高い結果を得るには、API ベースのエンジンを使用してください。

エンジン	無料枠	カテゴリー検索	API キー
Bing（デフォルト）	無制限（スクレイピング）	—	不要
Serper	2,500（初回のみ）	ニュース、画像、学術論文、特許	serper.dev
SerpApi	月 100 件	ニュース、画像、学術論文、特許	serpapi.com
Tavily	月 1,000 件	ニュース	tavily.com

# Use Serper
fieldcure-mcp-essentials --search-engine serper --search-api-key YOUR_KEY

# Use Tavily
fieldcure-mcp-essentials --search-engine tavily --search-api-key YOUR_KEY

# Or via environment variables
ESSENTIALS_SEARCH_ENGINE=serper ESSENTIALS_SEARCH_API_KEY=xxx fieldcure-mcp-essentials

環境変数の自動検出

--search-engine を省略すると、サーバーが環境変数をスキャンし、利用可能な最適なエンジンを自動的に選択します。

エンジン	環境変数
Serper	SERPER_API_KEY
SerpApi	SERPAPI_API_KEY
Tavily	TAVILY_API_KEY

検出の優先順位：Serper → SerpApi → Tavily → Bing／DuckDuckGo へのフォールバック。

API キーのセキュリティ

エンジン	認証方法	キーの露出
Serper	HTTP ヘッダー（X-API-KEY）	URL に含まれません
Tavily	Authorization ヘッダー（Bearer トークン）	URL に含まれません
SerpApi	URL クエリパラメーター（api_key=xxx）	サーバーログに表示されます

地域

地域に応じた結果を得るには、region パラメーターを使用します。

// Korean results
{ "query": "서울 맛집", "region": "ko-kr" }

// US English results
{ "query": "best restaurants NYC", "region": "en-us" }

// Global (default)
{ "query": "Python tutorial" }

--search-engine を指定しない場合、CAPTCHA が発生するとフォールバックエンジン（Bing → DuckDuckGo）に自動で切り替わります。無料エンジンはスクレイピングに依存しており、動作が不安定になる場合があります。実用的な用途では、API ベースのエンジンを強く推奨します。

キーなしで有料エンジンを明示的に指定した場合 — MCP エリシテーション

--search-engine serper|tavily|serpapi を明示的に選択しているものの、API キーが設定されていない場合（CLI 引数、ESSENTIALS_SEARCH_API_KEY、またはエンジン固有の環境変数）、サーバーは最初の web_search 呼び出しまで待機し、その後 MCP Elicitation を通じて MCP クライアントにキーを要求します。ユーザーが辞退すると、続けて無料の Bing／DuckDuckGo で検索するかどうかを確認するプロンプトが表示されます。両方を辞退した場合、ツールは明確なメッセージを返してソフトフェイルし、LLM が復旧できるようにします。

Elicitation に対応していないクライアント（旧バージョンの CLI ホストを含む）は、2.1 より前の動作と同様に、直ちに無料エンジンへフォールバックします。キャッシュされたキーはプロセスの存続中保持されます。ツールがキャッシュを無効化した場合、ホストは上流からの 401／403 を受けて再度キーを要求できます。

Wolfram|Alpha

wolfram_alpha は Full Results API v2 を呼び出し、プレーンテキスト、MathML（ChatPanel／WebView2 など、MathML をネイティブにレンダリングするクライアント向けにそのまま渡されます）、ImageContent として埋め込まれたプロット画像を含む、複合コンテンツを返します。API の reinterpret=true フラグは常に有効になっているため、誤字程度のエラーのほとんどはサーバー側で自動修正されます。実際の解析エラーのみが、assumptions > tips > didyoumeans の案内とともに isError: true として表面化します。

AppID

developer.wolframalpha.com で取得した AppID を WOLFRAM_APPID に設定します（「Full Results API」を選択してください。無料プランは月 2,000 回までで、非商用利用に限られます）。Elicitation に対応した MCP クライアントでは、初回利用時にキーを対話形式で入力することもできます。AppID が拒否された場合（401／403）、無効化して 1 回だけ再試行するため、キーの入力ミスがあれば再度要求できます。既存の ApiKeyResolverRegistry による再要求回数の上限（環境変数スロットごとに 2 回）で、ループを防ぎます。

⚠️ developer.wolfram.com ではなく developer.wolframalpha.com を使用してください。前者は別の有料ポータルであり、無料アカウントでは「no permission to access any API keys」と表示されます。

AppID の状態にかかわらず、ツールは常に登録されます。キーがない場合は、モデルが何もせずにスキップするのではなく、ユーザーに案内できるよう、セットアップ方法を示すエラーを返します。

クエリのヒント（ツールの説明に表示）

• 英語のみ。簡潔なキーワード形式（'France population'。'how many people live in France' ではありません）
• 指数表記は 6*10^14 を使用し、6e14 は使用しないでください
• 変数は 1 文字（x、y、n）にしてください
• 物理定数は名称で指定します（'speed of light'。299792458 ではありません）
• 単位を含む方程式は、まず単位なしで解いてください
• RECOMMENDED / AVOID のヒントはモデルを誘導します。簡単な算術には run_javascript、一般的なウェブ検索には web_search を使用し、主観的な質問やニュース関連の質問には Wolfram を使わないよう促します

JavaScript サンドボックス

run_javascript は、厳格な制限が設定された Jint エンジンを使用します。

制約	値
タイムアウト	デフォルト 5 秒、最大 30 秒
最大ステートメント数	100,000
再帰の深さ	64
厳格モード	強制

許可: Math.*、JSON、Date、RegExp、console.log、文字列／配列メソッド、parseInt、encodeURIComponent、atob／btoa

ブロック: setTimeout、setInterval、require、import、.NET interop、eval()

データパイプラインで使用するため、変数をスクリプトスコープに注入できます。

1. http_request(url: "https://api.example.com/data") → {"items": [...]}
2. run_javascript(
     code: "data.items.filter(x => x.price > 100).map(x => x.name)",
     variables: {"data": {"items": [...]}}
   )

コマンドの実行

run_command は、ホストに対応した下位互換性のあるシェルをデフォルトで使用します。Windows では cmd.exe、Unix では /bin/sh です。特定の構文が必要なコマンドでは shell を使用してください。

シェル	説明
auto	デフォルト。Windows では cmd.exe、Unix では /bin/sh
pwsh	PowerShell Core。インストールされている場合、PowerShell ネイティブのコマンドに推奨
powershell	pwsh がない Windows ホスト向けの Windows PowerShell フォールバック
cmd	Windows の cmd.exe を明示的に指定
bash	利用可能な場合に Bash を明示的に指定
sh	利用可能な場合に POSIX シェルを明示的に指定

詳細な出力は、max_output_chars（デフォルト 100,000）によってストリームごとに上限が設定されます。応答には shell_used、stdout_truncated、stderr_truncated が含まれます。切り詰められたストリームには、省略された文字数を示すインラインマーカーが含まれます。

メモリ

メモリは SQLite（%LOCALAPPDATA%/FieldCure/Mcp.Essentials/memory.db）に保存され、同じマシン上のすべての MCP クライアントで共有されます。

# Custom memory path
fieldcure-mcp-essentials --memory-path /path/to/memory.db

# Or via environment variable
ESSENTIALS_MEMORY_PATH=/path/to/memory.db fieldcure-mcp-essentials

設定

Essentials の設定

デフォルトの設定ファイルは次のとおりです。

• Windows：%LOCALAPPDATA%/FieldCure/Mcp.Essentials/settings.json
• macOS/Linux：プラットフォームのローカルアプリデータフォルダーに FieldCure/Mcp.Essentials/settings.json を加えたパス

{
  "download_directory": "~/Downloads/mcp"
}

ダウンロードディレクトリの優先順位は次のとおりです。

1. CLI：--download-directory <path>
2. 環境変数：ESSENTIALS_DOWNLOAD_DIRECTORY
3. 設定ファイル：download_directory
4. デフォルト：~/Downloads/mcp

別の設定ファイルを指定するには、--settings-path <path> または ESSENTIALS_SETTINGS_PATH を使用してください。

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "essentials": {
      "command": "fieldcure-mcp-essentials"
    }
  }
}

検索エンジンを使用する場合：

{
  "mcpServers": {
    "essentials": {
      "command": "fieldcure-mcp-essentials",
      "args": ["--search-engine", "serper", "--search-api-key", "YOUR_KEY"]
    }
  }
}

VS Code（Copilot）

.vscode/mcp.json に追加します。

{
  "servers": {
    "essentials": {
      "command": "fieldcure-mcp-essentials"
    }
  }
}

ソースから（dotnet tool を使わない場合）

{
  "mcpServers": {
    "essentials": {
      "command": "dotnet",
      "args": [
        "run",
        "--project", "C:\\path\\to\\fieldcure-mcp-essentials\\src\\FieldCure.Mcp.Essentials"
      ]
    }
  }
}

データストレージ

データ	保存場所
メモリデータベース	%LOCALAPPDATA%/FieldCure/Mcp.Essentials/memory.db
設定ファイル	%LOCALAPPDATA%/FieldCure/Mcp.Essentials/settings.json
デフォルトのダウンロード先	~/Downloads/mcp
検索 API キー	環境変数（SERPER_API_KEY、TAVILY_API_KEY、SERPAPI_API_KEY）

プロジェクト構成

src/FieldCure.Mcp.Essentials/
├── Program.cs                  # MCP server entry point (stdio)
├── Configuration/
│   └── EssentialsSettings.cs   # Server settings and download directory resolution
├── Http/
│   └── SsrfGuard.cs            # SSRF protection (shared by http_request & web_fetch)
├── Memory/
│   └── MemoryStore.cs          # SQLite + FTS5 memory storage
├── Search/
│   ├── ISearchEngine.cs        # Search engine interface
│   ├── ICategorySearchEngine.cs # Category search interface (news, images, scholar, patents)
│   ├── SearchResult.cs         # Search result record
│   ├── BingSearchEngine.cs     # Bing scraping (default)
│   ├── DuckDuckGoSearchEngine.cs  # DuckDuckGo lite scraping
│   ├── FallbackSearchEngine.cs # Auto-rotate on CAPTCHA
│   ├── SerperSearchEngine.cs   # Serper.dev API (+ category search)
│   ├── TavilySearchEngine.cs   # Tavily API (+ news)
│   └── SerpApiSearchEngine.cs  # SerpApi API (+ category search)
└── Tools/
    ├── HttpRequestTool.cs      # http_request
    ├── WebSearchTool.cs        # web_search
    ├── WebFetchTool.cs         # web_fetch (SmartReader)
    ├── DownloadFileTool.cs     # download_file
    ├── CategorySearchTools.cs  # search_news / search_images / search_scholar / search_patents
    ├── RunCommandTool.cs       # run_command
    ├── RunJavaScriptTool.cs    # run_javascript (Jint sandbox)
    ├── WolframAlphaTool.cs     # wolfram_alpha (Full Results API, MathML pass-through)
    ├── GetEnvironmentTool.cs   # get_environment
    ├── ReadFileTool.cs         # read_file
    ├── WriteFileTool.cs        # write_file
    ├── SearchFilesTool.cs      # search_files
    └── MemoryTools.cs          # remember / forget / list_memories

開発

# Build
dotnet build

# Test
dotnet test

# Pack as dotnet tool
dotnet pack src/FieldCure.Mcp.Essentials -c Release

関連項目

AssistStudio エコシステムの一部です。

ライセンス

MIT