mirror of
https://github.com/samerfarida/mcp-ssh-orchestrator.git
synced 2026-11-20 12:23:31 +00:00
- Create 16-section wiki structure with LLM-optimized content - Integrate MCP security insights from Docker's MCP Security Explained blog - Add comprehensive security documentation (244+ security references) - Include Mermaid diagrams for architecture and security model - Set up GitHub Actions workflow for automated wiki synchronization - Migrate existing docs to docs/legacy/ with deprecation notices - Shorten SECURITY.md and update README.md to point to wiki - Add comprehensive troubleshooting, FAQ, and glossary sections - Implement policy-based access control documentation - Add deployment, integration, and observability guides Total: 231 KB of documentation across 16 sections Security: Policy enforcement, audit logging, compliance reporting Structure: LLM-friendly format with clear navigation and cross-references
Wiki Documentation
This directory contains the source files for the mcp-ssh-orchestrator GitHub wiki. These files are automatically synchronized to the GitHub wiki repository via GitHub Actions.
Directory Structure
docs/wiki/
├── Home.md # Landing page
├── _Sidebar.md # Navigation structure
├── 01-MCP-Overview.md # MCP protocol overview
├── 02-Risks.md # Security risks and threats
├── 03-Design-Goals.md # Project philosophy
├── 04-Architecture.md # System architecture
├── 05-Security-Model.md # Security architecture
├── 06-Configuration.md # Configuration overview
├── 06.1-servers.yml.md # Host inventory configuration
├── 06.2-credentials.yml.md # SSH authentication configuration
├── 06.3-policy.yml.md # Security policy configuration
├── 07-Tools-Reference.md # Complete MCP tools documentation
├── 08-Usage-Cookbook.md # Practical usage examples
├── 09-Deployment.md # Production deployment guide
├── 10-Integrations.md # MCP client integrations
├── 11-Observability-Audit.md # Monitoring and compliance
├── 12-Troubleshooting.md # Common issues and solutions
├── 13-Contributing.md # Development workflow
├── 14-Roadmap.md # Future features and milestones
├── 15-FAQ.md # Frequently asked questions
├── 16-Glossary.md # Terms and definitions
└── assets/ # Images, diagrams, examples
├── diagrams/
│ ├── architecture.mmd
│ ├── security-model.mmd
│ └── execution-flow.mmd
└── examples/
├── policy-examples/
└── docker-configs/
Synchronization Process
Automatic Sync
The wiki is automatically synchronized when changes are pushed to the main branch:
- GitHub Actions Workflow (
.github/workflows/sync-wiki.yml) triggers on push tomain - Wiki Repository is cloned from
https://github.com/samerfarida/mcp-ssh-orchestrator.wiki.git - Content Sync copies all files from
docs/wiki/to the wiki repository - Validation checks markdown syntax and validates links
- Commit & Push updates the wiki repository with changes
Manual Sync
You can also trigger the sync manually:
- Go to Actions tab in GitHub
- Select Sync Wiki Documentation workflow
- Click Run workflow
- Select the branch (usually
main) - Click Run workflow
Sync Requirements
- Write access to the main repository
- Wiki enabled for the repository
- GitHub Actions enabled for the repository
Editing Workflow
Making Changes
- Edit files in
docs/wiki/directory - Test locally using markdown preview
- Commit changes to your branch
- Create pull request for review
- Merge to main triggers automatic sync
File Guidelines
- Use Markdown syntax for all content
- Include diagrams using Mermaid syntax in
.mmdfiles - Test links before committing
- Follow naming conventions for consistency
- Add cross-references between related sections
Content Standards
- Purpose statement at the top of each page
- Clear section headers with consistent formatting
- Code examples with proper syntax highlighting
- Security context for all technical examples
- Cross-references to related sections
Validation
Automatic Validation
The sync process includes automatic validation:
- YAML syntax checking for configuration examples
- Markdown linting for formatting consistency
- Link checking for broken references
- Image validation for missing assets
Manual Validation
Before committing, validate your changes:
# Check markdown syntax
python -c "import yaml; yaml.safe_load(open('docs/wiki/06.3-policy.yml.md'))"
# Validate links (if link checker is installed)
markdown-link-check docs/wiki/Home.md
# Check for broken references
grep -r "\[.*\](" docs/wiki/ | grep -v "http"
Troubleshooting
Sync Issues
Wiki not updating:
- Check GitHub Actions workflow status
- Verify wiki repository exists and is accessible
- Check for YAML syntax errors in configuration examples
- Review workflow logs for specific error messages
Broken links:
- Use relative paths for internal wiki links
- Test links before committing
- Check that referenced pages exist
- Use absolute URLs for external links
Missing images:
- Ensure images are in
docs/wiki/assets/directory - Use relative paths in markdown:
 - Check file permissions and case sensitivity
Content Issues
Markdown rendering:
- Use standard Markdown syntax
- Avoid complex HTML in markdown files
- Test rendering in GitHub preview
- Check for special characters that need escaping
Mermaid diagrams:
- Store diagrams in
.mmdfiles inassets/diagrams/ - Reference diagrams in markdown:
 - Test diagram syntax with Mermaid preview tools
Contributing
Adding New Content
- Create new markdown file in appropriate location
- Update
_Sidebar.mdto include new page - Add cross-references from related pages
- Test locally before committing
- Submit pull request for review
Updating Existing Content
- Edit existing markdown file
- Maintain consistent formatting
- Update cross-references if needed
- Test changes before committing
- Submit pull request for review
Content Review Process
- Technical accuracy - Verify all technical details
- Security context - Ensure security implications are clear
- Consistency - Check formatting and style consistency
- Completeness - Verify all examples are complete and runnable
- Cross-references - Ensure links work and are relevant
Maintenance
Regular Tasks
- Review and update content quarterly
- Check for broken links monthly
- Update examples when configuration changes
- Add new sections as features are added
- Archive outdated content appropriately
Version Control
- Tag releases with corresponding documentation versions
- Maintain changelog for significant documentation changes
- Archive old versions when major updates occur
- Document breaking changes clearly
Support
For questions about the wiki documentation:
- Open an issue in the main repository
- Create a discussion for general questions
- Submit a pull request for documentation improvements
- Contact maintainers for urgent issues
License
This documentation is licensed under the same terms as the main project (Apache 2.0). See the main repository LICENSE file for details.