diff --git a/.markdownlint.json b/.markdownlint.json index 080ccd42..54465c02 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -20,6 +20,9 @@ "tables": false }, "no-bare-urls": false, + "no-inline-html": { + "allowed_elements": ["details", "summary"] + }, "proper-names": { "code_blocks": false, "names": ["Copilot", "GitHub", "ToolHive"] diff --git a/README.md b/README.md index 572e4c52..69c68c02 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Stacklok docs -[![GitHub deployments](https://img.shields.io/github/deployments/stacklok/docs-website/Production?logo=vercel&style=flat&label=Vercel%20deployment)](https://github.com/stacklok/docs-website/deployments/Production) +[![GitHub deployments][deployment-img]][deployment] This repository contains the public-facing docs for Stacklok's projects, hosted at [https://docs.stacklok.com](https://docs.stacklok.com). @@ -26,7 +26,7 @@ You'll need Node.js available (v22 recommended) or VS Code with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension and Docker. -[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/stacklok/docs-website) +[![Open in Dev Containers][devcontainer-img]][devcontainer] ```bash npm install @@ -80,3 +80,13 @@ the `main` branch. ## About This site is built with [Docusaurus](https://docusaurus.io/). + + + +[deployment-img]: + https://img.shields.io/github/deployments/stacklok/docs-website/Production?logo=vercel&label=Vercel%20deployment +[deployment]: https://github.com/stacklok/docs-website/deployments/Production +[devcontainer-img]: + https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue +[devcontainer]: + https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/stacklok/docs-website diff --git a/docs/toolhive/guides-cli/client-configuration.md b/docs/toolhive/guides-cli/client-configuration.md index 3b08f07b..203dc6e3 100644 --- a/docs/toolhive/guides-cli/client-configuration.md +++ b/docs/toolhive/guides-cli/client-configuration.md @@ -160,7 +160,8 @@ ToolHive provides. ## Troubleshooting -### Client is not detected by `thv client setup` +
+Client is not detected by `thv client setup` If ToolHive doesn't detect your client: @@ -177,7 +178,10 @@ If ToolHive doesn't detect your client: thv config register-client ``` -### Client can't connect to MCP server +
+ +
+Client can't connect to MCP server If your client can't connect to the MCP server: @@ -202,7 +206,10 @@ If your client can't connect to the MCP server: 4. Restart your client application. -### Client can connect but tools aren't available +
+ +
+Client can connect but tools aren't available If your client connects to the MCP server but tools aren't available: @@ -227,7 +234,10 @@ If your client connects to the MCP server but tools aren't available: 5. If you've implemented authentication for your MCP server, make sure the client has the necessary permissions to access the tools. -### Containerized client can't connect to MCP server +
+ +
+Containerized client can't connect to MCP server If you're running an MCP client inside a container and it can't connect to an MCP server running on the same host, make sure you use the correct host address. @@ -242,7 +252,10 @@ connectivity. Refer to your containerization platform's documentation for details on how to configure network access between containers and the host. -### VS Code can't connect to some streamable-http servers +
+ +
+VS Code can't connect to some streamable-http servers You might encounter errors with Visual Studio Code connecting to some Python-based MCP servers using the Streamable HTTP transport protocol: @@ -267,3 +280,5 @@ There are two workarounds: You can track a proposed fix for this issue in the [MCP Python SDK repository](https://github.com/modelcontextprotocol/python-sdk/pull/781). + +
diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx index 18644dd5..aa89b449 100644 --- a/docs/toolhive/guides-cli/custom-permissions.mdx +++ b/docs/toolhive/guides-cli/custom-permissions.mdx @@ -349,7 +349,8 @@ When creating and using permission profiles: ## Troubleshooting -### File system access issues +
+File system access issues If your MCP server can't access the file system as expected: @@ -365,7 +366,10 @@ If your MCP server can't access the file system as expected: 4. Restart the server with the updated profile or a corrected volume mount -### Network connectivity issues +
+ +
+Network connectivity issues If your MCP server can't connect to external services: @@ -381,3 +385,5 @@ If your MCP server can't connect to external services: 4. Try temporarily using the default `network` profile to confirm it's a permissions issue + +
diff --git a/docs/toolhive/guides-cli/install.mdx b/docs/toolhive/guides-cli/install.mdx index b1edbd63..cf381f3c 100644 --- a/docs/toolhive/guides-cli/install.mdx +++ b/docs/toolhive/guides-cli/install.mdx @@ -323,7 +323,8 @@ MCP servers. See [Explore the registry](./registry.md) and ## Troubleshooting -### Permission denied errors +
+Permission denied errors If you see "permission denied" errors when running ToolHive: @@ -346,7 +347,10 @@ If you see "permission denied" errors when running ToolHive: [Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) for more details. -### Upgrade error on Windows +
+ +
+Upgrade error on Windows If you encounter an error when upgrading ToolHive on Windows, it may be due to the ToolHive executable being locked by a running MCP server proxy. @@ -383,6 +387,8 @@ To resolve this: # repeat for each server ``` +
+ ### Other issues For other installation issues, check the diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 1e364780..12e44490 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -383,7 +383,8 @@ control your servers. ## Troubleshooting -### Server fails to start +
+Server fails to start If a server fails to start: @@ -392,7 +393,10 @@ If a server fails to start: 3. Check if the port is already in use 4. Look at the error message for specific issues -### Server starts but isn't accessible +
+ +
+Server starts but isn't accessible If a server starts but isn't accessible: @@ -407,7 +411,10 @@ If a server starts but isn't accessible: 3. Make sure clients are properly configured (see [Client configuration](client-configuration.md)) -### Server crashes or exits unexpectedly +
+ +
+Server crashes or exits unexpectedly If a server crashes or exits unexpectedly: @@ -430,3 +437,5 @@ If a server crashes or exits unexpectedly: ``` 4. Check if the server requires any secrets or environment variables + +
diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx index 8831c9f1..34980b0e 100644 --- a/docs/toolhive/guides-cli/secrets-management.mdx +++ b/docs/toolhive/guides-cli/secrets-management.mdx @@ -278,7 +278,8 @@ in the `MCPVault` vault and passes them to the `slack` MCP server as the ## Troubleshooting -### Keyring access issues +
+Keyring access issues If you run into errors related to the system keyring: @@ -294,7 +295,10 @@ If you run into errors related to the system keyring: sudo dnf install gnome-keyring ``` -### Secret not available to MCP server +
+ +
+Secret not available to MCP server If your MCP server can't access a secret: @@ -324,13 +328,19 @@ If your MCP server can't access a secret: thv logs ``` -### Forgot encryption password +
+ +
+Forgot encryption password If the keyring entry is lost or corrupted and you forget your encryption password, you won't be able to access your secrets. In this case, delete the [encrypted secrets file](#reset-your-secret-store) and recreate your secrets. -### Issues accessing 1Password secrets +
+ +
+Issues accessing 1Password secrets If you can't access 1Password secrets: @@ -353,3 +363,5 @@ If you can't access 1Password secrets: ```bash thv secret get op:////[section-name/] ``` + +
diff --git a/docs/toolhive/guides-k8s/deploy-operator-helm.md b/docs/toolhive/guides-k8s/deploy-operator-helm.md index 030643f6..0cab25ed 100644 --- a/docs/toolhive/guides-k8s/deploy-operator-helm.md +++ b/docs/toolhive/guides-k8s/deploy-operator-helm.md @@ -246,7 +246,8 @@ configured during installation. ## Troubleshooting -### Authentication error with ghcr.io +
+Authentication error with ghcr.io If you encounter an authentication error when pulling the Helm chart, it might indicate a problem with your access to the GitHub Container Registry @@ -259,7 +260,10 @@ your token has expired or been revoked. See the GitHub documentation to [re-authenticate to the registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic). -### Operator pod fails to start +
+ +
+Operator pod fails to start If the operator pod is not starting or is in a `CrashLoopBackOff` state, check the pod logs for error messages: @@ -284,7 +288,10 @@ Common causes include: resources available - **Image pull issues**: Verify that the cluster can pull images from `ghcr.io` -### CRDs installation fails +
+ +
+CRDs installation fails If the CRDs installation fails, you might see errors about existing resources or permission issues: @@ -304,7 +311,10 @@ helm uninstall toolhive-operator-crds helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds ``` -### Namespace creation issues +
+ +
+Namespace creation issues If you encounter permission errors when creating the `toolhive-system` namespace, create it manually first: @@ -319,7 +329,10 @@ Then install the operator without the `--create-namespace` flag: helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system ``` -### Helm chart not found +
+ +
+Helm chart not found If Helm cannot find the chart, ensure you're using the correct OCI registry URL and that your Helm version supports OCI registries (v3.8.0+): @@ -332,10 +345,15 @@ helm version helm pull oci://ghcr.io/stacklok/toolhive/toolhive-operator ``` -### Network connectivity issues +
+ +
+Network connectivity issues If you're experiencing network timeouts or connection issues: - Verify your cluster has internet access to reach `ghcr.io` - Check if your organization uses a proxy or firewall that might block access - Consider using a private registry mirror if direct access is restricted + +
diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.md b/docs/toolhive/guides-k8s/run-mcp-k8s.md index 0f5d8def..897008d7 100644 --- a/docs/toolhive/guides-k8s/run-mcp-k8s.md +++ b/docs/toolhive/guides-k8s/run-mcp-k8s.md @@ -393,7 +393,8 @@ visiting our [GitHub repository](https://github.com/stacklok/toolhive). ## Troubleshooting -### MCPServer resource not creating pods +
+MCPServer resource not creating pods If your `MCPServer` resource is created but no pods appear, first ensure you created the `MCPServer` resource in an allowed namespace. If the operator runs @@ -433,7 +434,10 @@ Other common causes include: for cluster-level permission issues - **Resource quotas**: Check if namespace resource quotas prevent pod creation -### MCP server pod fails to start +
+ +
+MCP server pod fails to start If the MCP server pod is created but fails to start or is in `CrashLoopBackOff`: @@ -460,7 +464,10 @@ Common causes include: - **Invalid arguments**: Check if the `args` field contains valid arguments for the MCP server -### Proxy pod connection issues +
+ +
+Proxy pod connection issues If the proxy pod is running but clients cannot connect: @@ -485,7 +492,10 @@ Common causes include: MCP server's capabilities - **Network policies**: Check if network policies are blocking communication -### Secret mounting issues +
+ +
+Secret mounting issues If secrets are not being properly mounted or environment variables are missing: @@ -510,7 +520,10 @@ Common causes include: - **Permission issues**: The operator automatically creates the necessary RBAC resources, but verify the ServiceAccount has access to read secrets -### Volume mounting problems +
+ +
+Volume mounting problems If persistent volumes or other volumes are not mounting correctly: @@ -536,7 +549,10 @@ Common causes include: - **Mount path conflicts**: Ensure mount paths don't conflict with existing directories -### Permission profile errors +
+ +
+Permission profile errors If the MCP server fails due to permission profile issues: @@ -560,7 +576,10 @@ Common causes include: - **Invalid JSON**: Verify the permission profile JSON is valid - **Missing key**: Ensure the specified key exists in the ConfigMap -### Resource limit issues +
+ +
+Resource limit issues If pods are being killed due to resource constraints: @@ -583,7 +602,10 @@ Solutions: - **Check node capacity**: Ensure cluster nodes have sufficient resources - **Review resource quotas**: Check namespace resource quotas and limits -### Debugging connectivity +
+ +
+Debugging connectivity To test connectivity between components: @@ -598,7 +620,10 @@ curl http://localhost:8080/health kubectl -n get endpoints ``` -### Getting more information +
+ +
+Getting more debug information For additional debugging information: @@ -612,3 +637,5 @@ kubectl -n get events --field-selector involvedObject.kind=MCPServer # Export MCPServer resource for inspection kubectl -n get mcpserver -o yaml ``` + +
diff --git a/docs/toolhive/tutorials/quickstart.mdx b/docs/toolhive/tutorials/quickstart.mdx index 21eefa4f..892d1dd9 100644 --- a/docs/toolhive/tutorials/quickstart.mdx +++ b/docs/toolhive/tutorials/quickstart.mdx @@ -292,7 +292,8 @@ server. Here are some next steps to explore: ## Troubleshooting -### Server fails to start +
+Server fails to start If the server fails to start, check: @@ -306,7 +307,10 @@ Try running with a specific port: thv run --port 8081 fetch ``` -### Client can't use the server +
+ +
+Client can't use the server If your AI client application can't use the server: @@ -314,3 +318,5 @@ If your AI client application can't use the server: - Check that your client is supported - Restart your client to pick up the new configuration - Verify the server is running with [`thv list`](../reference/cli/thv_list.md) + +
diff --git a/docs/toolhive/tutorials/toolhive-operator.mdx b/docs/toolhive/tutorials/toolhive-operator.mdx index 9d2b7a21..6c88bb38 100644 --- a/docs/toolhive/tutorials/toolhive-operator.mdx +++ b/docs/toolhive/tutorials/toolhive-operator.mdx @@ -438,7 +438,8 @@ Here are some next steps to explore: ## Troubleshooting -### Operator pod not starting +
+Operator pod not starting If the operator pod isn't starting, check the logs: @@ -446,7 +447,10 @@ If the operator pod isn't starting, check the logs: kubectl logs -n toolhive-system deployment/toolhive-operator ``` -### MCP server stuck in pending state +
+ +
+MCP server stuck in pending state Check the operator logs to see what's happening: @@ -460,7 +464,10 @@ Also check if there are any resource constraints: kubectl describe mcpserver fetch -n toolhive-system ``` -### Can't access MCP server +
+ +
+Can't access MCP server Verify the service is created and has endpoints: @@ -468,3 +475,5 @@ Verify the service is created and has endpoints: kubectl get service mcp-fetch-proxy -n toolhive-system kubectl get endpoints mcp-fetch-proxy -n toolhive-system ``` + +