From 0c83046a511019570c945bce20baf55549db5b3d Mon Sep 17 00:00:00 2001 From: John Brahy Date: Thu, 19 Mar 2026 01:27:37 -0700 Subject: [PATCH] docs: add guidance for local custom MCP setup --- docs/configuration.md | 75 +++++++++++++++++++++++++++++++++++++++++ docs/getting-started.md | 6 ++++ docs/troubleshooting.md | 73 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 154 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index d10c6f52f..a647524a7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -76,6 +76,81 @@ This opens an interactive wizard showing which keys are configured and which are 4. Environment variables (`export BRAVE_API_KEY=...`) take precedence over saved keys 5. Anthropic models don't need Brave/Tavily — they have built-in web search +## MCP Servers + +GSD can connect to external MCP servers configured in project files. This is useful for local tools, internal APIs, self-hosted services, or integrations that aren't built in as native GSD extensions. + +### Config file locations + +GSD reads MCP client configuration from these project-local paths: + +- `.mcp.json` +- `.gsd/mcp.json` + +If both files exist, server names are merged and the first definition found wins. Use: + +- `.mcp.json` for repo-shared MCP configuration you may want to commit +- `.gsd/mcp.json` for local-only MCP configuration you do **not** want to share + +### Supported transports + +| Transport | Config shape | Use when | +|-----------|--------------|----------| +| `stdio` | `command` + optional `args`, `env`, `cwd` | Launching a local MCP server process | +| `http` | `url` | Connecting to an already-running MCP server over HTTP | + +### Example: stdio server + +```json +{ + "mcpServers": { + "my-server": { + "type": "stdio", + "command": "/absolute/path/to/python3", + "args": ["/absolute/path/to/server.py"], + "env": { + "API_URL": "http://localhost:8000" + } + } + } +} +``` + +### Example: HTTP server + +```json +{ + "mcpServers": { + "my-http-server": { + "url": "http://localhost:8080/mcp" + } + } +} +``` + +### Verifying a server + +After adding config, verify it from a GSD session: + +```text +mcp_servers +mcp_discover(server="my-server") +mcp_call(server="my-server", tool="", args={...}) +``` + +Recommended verification order: + +1. `mcp_servers` — confirms GSD can see the config file and parse the server entry +2. `mcp_discover` — confirms the server process starts and responds to `tools/list` +3. `mcp_call` — confirms at least one real tool invocation works + +### Notes + +- Use absolute paths for local executables and scripts when possible. +- For `stdio` servers, prefer setting required environment variables directly in the MCP config instead of relying on an interactive shell profile. +- If a server is team-shared and safe to commit, `.mcp.json` is usually the better home. +- If a server depends on machine-local paths, personal services, or local-only secrets, prefer `.gsd/mcp.json`. + ## All Settings ### `models` diff --git a/docs/getting-started.md b/docs/getting-started.md index 31b3b0748..a52480c2b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -21,6 +21,12 @@ If you use a non-Anthropic model, you'll need a search API key for web search. R See [Global API Keys](./configuration.md#global-api-keys-gsd-config) for details on supported keys. +### Set up custom MCP servers + +If you want GSD to call local or external MCP servers, add project-local config in `.mcp.json` or `.gsd/mcp.json`. + +See [Configuration → MCP Servers](./configuration.md#mcp-servers) for examples and verification steps. + ### VS Code Extension GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions. The extension provides: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 0152e9ffa..382cc25e2 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -95,6 +95,79 @@ rm -rf "$(dirname .gsd)/.gsd.lock" **Fix:** GSD auto-resolves conflicts on `.gsd/` runtime files. For content conflicts in code files, the LLM is given an opportunity to resolve them via a fix-merge session. If that fails, manual resolution is needed. +## MCP Client Issues + +### `mcp_servers` shows no configured servers + +**Symptoms:** `mcp_servers` reports no servers configured. + +**Common causes:** +- No `.mcp.json` or `.gsd/mcp.json` file exists in the current project +- The config file is malformed JSON +- The server is configured in a different project directory than the one where you launched GSD + +**Fix:** +- Add the server to `.mcp.json` or `.gsd/mcp.json` +- Verify the file parses as JSON +- Re-run `mcp_servers(refresh=true)` + +### `mcp_discover` times out + +**Symptoms:** `mcp_discover` fails with a timeout. + +**Common causes:** +- The server process starts but never completes the MCP handshake +- The configured command points to a script that hangs on startup +- The server is waiting on an unavailable dependency or backend service + +**Fix:** +- Run the configured command directly outside GSD and confirm the server actually starts +- Check that any backend URLs or required services are reachable +- For local custom servers, verify the implementation is using an MCP SDK or a correct stdio protocol implementation + +### `mcp_discover` reports connection closed + +**Symptoms:** `mcp_discover` fails immediately with a connection-closed error. + +**Common causes:** +- Wrong executable path +- Wrong script path +- Missing runtime dependency +- The server crashes before responding + +**Fix:** +- Verify `command` and `args` paths are correct and absolute +- Run the command manually to catch import/runtime errors +- Check that the configured interpreter or runtime exists on the machine + +### `mcp_call` fails because required arguments are missing + +**Symptoms:** A discovered MCP tool exists, but calling it fails validation because required fields are missing. + +**Common causes:** +- The call shape is wrong +- The target server's tool schema changed +- You're calling a stale server definition or stale branch build + +**Fix:** +- Re-run `mcp_discover(server="name")` and confirm the exact required argument names +- Call the tool with `mcp_call(server="name", tool="tool_name", args={...})` +- If you're developing GSD itself, rebuild after schema changes with `npm run build` + +### Local stdio server works manually but not in GSD + +**Symptoms:** Running the server command manually seems fine, but GSD can't connect. + +**Common causes:** +- The server depends on shell state that GSD doesn't inherit +- Relative paths only work from a different working directory +- Required environment variables exist in your shell but not in the MCP config + +**Fix:** +- Use absolute paths for `command` and script arguments +- Set required environment variables in the MCP config's `env` block +- If needed, set `cwd` explicitly in the server definition + ## Recovery Procedures ### Reset auto mode state