Skip to content

docs: address setup friction points and client config pitfalls (#123) - #312

Draft
dandye wants to merge 1 commit into
mainfrom
docs/issue-123-setup-friction
Draft

docs: address setup friction points and client config pitfalls (#123)#312
dandye wants to merge 1 commit into
mainfrom
docs/issue-123-setup-friction

Conversation

@dandye

@dandye dandye commented Sep 9, 2026

Copy link
Copy Markdown
Collaborator

Resolves #123

Summary of Changes

This PR updates the setup, configuration, and troubleshooting documentation across README.md and docs/usage_guide.md to address common friction points encountered during first-time onboarding:

  1. uv Installation & Desktop GUI Client PATH Gotchas:
    • Documented uv installation options.
    • Clarified why desktop GUI applications (Claude Desktop, Cursor, VS Code / Cline) often do not inherit shell profile PATH additions (e.g., ~/.local/bin/uv), resulting in spawn uv ENOENT.
    • Documented running which uv and specifying the full absolute path in "command".
  2. Virtual Environment vs. Standalone uv:
    • Clarified that while using uv or Python from an existing virtual environment is supported, a standalone global uv installation is recommended because uv run handles per-server isolation automatically.
  3. Directory Depth & Entrypoint Gotchas (The SCC Copy-Paste Trap):
    • Highlighted the entry point differences: SecOps, SOAR, and GTI run server.py from nested package directories (secops_mcp, secops_soar_mcp, gti_mcp), whereas SCC runs scc_mcp.py directly from server/scc/.
    • Added warnings against setting --directory to <repo>/server/ or copy-pasting server.py for SCC.
  4. --env-file Flag Placement:
    • Documented that --env-file is a flag to uv run and must appear after run in the args array.
  5. SOAR SSL Certificate Verification & certifi:
    • Documented CA certificate requirements for SecOps SOAR connections on macOS (Install Certificates.command and SSL_CERT_FILE with certifi).
  6. Fallback Pattern (/bin/bash -c):
    • Provided an explicit /bin/bash -c fallback configuration example for environments where uv cannot be located by GUI desktop clients or when using existing virtual environments.

- Document uv installation and explain when/why absolute paths are required for desktop GUI clients.
- Clarify virtual environment vs. standalone uv usage.
- Highlight directory path levels and the SCC copy-paste trap (scc_mcp.py vs server.py).
- Clarify --env-file argument placement after 'run'.
- Document SOAR SSL certificate / certifi configuration requirements.
- Provide /bin/bash -c bypass recipe when uv is unavailable or in existing venvs.

Closes #123
@dandye
dandye marked this pull request as draft September 9, 2026 02:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: setup friction

1 participant