Docs cleanup

[angpt]

Reorganizing docs:

1. Added a troubleshooting guide
2. Cleaned up pre-requisites

Summary by CodeRabbit

• Documentation
  • Added comprehensive troubleshooting guide covering setup, configuration, and runtime failure issues.
  • Clarified runtime prerequisites and installation instructions based on MCP server package types.
  • Enhanced quick-start guidance with specific requirements for uvx, Node.js, and Docker runtimes.
  • Expanded documentation with guidance on common issues, including cache freshness and CORS configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: c9c226f8-0cf7-4707-9b65-b8ca5c2621a1

📥 Commits

Reviewing files that changed from the base of the PR and between bb2a210 and c1a508e.

📒 Files selected for processing (11)

• README.md
• docs/caching.md
• docs/configuration.md
• docs/daemon-configuration.md
• docs/index.md
• docs/installation.md
• docs/plugin-configuration.md
• docs/requirements.md
• docs/troubleshooting.md
• docs/tutorial.md
• mkdocs.yaml

---

Walkthrough

This pull request adds comprehensive troubleshooting documentation and restructures existing guides to clarify runtime/installation prerequisites for the mcpd daemon. The changes improve user onboarding by explaining which tools are required based on the MCP server runtime types they plan to use (uvx, npx, or Docker).

Changes

Troubleshooting and Prerequisites Documentation

Layer / File(s)	Summary
Comprehensive troubleshooting guide docs/troubleshooting.md	New 218-line guide covering debug logging setup, missing servers/registries, runtime mismatches, missing args/environment values, configuration reload semantics, CORS and API address issues, tool exposure, Docker host integration, plugin validation, and guidance on collecting information when requesting help.
Runtime prerequisites and requirements documentation README.md, docs/requirements.md, docs/installation.md, docs/index.md	README.md Quick Start prerequisites updated with runtime-specific installation guidance. docs/requirements.md restructured to map server prefixes (uvx:: → uv, npx:: → Node.js, docker:: → Docker) with optional and development-only tooling tables. docs/installation.md and docs/index.md added "Runtime prerequisites" callouts clarifying that mcpd binary and MCP server runtime installations are separate steps.
Troubleshooting references across documentation docs/configuration.md, docs/daemon-configuration.md, docs/caching.md, docs/plugin-configuration.md, docs/installation.md	Multiple documentation pages updated with cross-references directing readers to troubleshooting.md for hot reload issues, CORS/API address problems, cache staleness, plugin validation, and Docker server integration scenarios.
Documentation messaging refinement and tutorial clarification docs/index.md, docs/tutorial.md, mkdocs.yaml	docs/index.md refined capability messaging and added troubleshooting navigation link. docs/tutorial.md added explicit prerequisites note for uv and clarified time server runtime, added npx requirement for inspector tool, and simplified API example commands. mkdocs.yaml navigation updated to expose troubleshooting guide at top level.

Possibly related PRs

• mozilla-ai/mcpd#235: Updates README setup and installation guidance with Docker/npx/uvx runtime requirements, overlapping directly with prerequisites documentation changes in this PR.

Suggested reviewers

• peteski22
• aittalam

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title "Docs cleanup" is vague and generic, using a non-descriptive term that doesn't convey the specific nature of the changes (adding troubleshooting guide and reorganising prerequisites).	Consider using a more descriptive title such as "Add troubleshooting guide and reorganise documentation prerequisites" to clearly communicate the main changes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-cleanup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR reorganizes and clarifies the documentation around setup/runtime prerequisites, and adds a dedicated troubleshooting guide to help users diagnose common configuration and runtime issues when running mcpd.

Changes:

• Clarifies prerequisites by separating mcpd installation from MCP server runtime requirements (uv/npx/Docker) across README and docs.
• Adds a new Troubleshooting page and links to it from relevant docs (configuration, daemon config, caching, plugins, installation, index).
• Updates the tutorial to better call out required tools (e.g., uv for uvx-based examples; npx for mcpd inspector) and makes jq explicitly optional.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Clarifies runtime-specific prerequisites and optional helper tooling for examples.
mkdocs.yaml	Adds Troubleshooting to the site navigation and fixes CLI nav indentation.
docs/tutorial.md	Adds an up-front “what you need” note; clarifies npx requirement for inspector; makes jq optional.
docs/troubleshooting.md	Introduces a comprehensive troubleshooting guide with diagnostic steps and common resolutions.
docs/requirements.md	Reframes requirements around per-runtime needs and separates optional vs development-only tools.
docs/plugin-configuration.md	Adds a pointer to Troubleshooting for runtime plugin failures and binary checks.
docs/installation.md	Adds runtime prerequisite guidance and links Docker-in-Docker runtime issues to Troubleshooting.
docs/index.md	Updates positioning text to reflect runtime flexibility; links to Troubleshooting.
docs/daemon-configuration.md	Links CORS/API address diagnosis guidance to Troubleshooting.
docs/configuration.md	Adds a tip directing reload diagnosis to Troubleshooting.
docs/caching.md	Consolidates cache troubleshooting into “Common Issues” and links to Troubleshooting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[peteski22]

🙏🏼