fieldcure-mcp-essentials: Instructions file for Claude Code

FieldCure.Mcp.Essentials

Cross-platform .NET 8 MCP server. Tools live in src/FieldCure.Mcp.Essentials/Tools/*.cs, packaged as NuGet FieldCure.Mcp.Essentials and distributed via dnx.

Tool authoring conventions

• Tools are static methods on a [McpServerToolType] class with [McpServerTool(Name = "snake_case", Destructive = true|false)] and a prescriptive [Description].
• Parameter names use snake_case (working_directory, max_output_chars) — they reach the LLM verbatim through the schema.
• Always return JsonSerializer.Serialize(result, McpJson.Options). McpJson.Options applies JsonNamingPolicy.SnakeCaseLower, so PascalCase anonymous types serialize as snake_case JSON automatically.
• Errors return { "error": "<message>" } rather than throwing.
• Tool/parameter descriptions are LLM-steering surface area: be prescriptive about when to use which option, not just what it is. Mirror the HttpRequestTool max_response_chars and RunCommandTool shell descriptions.

RunCommandTool subtleties

These are non-obvious and easy to break:

• cmd.exe (shell: "auto" on Windows, shell: "cmd") uses raw psi.Arguments, not ArgumentList. cmd does not parse argv with CommandLineToArgvW conventions, and ArgumentList leaks backslashes around embedded quotes (echo "a" → \"a\"). All other shells use ArgumentList.
• PowerShell shells (pwsh, powershell) use -EncodedCommand with a UTF-8 prelude ($OutputEncoding=[Console]::OutputEncoding=[System.Text.Encoding]::UTF8;) prepended before base64 encoding. Without the prelude, Windows PowerShell 5.1 emits OEM-codepage bytes (CP949 on Korean Windows) and the parent's UTF-8 reader sees mojibake.
• Output truncation must keep draining the pipe after the visible cap; breaking the read loop deadlocks verbose children on a full stdout/stderr pipe.
• The shell-availability cache stores successes only. Failures are re-probed so a transient cold-start miss (AV scan, slow disk) does not poison the rest of the process lifetime. Probe timeout is 5 s.