Purpose: Minimal, realistic find_files inputs and structured outputs, plus a representative MCP stdio server snippet. Exact host JSON varies by product; adapt keys to your client’s docs.

Illustrative shape: command (absolute path recommended), optional environment, optional working directory if the host supports it.

{
  "mcpServers": {
    "file-discovery-mcp": {
      "command": "/home/alice/bin/file-discovery-mcp",
      "env": {
        "FILE_DISCOVERY_MCP_ROOTS": "/home/alice/work/myproject:/home/alice/oss/contrib"
      }
    }
  }
}

• If FILE_DISCOVERY_MCP_ROOTS is omitted, only the server’s startup cwd is allowed (set cwd in the host when you can).
• Replace paths and top-level key (mcpServers vs servers) with whatever your editor or runtime expects.

Find all Go files under a repository root (basename glob only).

tools/call — name: find_files, arguments:

{
  "pattern": "*.go",
  "root": "/home/alice/work/myproject"
}

Structured result (success; matches order not guaranteed):

{
  "ok": true,
  "matches": [
    "/home/alice/work/myproject/cmd/file-discovery-mcp/main.go",
    "/home/alice/work/myproject/internal/findfiles/findfiles.go"
  ],
  "truncated": false,
  "backend": "fd",
  "root": "/home/alice/work/myproject",
  "pattern": "*.go",
  "max_results": 500
}

backend may be walk if fd is not used. max_results reflects the effective cap after defaults and clamping (500 here = default when the client omitted max_results).

Same tree, but only two directory levels below root, and at most 20 paths.

Arguments:

{
  "pattern": "*.md",
  "root": "/home/alice/work/myproject",
  "max_depth": 2,
  "max_results": 20
}

Structured result (success with truncation):

{
  "ok": true,
  "matches": [
    "/home/alice/work/myproject/README.md",
    "/home/alice/work/myproject/docs/README.md"
  ],
  "truncated": false,
  "backend": "walk",
  "root": "/home/alice/work/myproject",
  "pattern": "*.md",
  "max_results": 20
}

If more than 20 files matched, you would see truncated": true and at most 20 entries in matches.

Arguments (repo allowed only under /home/alice/work/myproject, but root points elsewhere):

{
  "pattern": "*.go",
  "root": "/etc"
}

Structured result:

{
  "ok": false,
  "code": "PATH_NOT_ALLOWED",
  "error": "allowlist: path \"/etc\" is not under allowed roots"
}

Exact error text may differ slightly; clients should branch on code, not parse error.

{
  "pattern": "   ",
  "root": "/home/alice/work/myproject"
}

Structured result:

{
  "ok": false,
  "code": "INVALID_PATTERN",
  "error": "pattern is required"
}

Arguments: {}

Structured result (representative):

{
  "version": "0.3.0",
  "description": "file-discovery-mcp: read-only filesystem discovery MCP server",
  "read_only": true,
  "filesystem_search_wip": false
}

• Using — invocation and stdio expectations.
• User guide — usage narrative.
• Troubleshooting — when searches fail unexpectedly.
• Client contract — full field definitions.