fieldcure-mcp-essentials

FieldCure MCP Essentials

 

Install once, get the basics. A Model Context Protocol (MCP) server that provides 20 essential tools — HTTP requests, web search & fetch, URL file downloads, Wolfram|Alpha computational knowledge, shell commands, JavaScript execution, file I/O, environment info, and persistent memory — for any MCP client. Category search (news, images, scholar, patents) and runtime engine switching (get/set) are always available; capabilities are guarded at invocation time against the active engine. Built with C# and the official MCP C# SDK.

Features

• 20 essential tools — HTTP, web search & fetch, URL file downloads, runtime search-engine switching (get/set), Wolfram|Alpha, shell, JavaScript sandbox, environment info, file read/write/search, persistent memory + category search (news, images, scholar, patents)
• Zero configuration — no API keys needed for default Bing search; optional API keys unlock Serper, Tavily, SerpApi (+ category search tools), and Wolfram|Alpha
• Document parsing — web_fetch and read_file extract text from PDF, DOCX, HWPX, PPTX, XLSX into Markdown. PDF text extraction is text-layer only; scanned PDFs without a text layer yield empty text. For OCR-backed indexing use fieldcure-mcp-rag.
• Sandboxed JavaScript — Jint engine with strict limits (timeout, statement count, recursion depth)
• SSRF protection — HTTP requests, web fetch, and file downloads block private IP ranges and loopback addresses
• Cross-client — works with Claude Desktop, VS Code, AssistStudio, and any MCP-compatible client
• Stdio transport — standard MCP subprocess model via JSON-RPC over stdin/stdout

Installation

dotnet tool install -g FieldCure.Mcp.Essentials

After installation, the fieldcure-mcp-essentials command is available globally.

From source

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

Requirements

• .NET 8.0 Runtime or later

Tools

| Tool | Description | Destructive | |------|-------------|:-----------:| | http_request | Full HTTP client (GET/POST/PUT/DELETE/PATCH/HEAD) with custom headers and body | — | | web_search | Search the web and return snippets (title, URL, description) | — | | web_fetch | Fetch a URL and extract content as Markdown — HTML pages and documents (PDF, DOCX, HWPX, PPTX, XLSX) | — | | download_file | Download URL content to disk with a configurable download directory, 100 MB limit, and atomic save | Yes | | run_command | Execute shell commands with working directory, environment variables, shell selection, and output truncation flags | Yes | | run_javascript | Sandboxed JavaScript execution (Jint) for math, data processing, JSON, regex | — | | wolfram_alpha | Wolfram|Alpha Full Results API — symbolic math, plots, unit conversions, constants; MathML passes through for native rendering | — | | get_environment | System info — local time, timezone, OS, hostname, username, .NET version | — | | read_file | Read files — text with offset/limit, documents (PDF, DOCX, HWPX, PPTX, XLSX) parsed to Markdown | — | | write_file | Write or append text to files with auto directory creation | Yes | | search_files | Search files by glob pattern and content (grep-like) | — | | remember | Store a key-value memory (persisted in SQLite) | — | | forget | Delete memories by key or keyword search | Yes | | list_memories | Search and list stored memories with FTS5 and pagination | — |

Category Search (SerpApi / Serper / Tavily)

Always registered. Each tool runtime-guards on the active engine's capabilities and returns a descriptive error pointing at set_search_engine when the current engine does not support the category.

| Tool | Description | SerpApi | Serper | Tavily | |------|-------------|:-------:|:------:|:------:| | search_news | Search recent news articles via Google News | Yes | Yes | Yes | | search_images | Search images with size/type filtering | Yes | Yes | — | | search_scholar | Search academic papers with citation counts | Yes | Yes | — | | search_patents | Search patent documents with inventor/assignee filtering | Yes | Yes | — |

Runtime engine switching

| Tool | Description | |------|-------------| | set_search_engine | Switch the active engine (bing, duckduckgo, serper, tavily, serpapi) at runtime. Paid-engine API keys resolve lazily via env var or MCP Elicitation on the next search; the switch itself takes only the engine name. Emits notifications/tools/list_changed on success. | | get_search_engine | Return the currently active engine and its category capabilities. Read-only; use this to reflect live engine state in host UIs or to check category support before calling a category search tool. |

web_search vs web_fetch vs download_file vs http_request

| | http_request | web_search | web_fetch | download_file | |---|---|---|---|---| | Purpose | API calls, raw HTTP | Web search | Read web pages | Save original files | | Response | Raw (JSON, HTML, etc.) | {title, url, snippet}[] | Markdown (body only) | JSON metadata with saved path | | Conversion | None | None | SmartReader HTML → Markdown | None | | Length limit | max_response_chars (default: unlimited, up to 1MB) | max_results (max 10) | max_length (max 20000) | 100 MB |

Document Parsing

web_fetch and read_file can parse binary documents into Markdown:

| Format | Extension | Detection | |--------|-----------|-----------| | PDF | .pdf | Content-Type / URL extension (text layer only; no OCR) | | Word | .docx | Content-Type / URL extension | | Hangul (HWPX) | .hwpx | URL extension (no standard Content-Type) | | PowerPoint | .pptx | Content-Type / URL extension | | Excel | .xlsx | Content-Type / URL extension |

Output includes headings, tables, math expressions ([math: LaTeX]), and slide/page separators.

File Downloads

download_file saves the original bytes from an HTTP(S) URL. If save_path is omitted, the tool infers a filename from Content-Disposition, the URL path, or a generated fallback name. Relative save_path values resolve under the configured download_directory; absolute paths are used as-is except for protected system directories.

The default download directory is ~/Downloads/mcp and is created automatically on first use. Downloads are written to a temporary file in the destination directory and then committed with an atomic move/replace, so failed or cancelled downloads do not leave a partial final file.

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

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

Web Search

Default engine is Bing (free, no API key needed). For more reliable results, use an API-based engine:

| Engine | Free Tier | Category Search | API Key | |--------|-----------|:---------------:|---------| | Bing (default) | Unlimited (scraping) | — | Not needed | | Serper | 2,500 one-time | news, images, scholar, patents | serper.dev | | SerpApi | 100/month | news, images, scholar, patents | serpapi.com | | Tavily | 1,000/month | news | 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

Environment Variable Auto-Detection

When --search-engine is omitted, the server scans environment variables and automatically selects the best available engine:

| Engine | Environment Variable | |--------|---------------------| | Serper | SERPER_API_KEY | | SerpApi | SERPAPI_API_KEY | | Tavily | TAVILY_API_KEY |

Detection priority: Serper → SerpApi → Tavily → Bing/DuckDuckGo fallback.

API Key Security

| Engine | Auth Method | Key Exposure | |--------|-------------|--------------| | Serper | HTTP header (X-API-KEY) | Not in URL | | Tavily | Authorization header (Bearer token) | Not in URL | | SerpApi | URL query parameter (api_key=xxx) | Visible in server logs |

Region

Use the region parameter for localized results:

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

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

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

Without --search-engine, a fallback engine (Bing → DuckDuckGo) auto-switches on CAPTCHA. Free engines rely on scraping and may be intermittent — an API-based engine is strongly recommended for any non-trivial use.

Explicit paid engine without a key — MCP Elicitation

When --search-engine serper|tavily|serpapi is selected explicitly but no API key is configured (CLI arg, ESSENTIALS_SEARCH_API_KEY, or engine-specific env var), the server waits until the first web_search call and then asks the MCP client for the key via MCP Elicitation. If the user declines, a follow-up prompt asks whether to run the search with free Bing/DuckDuckGo instead. Declining both lets the tool soft-fail with a clear message so the LLM can recover.

Clients without Elicitation support (including older CLI hosts) fall back to the free engine immediately, matching the pre-2.1 behaviour. Cached keys live for the process lifetime; the host can re-elicit after an upstream 401/403 if the tool invalidates the cache.

Wolfram|Alpha

wolfram_alpha calls the Full Results API v2 and returns mixed content — plaintext, MathML (passed through verbatim for clients that render MathML natively, e.g. ChatPanel/WebView2), and plot images embedded as ImageContent. The API's reinterpret=true flag is always on so most typo-level failures auto-correct server-side; only real parse failures surface isError: true with assumptions > tips > didyoumeans guidance.

AppID

Set WOLFRAM_APPID to the AppID obtained at developer.wolframalpha.com (select "Full Results API"; free tier: 2,000 calls/month, non-commercial). On MCP clients that support Elicitation the key can also be supplied interactively on first use. A rejected AppID (401/403) triggers a single invalidate-and-retry so a mistyped key can be re-elicited; the existing ApiKeyResolverRegistry re-elicit cap (2 per env-var slot) prevents loops.

⚠️ Use developer.wolframalpha.com, not developer.wolfram.com — the latter is a separate paid portal and will show "no permission to access any API keys" for free accounts.

The tool is always registered regardless of AppID status; without a key it returns a setup-guidance error so the model can inform the user instead of silently skipping.

Query tips (surfaced in the tool description)

• English only, simplified keyword form ('France population', not 'how many people live in France')
• Exponent notation 6*10^14, never 6e14
• Single-letter variables (x, y, n)
• Named physical constants ('speed of light', not 299792458)
• For equations with units, solve without units first
• RECOMMENDED / AVOID hints steer the model — simple arithmetic to run_javascript, general web queries to web_search, subjective/news questions away from Wolfram

JavaScript Sandbox

run_javascript uses the Jint engine with strict limits:

| Constraint | Value | |-----------|-------| | Timeout | 5s default, 30s max | | Max statements | 100,000 | | Recursion depth | 64 | | Strict mode | Enforced |

Allowed: Math.*, JSON, Date, RegExp, console.log, string/array methods, parseInt, encodeURIComponent, atob/btoa

Blocked: setTimeout, setInterval, require, import, .NET interop, eval()

Variables can be injected into the script scope for data pipeline use:

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

run_command defaults to the backward-compatible shell for the host: cmd.exe on Windows and /bin/sh on Unix. Use shell when a command requires specific syntax:

| Shell | Notes | |-------|-------| | auto | Default; cmd.exe on Windows, /bin/sh on Unix | | pwsh | PowerShell Core; recommended for PowerShell-native commands when installed | | powershell | Windows PowerShell fallback for Windows hosts without pwsh | | cmd | Explicit Windows cmd.exe | | bash | Explicit Bash when available | | sh | Explicit POSIX shell when available |

Verbose output is capped per stream with max_output_chars (default 100,000). Responses include shell_used, stdout_truncated, and stderr_truncated; truncated streams include an inline marker with the omitted character count.

Memory

Memories are stored in SQLite (%LOCALAPPDATA%/FieldCure/Mcp.Essentials/memory.db) and shared across all MCP clients on the same machine.

# 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

Configuration

Essentials settings

The default settings file is:

• Windows: %LOCALAPPDATA%/FieldCure/Mcp.Essentials/settings.json
• macOS/Linux: the platform local app-data folder plus FieldCure/Mcp.Essentials/settings.json

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

Download directory precedence is:

1. CLI: --download-directory <path>
2. Environment: ESSENTIALS_DOWNLOAD_DIRECTORY
3. Settings file: download_directory
4. Default: ~/Downloads/mcp

Use --settings-path <path> or ESSENTIALS_SETTINGS_PATH to point at a different settings file.

Claude Desktop

Add to claude_desktop_config.json:

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

With a search engine:

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

VS Code (Copilot)

Add to .vscode/mcp.json:

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

From source (without dotnet tool)

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

Data Storage

| Data | Location | |------|----------| | Memory database | %LOCALAPPDATA%/FieldCure/Mcp.Essentials/memory.db | | Settings file | %LOCALAPPDATA%/FieldCure/Mcp.Essentials/settings.json | | Default downloads | ~/Downloads/mcp | | Search API keys | Environment variables (SERPER_API_KEY, TAVILY_API_KEY, SERPAPI_API_KEY) |

Project Structure

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

Development

# Build
dotnet build

# Test
dotnet test

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

See Also

Part of the AssistStudio ecosystem.

License

MIT