{
  "markdown": "# FieldCure MCP Essentials\n\n[![NuGet](https://img.shields.io/nuget/v/FieldCure.Mcp.Essentials)](https://www.nuget.org/packages/FieldCure.Mcp.Essentials)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/fieldcure/fieldcure-mcp-essentials/blob/main/LICENSE)\n\nInstall once, get the basics. A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](https://github.com/modelcontextprotocol/csharp-sdk).\n\n## Features\n\n- **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)\n- **Zero configuration** — no API keys needed for default Bing search; optional API keys unlock Serper, Tavily, SerpApi (+ category search tools), and Wolfram|Alpha\n- **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`](https://github.com/fieldcure/fieldcure-mcp-rag).\n- **Sandboxed JavaScript** — Jint engine with strict limits (timeout, statement count, recursion depth)\n- **SSRF protection** — HTTP requests, web fetch, and file downloads block private IP ranges and loopback addresses\n- **Cross-client** — works with Claude Desktop, VS Code, AssistStudio, and any MCP-compatible client\n- **Stdio transport** — standard MCP subprocess model via JSON-RPC over stdin/stdout\n\n## Installation\n\n```bash\ndotnet tool install -g FieldCure.Mcp.Essentials\n```\n\nAfter installation, the `fieldcure-mcp-essentials` command is available globally.\n\n### From source\n\n```bash\ngit clone https://github.com/fieldcure/fieldcure-mcp-essentials.git\ncd fieldcure-mcp-essentials\ndotnet build\n```\n\n### Requirements\n\n- [.NET 8.0 Runtime](https://dotnet.microsoft.com/download/dotnet/8.0) or later\n\n## Tools\n\n| Tool | Description | Destructive |\n|------|-------------|:-----------:|\n| `http_request` | Full HTTP client (GET/POST/PUT/DELETE/PATCH/HEAD) with custom headers and body | — |\n| `web_search` | Search the web and return snippets (title, URL, description) | — |\n| `web_fetch` | Fetch a URL and extract content as Markdown — HTML pages and documents (PDF, DOCX, HWPX, PPTX, XLSX) | — |\n| `download_file` | Download URL content to disk with a configurable download directory, 100 MB limit, and atomic save | Yes |\n| `run_command` | Execute shell commands with working directory, environment variables, shell selection, and output truncation flags | Yes |\n| `run_javascript` | Sandboxed JavaScript execution (Jint) for math, data processing, JSON, regex | — |\n| `wolfram_alpha` | Wolfram&#124;Alpha Full Results API — symbolic math, plots, unit conversions, constants; MathML passes through for native rendering | — |\n| `get_environment` | System info — local time, timezone, OS, hostname, username, .NET version | — |\n| `read_file` | Read files — text with offset/limit, documents (PDF, DOCX, HWPX, PPTX, XLSX) parsed to Markdown | — |\n| `write_file` | Write or append text to files with auto directory creation | Yes |\n| `search_files` | Search files by glob pattern and content (grep-like) | — |\n| `remember` | Store a key-value memory (persisted in SQLite) | — |\n| `forget` | Delete memories by key or keyword search | Yes |\n| `list_memories` | Search and list stored memories with FTS5 and pagination | — |\n\n### Category Search (SerpApi / Serper / Tavily)\n\nAlways 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.\n\n| Tool | Description | SerpApi | Serper | Tavily |\n|------|-------------|:-------:|:------:|:------:|\n| `search_news` | Search recent news articles via Google News | Yes | Yes | Yes |\n| `search_images` | Search images with size/type filtering | Yes | Yes | — |\n| `search_scholar` | Search academic papers with citation counts | Yes | Yes | — |\n| `search_patents` | Search patent documents with inventor/assignee filtering | Yes | Yes | — |\n\n### Runtime engine switching\n\n| Tool | Description |\n|------|-------------|\n| `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. |\n| `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. |\n\n### `web_search` vs `web_fetch` vs `download_file` vs `http_request`\n\n| | `http_request` | `web_search` | `web_fetch` | `download_file` |\n|---|---|---|---|---|\n| Purpose | API calls, raw HTTP | Web search | Read web pages | Save original files |\n| Response | Raw (JSON, HTML, etc.) | `{title, url, snippet}[]` | Markdown (body only) | JSON metadata with saved path |\n| Conversion | None | None | SmartReader HTML → Markdown | None |\n| Length limit | `max_response_chars` (default: unlimited, up to 1MB) | `max_results` (max 10) | `max_length` (max 20000) | 100 MB |\n\n## Document Parsing\n\n`web_fetch` and `read_file` can parse binary documents into Markdown:\n\n| Format | Extension | Detection |\n|--------|-----------|-----------|\n| PDF | `.pdf` | Content-Type / URL extension (text layer only; no OCR) |\n| Word | `.docx` | Content-Type / URL extension |\n| Hangul (HWPX) | `.hwpx` | URL extension (no standard Content-Type) |\n| PowerPoint | `.pptx` | Content-Type / URL extension |\n| Excel | `.xlsx` | Content-Type / URL extension |\n\nOutput includes headings, tables, math expressions (`[math: LaTeX]`), and slide/page separators.\n\n## File Downloads\n\n`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.\n\nThe 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.\n\n```json\n{\n  \"url\": \"https://example.com/report.pdf\"\n}\n```\n\n```json\n{\n  \"url\": \"https://example.com/report.pdf\",\n  \"save_path\": \"reports/report.pdf\",\n  \"overwrite\": false\n}\n```\n\n## Web Search\n\nDefault engine is Bing (free, no API key needed). For more reliable results, use an API-based engine:\n\n| Engine | Free Tier | Category Search | API Key |\n|--------|-----------|:---------------:|---------|\n| Bing (default) | Unlimited (scraping) | — | Not needed |\n| Serper | 2,500 one-time | news, images, scholar, patents | [serper.dev](https://serper.dev) |\n| SerpApi | 100/month | news, images, scholar, patents | [serpapi.com](https://serpapi.com) |\n| Tavily | 1,000/month | news | [tavily.com](https://tavily.com) |\n\n```bash\n# Use Serper\nfieldcure-mcp-essentials --search-engine serper --search-api-key YOUR_KEY\n\n# Use Tavily\nfieldcure-mcp-essentials --search-engine tavily --search-api-key YOUR_KEY\n\n# Or via environment variables\nESSENTIALS_SEARCH_ENGINE=serper ESSENTIALS_SEARCH_API_KEY=xxx fieldcure-mcp-essentials\n```\n\n### Environment Variable Auto-Detection\n\nWhen `--search-engine` is omitted, the server scans environment variables and automatically selects the best available engine:\n\n| Engine | Environment Variable |\n|--------|---------------------|\n| Serper | `SERPER_API_KEY` |\n| SerpApi | `SERPAPI_API_KEY` |\n| Tavily | `TAVILY_API_KEY` |\n\nDetection priority: Serper → SerpApi → Tavily → Bing/DuckDuckGo fallback.\n\n### API Key Security\n\n| Engine | Auth Method | Key Exposure |\n|--------|-------------|--------------|\n| Serper | HTTP header (`X-API-KEY`) | Not in URL |\n| Tavily | Authorization header (`Bearer` token) | Not in URL |\n| SerpApi | URL query parameter (`api_key=xxx`) | Visible in server logs |\n\n### Region\n\nUse the `region` parameter for localized results:\n\n```json\n// Korean results\n{ \"query\": \"서울 맛집\", \"region\": \"ko-kr\" }\n\n// US English results\n{ \"query\": \"best restaurants NYC\", \"region\": \"en-us\" }\n\n// Global (default)\n{ \"query\": \"Python tutorial\" }\n```\n\nWithout `--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.**\n\n### Explicit paid engine without a key — MCP Elicitation\n\nWhen `--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](https://spec.modelcontextprotocol.io/specification/2025-06-18/client/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.\n\nClients 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.\n\n## Wolfram|Alpha\n\n`wolfram_alpha` calls the [Full Results API v2](https://products.wolframalpha.com/api/) 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.\n\n### AppID\n\nSet `WOLFRAM_APPID` to the AppID obtained at [developer.wolframalpha.com](https://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.\n\n> ⚠️ 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.\n\nThe 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.\n\n### Query tips (surfaced in the tool description)\n\n- English only, simplified keyword form (`'France population'`, not `'how many people live in France'`)\n- Exponent notation `6*10^14`, never `6e14`\n- Single-letter variables (`x`, `y`, `n`)\n- Named physical constants (`'speed of light'`, not `299792458`)\n- For equations with units, solve without units first\n- `RECOMMENDED / AVOID` hints steer the model — simple arithmetic to `run_javascript`, general web queries to `web_search`, subjective/news questions away from Wolfram\n\n## JavaScript Sandbox\n\n`run_javascript` uses the [Jint](https://github.com/sebastienros/jint) engine with strict limits:\n\n| Constraint | Value |\n|-----------|-------|\n| Timeout | 5s default, 30s max |\n| Max statements | 100,000 |\n| Recursion depth | 64 |\n| Strict mode | Enforced |\n\n**Allowed:** `Math.*`, `JSON`, `Date`, `RegExp`, `console.log`, string/array methods, `parseInt`, `encodeURIComponent`, `atob`/`btoa`\n\n**Blocked:** `setTimeout`, `setInterval`, `require`, `import`, `.NET interop`, `eval()`\n\nVariables can be injected into the script scope for data pipeline use:\n\n```\n1. http_request(url: \"https://api.example.com/data\") → {\"items\": [...]}\n2. run_javascript(\n     code: \"data.items.filter(x => x.price > 100).map(x => x.name)\",\n     variables: {\"data\": {\"items\": [...]}}\n   )\n```\n\n## Run Command\n\n`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:\n\n| Shell | Notes |\n|-------|-------|\n| `auto` | Default; `cmd.exe` on Windows, `/bin/sh` on Unix |\n| `pwsh` | PowerShell Core; recommended for PowerShell-native commands when installed |\n| `powershell` | Windows PowerShell fallback for Windows hosts without `pwsh` |\n| `cmd` | Explicit Windows `cmd.exe` |\n| `bash` | Explicit Bash when available |\n| `sh` | Explicit POSIX shell when available |\n\nVerbose 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.\n\n## Memory\n\nMemories are stored in SQLite (`%LOCALAPPDATA%/FieldCure/Mcp.Essentials/memory.db`) and shared across all MCP clients on the same machine.\n\n```bash\n# Custom memory path\nfieldcure-mcp-essentials --memory-path /path/to/memory.db\n\n# Or via environment variable\nESSENTIALS_MEMORY_PATH=/path/to/memory.db fieldcure-mcp-essentials\n```\n\n## Configuration\n\n### Essentials settings\n\nThe default settings file is:\n\n- Windows: `%LOCALAPPDATA%/FieldCure/Mcp.Essentials/settings.json`\n- macOS/Linux: the platform local app-data folder plus `FieldCure/Mcp.Essentials/settings.json`\n\n```json\n{\n  \"download_directory\": \"~/Downloads/mcp\"\n}\n```\n\nDownload directory precedence is:\n\n1. CLI: `--download-directory <path>`\n2. Environment: `ESSENTIALS_DOWNLOAD_DIRECTORY`\n3. Settings file: `download_directory`\n4. Default: `~/Downloads/mcp`\n\nUse `--settings-path <path>` or `ESSENTIALS_SETTINGS_PATH` to point at a different settings file.\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"essentials\": {\n      \"command\": \"fieldcure-mcp-essentials\"\n    }\n  }\n}\n```\n\nWith a search engine:\n\n```json\n{\n  \"mcpServers\": {\n    \"essentials\": {\n      \"command\": \"fieldcure-mcp-essentials\",\n      \"args\": [\"--search-engine\", \"serper\", \"--search-api-key\", \"YOUR_KEY\"]\n    }\n  }\n}\n```\n\n### VS Code (Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"essentials\": {\n      \"command\": \"fieldcure-mcp-essentials\"\n    }\n  }\n}\n```\n\n### From source (without dotnet tool)\n\n```json\n{\n  \"mcpServers\": {\n    \"essentials\": {\n      \"command\": \"dotnet\",\n      \"args\": [\n        \"run\",\n        \"--project\", \"C:\\\\path\\\\to\\\\fieldcure-mcp-essentials\\\\src\\\\FieldCure.Mcp.Essentials\"\n      ]\n    }\n  }\n}\n```\n\n## Data Storage\n\n| Data | Location |\n|------|----------|\n| Memory database | `%LOCALAPPDATA%/FieldCure/Mcp.Essentials/memory.db` |\n| Settings file | `%LOCALAPPDATA%/FieldCure/Mcp.Essentials/settings.json` |\n| Default downloads | `~/Downloads/mcp` |\n| Search API keys | Environment variables (`SERPER_API_KEY`, `TAVILY_API_KEY`, `SERPAPI_API_KEY`) |\n\n## Project Structure\n\n```\nsrc/FieldCure.Mcp.Essentials/\n├── Program.cs                  # MCP server entry point (stdio)\n├── Configuration/\n│   └── EssentialsSettings.cs   # Server settings and download directory resolution\n├── Http/\n│   └── SsrfGuard.cs            # SSRF protection (shared by http_request & web_fetch)\n├── Memory/\n│   └── MemoryStore.cs          # SQLite + FTS5 memory storage\n├── Search/\n│   ├── ISearchEngine.cs        # Search engine interface\n│   ├── ICategorySearchEngine.cs # Category search interface (news, images, scholar, patents)\n│   ├── SearchResult.cs         # Search result record\n│   ├── BingSearchEngine.cs     # Bing scraping (default)\n│   ├── DuckDuckGoSearchEngine.cs  # DuckDuckGo lite scraping\n│   ├── FallbackSearchEngine.cs # Auto-rotate on CAPTCHA\n│   ├── SerperSearchEngine.cs   # Serper.dev API (+ category search)\n│   ├── TavilySearchEngine.cs   # Tavily API (+ news)\n│   └── SerpApiSearchEngine.cs  # SerpApi API (+ category search)\n└── Tools/\n    ├── HttpRequestTool.cs      # http_request\n    ├── WebSearchTool.cs        # web_search\n    ├── WebFetchTool.cs         # web_fetch (SmartReader)\n    ├── DownloadFileTool.cs     # download_file\n    ├── CategorySearchTools.cs  # search_news / search_images / search_scholar / search_patents\n    ├── RunCommandTool.cs       # run_command\n    ├── RunJavaScriptTool.cs    # run_javascript (Jint sandbox)\n    ├── WolframAlphaTool.cs     # wolfram_alpha (Full Results API, MathML pass-through)\n    ├── GetEnvironmentTool.cs   # get_environment\n    ├── ReadFileTool.cs         # read_file\n    ├── WriteFileTool.cs        # write_file\n    ├── SearchFilesTool.cs      # search_files\n    └── MemoryTools.cs          # remember / forget / list_memories\n```\n\n## Development\n\n```bash\n# Build\ndotnet build\n\n# Test\ndotnet test\n\n# Pack as dotnet tool\ndotnet pack src/FieldCure.Mcp.Essentials -c Release\n```\n\n## See Also\n\nPart of the [AssistStudio ecosystem](https://github.com/fieldcure/fieldcure-assiststudio#packages).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 17713,
  "sha": "f97545a07627c9f13b09d52223dd0bc19b4e4d89058ea33b1afdd0e022e18ff5",
  "repo_slug": "fieldcure/fieldcure-mcp-essentials",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fieldcure_essentials_3cb39c4d/readme"
}