Add MacOS troubleshooting guide

- Add troubleshooting guide for MacOS.
- Detail prerequisites: uv and npx.
- Explain testing CLI directly with uvx.
- Provide version check and search command examples.
- Explain testing MCP server with inspector.
- Show how to run inspector with uvx.
- Explain how to invoke tool via inspector.
- Include example JSON input for trial_searcher.

Author: imaurer

docs/troubleshooting/macos.md

@@ -0,0 +1,55 @@
+# MacOS Troubleshooting Guide
+
+**Prerequisites:**
+
+- Ensure you have `uv` installed. Recommended method for macOS:
+  ```bash
+  brew install uv
+  ```
+  For other systems or methods, see the [uv installation guide](https://docs.astral.sh/uv/install/). `uvx` is included with `uv`.
+- Ensure you have `npx` available (usually comes with Node.js/npm). Recommended method for macOS if needed:
+  ```bash
+  brew install node
+  ```
+
+**1. Testing the CLI Directly:**
+
+You can run `biomcp` commands directly without a full installation using `uvx`. This tests if the package is fetchable and the CLI commands execute.
+
+- Check the version:
+  ```bash
+  uvx --from biomcp-python biomcp version
+  # Expected Output (version may vary): biomcp version: 0.1.0
+  ```
+- Test a search command (e.g., trial search):
+  ```bash
+  uvx --from biomcp-python biomcp trial search --condition NSCLC --size 1 | head -n 5
+  # Expected Output (NCT ID and Title will vary):
+  # # Record 1
+  # Nct Number: NCT0XXXXXXX
+  # Study Title:
+  #   Some Title Related to NSCLC
+  # Study Url: https://clinicaltrials.gov/study/NCT0XXXXXXX
+  ```
+
+**2. Testing the MCP Server with Inspector:**
+
+This verifies that the server starts correctly and the tools are available via the Model Context Protocol.
+
+- Run the inspector, telling it to start your server using the `uvx` command (this mirrors how Smithery likely starts it):
+  ```bash
+  npx @modelcontextprotocol/inspector uvx --from biomcp-python biomcp run
+  ```
+- Open the MCP Inspector interface in your browser (usually `http://127.0.0.1:6274`).
+- You should see the list of available tools (e.g., `article_searcher`, `trial_protocol`, `variant_searcher`, etc.).
+- Try invoking a tool:
+  - Select `trial_searcher`.
+  - Enter valid JSON input matching the `TrialQuery` model, for example:
+    ```json
+    {
+      "conditions": ["Melanoma"],
+      "recruiting_status": "OPEN"
+    }
+    ```
+  - Click "Call Tool".
+  - You should see a Markdown-formatted list of results in the "Output" section.