mirror of
https://github.com/samerfarida/mcp-ssh-orchestrator.git
synced 2026-11-20 20:33:16 +00:00
* fix: Remove unused variable in fix-markdownlint.py * fix: Remove unused code_block_lang variable * chore: Update documentation, workflows, and examples - Updated all wiki documentation files (markdownlint fixes) - Updated GitHub workflows and issue templates - Updated example configuration files - Updated metadata.json and pyproject.toml - Updated Dockerfile and compose files - Updated validation scripts Note: yamllint warnings are style-only (missing ---, line length) and don't affect functionality
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-FAQ.md # Frequently asked questions
├── 15-Glossary.md # Terms and definitions
└── assets/ # Images, diagrams, examples
├── diagrams/
└── 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 directly in markdown with
```mermaidcode blocks - 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:
1. Check GitHub Actions workflow status
2. Verify wiki repository exists and is accessible
3. Check for YAML syntax errors in configuration examples
4. Review workflow logs for specific error messages
### Broken links:
1. Use relative paths for internal wiki links
2. Test links before committing
3. Check that referenced pages exist
4. Use absolute URLs for external links
### Missing images:
1. Ensure images are in `docs/wiki/assets/` directory
2. Use relative paths in markdown: ``
3. Check file permissions and case sensitivity
### Content Issues
### Markdown rendering:
1. Use standard Markdown syntax
2. Avoid complex HTML in markdown files
3. Test rendering in GitHub preview
4. Check for special characters that need escaping
### Mermaid diagrams:
1. Embed diagrams directly in markdown using ` ```mermaid ` code blocks
2. Test diagram syntax with Mermaid preview tools
3. Keep diagrams close to the content they illustrate
## Contributing
### Adding New Content
1. **Create new markdown file** in appropriate location
2. **Update `_Sidebar.md`** to include new page
3. **Add cross-references** from related pages
4. **Test locally** before committing
5. **Submit pull request** for review
### Updating Existing Content
1. **Edit existing markdown file**
2. **Maintain consistent formatting**
3. **Update cross-references** if needed
4. **Test changes** before committing
5. **Submit pull request** for review
### Content Review Process
1. **Technical accuracy** - Verify all technical details
2. **Security context** - Ensure security implications are clear
3. **Consistency** - Check formatting and style consistency
4. **Completeness** - Verify all examples are complete and runnable
5. **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.