Files
mcp-ssh-orchestrator/docs/wiki
Sammy Farida d2e846a96f chore: production-ready Dockerfile updates (v0.2.1)
- Switch from Python 3.14 pre-release to stable Python 3.13-slim with pinned SHA256 digest
- Remove openssh-client (debug tool not needed in production)
- Remove libffi8 system dependency (not required by Python wheels)
- Fix trailing whitespace in apt-get command
- Change from editable install (pip install -e .) to production install (pip install .)
- Remove redundant .example configuration file copies
- Remove unused PATH modification for user local bin directory
- Simplify mkdir/chown operations

Updated documentation to reflect Python 3.13 base image reference
2025-10-31 00:32:34 -04:00
..

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/
    │   ├── 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:

  1. GitHub Actions Workflow (.github/workflows/sync-wiki.yml) triggers on push to main
  2. Wiki Repository is cloned from https://github.com/samerfarida/mcp-ssh-orchestrator.wiki.git
  3. Content Sync copies all files from docs/wiki/ to the wiki repository
  4. Validation checks markdown syntax and validates links
  5. Commit & Push updates the wiki repository with changes

Manual Sync

You can also trigger the sync manually:

  1. Go to Actions tab in GitHub
  2. Select Sync Wiki Documentation workflow
  3. Click Run workflow
  4. Select the branch (usually main)
  5. 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

  1. Edit files in docs/wiki/ directory
  2. Test locally using markdown preview
  3. Commit changes to your branch
  4. Create pull request for review
  5. Merge to main triggers automatic sync

File Guidelines

  • Use Markdown syntax for all content
  • Include diagrams using Mermaid syntax in .mmd files
  • 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: ![alt](assets/image.png)
  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. Store diagrams in .mmd files in assets/diagrams/
  2. Reference diagrams in markdown: ![Diagram](assets/diagrams/architecture.mmd)
  3. Test diagram syntax with Mermaid preview tools

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.