Fieldcure MCP Essentials

FieldCure MCP基础知识

 

特性

• 20个必备工具 --HTTP、网络搜索和获取、URL文件下载、运行时搜索引擎切换（获取/设置）、Wolfram|Alpha、shell、JavaScript沙箱、环境信息、文件读/写/搜索、持久内存+类别搜索（新闻、图像、学者、专利）
• 零配置 -默认必应搜索不需要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请求、web获取和文件下载会阻止私有IP范围和环回地址
• 跨客户 --适用于Claude Desktop、VS Code、AssistStudio和任何兼容MCP的客户端
• 标准运输 --通过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运行时 或以后

工具

类别搜索（SerpApi/Serper/Tavily）

始终注册。每个工具运行时都会保护活动引擎的功能，并返回一个描述性错误，指向 set_search_engine 当当前引擎不支持该类别时。

运行时发动机切换

web_search 对比 web_fetch 对比 download_file 对比 http_request

文档分析

web_fetch 和 read_file 可以将二进制文档解析为Markdown：

输出包括标题、表格、数学表达式([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的引擎：

# 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→ SerpApi→ 塔维利→ Bing/DuckDuckGo回退。

API密钥安全

区域

使用 region 本地化结果的参数：

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

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

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

没有 --search-engine，后备引擎（Bing→ DuckDuckGo）自动打开验证码。自由发动机依赖于刮擦，可能是间歇性的-- 强烈建议将基于API的引擎用于任何非琐碎的用途。

无密钥的显式付费引擎——MCP激励

当 --search-engine serper|tavily|serpapi 被明确地选择，但是没有配置API密钥（CLI arg， ESSENTIALS_SEARCH_API_KEY，或特定于引擎的env-var），服务器等待直到第一个 web_search 呼叫，然后通过以下方式向MCP客户端请求密钥 MCP激发。如果用户拒绝，后续提示会询问是否使用免费的Bing/DuckDuckGo进行搜索。拒绝这两个选项可以让工具软故障并显示明确的信息，以便LLM可以恢复。

没有Elicitation支持的客户端（包括较旧的CLI主机）会立即退回到免费引擎，与2.1之前的行为相匹配。缓存密钥在进程生命周期内有效；如果该工具使缓存无效，则主机可以在上游401/403之后重新引出。

Wolfram|Alpha

wolfram_alpha 呼叫 全面成果API v2 并返回混合内容——明文、MathML（为原生呈现MathML的客户端逐字传递，例如ChatPanel/WebView2）和嵌入为 ImageContent.API的 reinterpret=true 该标志始终处于打开状态，因此大多数拼写错误级别的故障都会在服务器端自动纠正；只有真正的解析失败出现 isError: true 和 assumptions > tips > didyoumeans 指导。

应用程序ID

集 WOLFRAM_APPID 到在以下位置获得的AppID developer.wolframalpha.com (选择“完整结果API”；免费套餐：每月2000次，非商业）。在支持Elicitation的MCP客户端上，密钥也可以在首次使用时交互式提供。被拒绝的AppID（401/403）会触发一次无效并重试，因此可以重新获取键入错误的密钥；现有的 ApiKeyResolverRegistry 重新引出cap（每个env-var插槽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 使用 金特 具有严格限制的发动机：

允许： 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： cmd.exe 在Windows和 /bin/sh 在Unix上。使用 shell 当命令需要特定语法时：

每个流的详细输出上限为 max_output_chars （默认值100000）。回应包括 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

配置

基本设置

默认设置文件为：

• 窗户： %LOCALAPPDATA%/FieldCure/Mcp.Essentials/settings.json
• macOS/Linux：平台本地应用程序数据文件夹+ FieldCure/Mcp.Essentials/settings.json

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

下载目录优先级为：

1. CLI： `--download-directory

`

1. 环境： ESSENTIALS_DOWNLOAD_DIRECTORY
2. 设置文件： download_directory
3. 违约： ~/Downloads/mcp

使用 --settings-path 或 ESSENTIALS_SETTINGS_PATH 指向不同的设置文件。

克劳德桌面

添加 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代码（副本）

添加 .vscode/mcp.json:

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

来自源代码（不含.NET工具）

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

数据存储

项目结构

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生态系统.

许可证

麻省理工学院