essentials

FieldCure MCP Essentials

安装一次，即可获得基础功能。这是一款 Model Context Protocol (MCP) 服务，为任何 MCP 客户端提供 20 个基础工具，包括 HTTP 请求、网页搜索与抓取、URL 文件下载、Wolfram|Alpha 计算知识、Shell 命令、JavaScript 执行、文件读写、环境信息和持久化记忆。类别搜索（新闻、图片、学术、专利）和运行时搜索引擎切换（获取/设置）始终可用；调用时会根据当前引擎检查功能是否受支持。使用 C# 和官方 MCP C# SDK 构建。

功能

• 20 个基础工具 — HTTP、网页搜索与抓取、URL 文件下载、运行时搜索引擎切换（获取/设置）、Wolfram|Alpha、Shell、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	将 URL 内容下载到磁盘，支持配置下载目录，限制为 100 MB，并采用原子保存	是
run_command	执行 Shell 命令，支持工作目录、环境变量、Shell 选择和输出截断标记	是
run_javascript	在沙盒中执行 JavaScript（Jint），用于数学计算、数据处理、JSON 和正则表达式	—
wolfram_alpha	Wolfram|Alpha Full Results API — 符号数学、绘图、单位换算、常数；MathML 会直接传递，以便原生渲染	—
get_environment	系统信息 — 本地时间、时区、操作系统、主机名、用户名、.NET 版本	—
read_file	读取文件 — 文本支持偏移量/限制，文档（PDF、DOCX、HWPX、PPTX、XLSX）可解析为 Markdown	—
write_file	写入或追加文本到文件，并自动创建目录	是
search_files	按 glob 模式和内容搜索文件（类似 grep）	—
remember	存储键值记忆（持久化于 SQLite）	—
forget	按键或关键词搜索删除记忆	是
list_memories	使用 FTS5 和分页搜索并列出已存储的记忆	—

类别搜索（SerpApi / Serper / Tavily）

始终注册。每个工具都会在运行时检查当前引擎的功能；如果当前引擎不支持该类别，则返回指向 set_search_engine 的说明性错误。

工具	描述	SerpApi	Serper	Tavily
search_news	搜索近期新闻文章（通过 Google News）	是	是	是
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 扩展名
Hangul (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 Elicitation

如果显式选择了 --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（原样传递给原生支持 MathML 渲染的客户端，例如 ChatPanel/WebView2），以及以 ImageContent 嵌入的绘图图像。API 的 reinterpret=true 标志始终启用，因此大多数拼写错误级别的问题会在服务端自动纠正；只有真正的解析失败才会返回 isError: true，并提供 assumptions > tips > didyoumeans 指引。

AppID

将 WOLFRAM_APPID 设置为在 developer.wolframalpha.com 获取的 AppID（选择 “Full Results API”；免费套餐：每月 2,000 次调用，仅限非商业用途）。支持 Elicitation 的 MCP 客户端也可以在首次使用时交互式提供密钥。如果 AppID 无效（401/403），系统会使其失效并重试一次，以便重新请求输错的密钥；现有的 ApiKeyResolverRegistry 重新请求上限（每个环境变量槽位 2 次）可防止陷入循环。

⚠️ 请使用 developer.wolframalpha.com，不要使用 developer.wolfram.com——后者是单独的付费门户，免费账户会显示“无权访问任何 API 密钥”。

无论 AppID 状态如何，都会注册此工具；如果未提供密钥，它会返回设置指引错误，让模型通知用户，而不是静默跳过。

查询提示（显示在工具描述中）

• 仅限英语，使用简化关键词形式（'France population'，而不是 'how many people live in France'）
• 指数记法使用 6*10^14，不要使用 6e14
• 使用单字母变量（x、y、n）
• 使用具名物理常数（'speed of light'，而不是 299792458）
• 对带单位的方程，先不带单位求解
• RECOMMENDED / AVOID 提示会引导模型：简单算术使用 run_javascript，一般网络查询使用 web_search，主观问题/新闻问题则避免使用 Wolfram

JavaScript 沙盒

run_javascript 使用 Jint 引擎，并施加严格限制：

限制	值
超时	默认 5s，最长 30s
最大语句数	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 默认使用主机的向后兼容 shell：Windows 上为 cmd.exe，Unix 上为 /bin/sh。如果命令需要特定语法，请使用 shell：

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 shell

每个流的详细输出上限由 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