docs: Add comprehensive thv build command documentation #116

JAORMX · 2025-08-14T08:28:10Z

Summary

This PR adds comprehensive documentation for the thv build command, addressing issue #108.

What's being documented

New Documentation Files

📖 docs/toolhive/guides-cli/build-containers.mdx

Core thv build command usage and examples
Protocol scheme support (uvx://, npx://, go://)
Custom image tagging and Dockerfile generation
Kubernetes deployment workflows
Basic CI/CD integration patterns
Troubleshooting section with common issues

📖 docs/toolhive/guides-cli/advanced-cicd.mdx

Advanced CI/CD patterns for production environments
Multi-architecture builds with Docker Buildx
Supply chain security with SBOM, provenance, and signing
Efficient change detection strategies
Matrix builds for multiple MCP servers
Vulnerability scanning integration
GitLab CI examples

🔧 sidebars.ts

Added both new guides to the CLI guides section
Proper navigation structure and ordering

Key Features Covered

Protocol Schemes: Complete coverage of uvx://, npx://, and go:// schemes
Container Building: From basic usage to advanced production patterns
Kubernetes Integration: Pre-building containers for K8s deployments
CI/CD Workflows: GitHub Actions and GitLab CI examples
Security: Supply chain security, vulnerability scanning, and image signing
Best Practices: Production-ready patterns and troubleshooting guidance

Documentation Style

Follows established ToolHive documentation patterns
User-focused approach with practical examples
Clear separation between basic and advanced use cases
Comprehensive but not overwhelming
Includes proper cross-references and navigation

Closes #108

- Add build-containers.mdx guide covering thv build command usage - Add advanced-cicd.mdx guide for production CI/CD patterns - Update sidebar navigation to include both new guides - Cover protocol schemes (uvx://, npx://, go://) - Include Kubernetes deployment workflows - Add troubleshooting section and best practices - Include proper installation commands using GitHub releases Closes #108

vercel · 2025-08-14T08:28:18Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs-website	Ready	Preview	Comment	Aug 25, 2025 8:45pm

Copilot

Pull Request Overview

This PR adds comprehensive documentation for the thv build command, addressing the need for detailed guidance on building MCP server containers without running them. The documentation is structured as two complementary guides that cover basic usage through advanced production patterns.

Key changes:

Added comprehensive thv build command documentation with practical examples
Created advanced CI/CD patterns guide for production environments
Integrated both guides into the CLI guides navigation structure

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
sidebars.ts	Added new CLI guides to the navigation sidebar
docs/toolhive/guides-cli/build-containers.mdx	Comprehensive guide covering `thv build` basics, protocol schemes, Kubernetes workflows, and troubleshooting
docs/toolhive/guides-cli/advanced-cicd.mdx	Advanced CI/CD patterns including multi-architecture builds, security scanning, and GitLab CI examples

docs/toolhive/guides-cli/build-containers.mdx

docs/toolhive/guides-cli/advanced-cicd.mdx

Remove fragment from thv run link as suggested by GitHub Copilot review

Remove unused Tabs and TabItem imports that were causing lint failures

Signed-off-by: Juan Antonio Osorio <[email protected]>

danbarr · 2025-08-14T16:51:17Z

@claude please review this addition per the style guide @claude

claude · 2025-08-14T16:51:33Z

Claude finished @danbarr's task —— View job

Style Guide Review Complete ✅

I've thoroughly reviewed the new ToolHive build documentation against the repository's style guide. Overall, this is excellent documentation that follows most style guidelines correctly. Here's my detailed feedback:

✅ Style Guide Compliance - Strengths

Writing Style:

Excellent use of active voice throughout both documents
Consistent second-person address ("you", "your")
Casual yet professional tone that matches the style guide
Clear, straightforward language without excessive jargon
Proper sentence case in all headings
Correct capitalization of proper nouns (ToolHive, GitHub, Docker, etc.)

Content Structure:

Follows Diátaxis framework well - clear how-to guide structure
Logical progression from basic to advanced usage
Good separation of concerns between the two guides
Comprehensive but not overwhelming

Formatting:

Consistent use of monospace for commands, filenames, and code
Proper use of bold for UI elements and emphasis
Good use of code blocks with language specification
Clean markdown structure with proper spacing

🔧 Issues Requiring Fixes

Critical: Link Extension Issues (4 instances)

The Copilot review correctly identified link extension problems:

Line 325 in build-containers.mdx: ../guides-k8s/run-mcp-k8s.md should be .mdx
Line 333 in build-containers.mdx: ../guides-k8s/run-mcp-k8s.md should be .mdx
Line 325 in advanced-cicd.mdx: ../guides-k8s/run-mcp-k8s.md should be .mdx

Per the style guide: "Use relative file links (with .md/.mdx extensions) when referring to other pages." Since the target file exists as .md, these should use .md extension, not .mdx.

Anchor Link Verification

Line 126 in build-containers.mdx: The link ./run-mcp-servers.mdx#run-a-server-using-protocol-schemes references a valid anchor - verified it exists in the target file.

📋 Minor Style Suggestions

Consistent Protocol Naming: Both documents correctly maintain consistency in protocol scheme formatting (uvx://, npx://, go://)
Command Examples: Excellent use of realistic, practical examples throughout
Cross-references: Good use of relative links to maintain the documentation ecosystem

🎯 Content Quality Assessment

build-containers.mdx:

Comprehensive coverage of the thv build command
Excellent practical examples and use cases
Good troubleshooting section
Proper integration with existing documentation

advanced-cicd.mdx:

Advanced patterns are well-structured and practical
Good balance of GitHub Actions and GitLab CI examples
Security best practices are appropriately emphasized
Matrix build examples are particularly valuable

sidebars.ts:

Clean integration into existing navigation structure
Proper placement within CLI guides section

🚀 Recommendation

APPROVED with minor fixes required. The documentation is high-quality, well-structured, and follows the style guide effectively. Only the link extension corrections need to be addressed before merging.

Action Items

Fix 3 instances of .md extension in links to /guides-k8s/run-mcp-k8s.md
Run npm run markdownlint and npm run eslint to verify compliance

Review Tasks

Read repository style guide and CLAUDE.md files
Review build-containers.mdx for style compliance
Review advanced-cicd.mdx for style compliance
Review sidebars.ts changes
Analyze existing copilot feedback
Provide comprehensive style guide feedback

docs/toolhive/guides-cli/advanced-cicd.mdx

sidebars.ts

docs/toolhive/guides-cli/advanced-cicd.mdx

docs/toolhive/guides-cli/build-containers.mdx

Signed-off-by: Juan Antonio Osorio <[email protected]>

danbarr

The Vercel build is just failing because of broken links. I noted the fixes. Otherwise LGTM!

docs/toolhive/guides-cli/advanced-cicd.mdx

docs/toolhive/guides-cli/build-containers.mdx

Signed-off-by: Dan Barr <[email protected]>

Copilot AI review requested due to automatic review settings August 14, 2025 08:28

vercel bot deployed to Preview August 14, 2025 08:28 View deployment

Copilot AI reviewed Aug 14, 2025

View reviewed changes

docs: Fix link anchor in build-containers.mdx

2e9b27b

Remove fragment from thv run link as suggested by GitHub Copilot review

vercel bot deployed to Preview August 14, 2025 08:34 View deployment

docs: Fix ESLint errors in advanced-cicd.mdx

b4340c7

Remove unused Tabs and TabItem imports that were causing lint failures

vercel bot deployed to Preview August 14, 2025 08:36 View deployment

Fix linter issues

bd1a8d2

Signed-off-by: Juan Antonio Osorio <[email protected]>

vercel bot deployed to Preview August 14, 2025 13:40 View deployment

danbarr self-requested a review August 18, 2025 18:33

danbarr requested changes Aug 18, 2025

View reviewed changes

Address suggestions

15f007d

Signed-off-by: Juan Antonio Osorio <[email protected]>

vercel bot had a problem deploying to Preview August 20, 2025 06:10 Failure

danbarr requested changes Aug 20, 2025

View reviewed changes

docs/toolhive/guides-cli/advanced-cicd.mdx Outdated Show resolved Hide resolved

docs/toolhive/guides-cli/build-containers.mdx Outdated Show resolved Hide resolved

docs/toolhive/guides-cli/build-containers.mdx Outdated Show resolved Hide resolved

danbarr added 2 commits August 25, 2025 16:40

Fix broken links

6b7f95b

Signed-off-by: Dan Barr <[email protected]>

Merge branch 'main' into docs/add-thv-build-documentation

874a192

Signed-off-by: Dan Barr <[email protected]>

danbarr approved these changes Aug 25, 2025

View reviewed changes

vercel bot deployed to Preview August 25, 2025 20:45 View deployment

JAORMX enabled auto-merge (squash) August 26, 2025 10:18

eleftherias approved these changes Aug 26, 2025

View reviewed changes

JAORMX merged commit b8ad559 into main Aug 26, 2025
6 checks passed

JAORMX deleted the docs/add-thv-build-documentation branch August 26, 2025 10:27

docs: Add comprehensive thv build command documentation #116

docs: Add comprehensive thv build command documentation #116

Uh oh!

Conversation

JAORMX commented Aug 14, 2025

Summary

What's being documented

New Documentation Files

Key Features Covered

Documentation Style

Uh oh!

vercel bot commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danbarr commented Aug 14, 2025

Uh oh!

claude bot commented Aug 14, 2025 • edited by danbarr Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Style Guide Review Complete ✅

✅ Style Guide Compliance - Strengths

🔧 Issues Requiring Fixes

Critical: Link Extension Issues (4 instances)

Anchor Link Verification

📋 Minor Style Suggestions

🎯 Content Quality Assessment

🚀 Recommendation

Action Items

Review Tasks

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danbarr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Aug 14, 2025 •

edited

Loading

claude bot commented Aug 14, 2025 •

edited by danbarr

Loading