Skip to main content

Directory Structure

A walkthrough of every directory in the repository and its purpose.

Top-Level Layout​

claude-swiss-army-knife/
├── .env.example # Environment variable template
├── docker-compose.yml # Main Docker Compose (8 services)
├── compose-casaos.yaml # CasaOS appliance Compose
├── pyproject.toml # Python tooling config (pyink, pylint)
├── package.json # Root (just recharts dep, unused directly)
├── push-all.sh # Deployment helper script
├── .github/ # CI workflows and issue templates
├── scripts/ # Utility shell scripts
├── configs/ # Permission YAML and templates
├── mcp-servers/ # All MCP server source code
├── mcp-webui/ # Next.js 15 Web UI
└── docs-site/ # Docusaurus 3 documentation

mcp-servers/​

Each server follows the same pattern:

mcp-servers/<server>/
├── Dockerfile # Multi-stage Python build
├── pyproject.toml # Package metadata and dependencies
├── config.yaml.example # Example permission config
├── src/<server>_mcp/ # Python package
│ ├── __init__.py # Package docstring
│ ├── __main__.py # python -m entry point
│ ├── server.py # Main server class (extends BaseMCPServer)
│ ├── config_watcher.py # Hot-reload via watchfiles
│ ├── discover.py # Folder scanning for Web UI
│ └── tools/ # Tool implementation modules
│ └── __init__.py
└── tests/
├── __init__.py
└── test_smoke.py

ubuntu-server/​

The most complex MCP server with 12 tools:

FilePurpose
server.pyUbuntuServer class: tool registration, dispatch, config loading
path_mapper.pyPathMapper: translates host paths (/var/log) to container paths (/mnt/host/var/log)
tools/read_file.pyPath validation, file reading via safe_resolve_path
tools/write_file.pyContent write with permission check
tools/append_file.pyAppend mode file writing
tools/list_dir.pyDirectory listing with recursive option
tools/execute.pyCommand execution with shell injection prevention
tools/system_info.pypsutil-based CPU/RAM/disk/load/uptime queries
tools/service.pysystemd service status and management
tools/docker_mgmt.pyDocker ps, logs, restart via Docker CLI
config_watcher.pywatchfiles-based hot reload
discover.pyFolder structure discovery for Web UI tree

obsidian/​

FilePurpose
server.pyObsidianServer class: 9 tools for vault management
vault.pyVault class: filesystem operations, path safety, note enumeration
frontmatter.pyYAML frontmatter parsing, building, tag extraction, title detection
wikilinks.py[[wikilink]] extraction and backlink resolution across vault
discover.pyFolder discovery

synology-nas/​

FilePurpose
server.pySynologyServer class: 9 tools for NAS management
dsm_client.pyDSMClient: httpx-based DSM 7.x REST API client with TOTP auth
discover.pyShared folder discovery

github/​

FilePurpose
server.pyEntry point: delegates to ProxyServer
custom/__init__.pyGitHub-specific hooks: filter destructive tools, on_tools_cached

shared/​

DirectoryPurpose
mcp-permission-engine/Core permission library used by all servers
mcp-proxy/Generic proxy framework for wrapping external MCP servers

mcp-permission-engine/src/permission_engine/​

FilePurpose
__init__.pyPublic API: exports BaseMCPServer, PermissionEnforcer, models, context vars
models.pyPydantic v2 schemas: AccessLevel, PathRule, CommandRule, ToolRule, ServerConfig, ProxyConfig
config.pyConfigLoader: YAML loading with !ENV env var substitution
enforcer.pyPermissionEnforcer: core access checks (paths, commands, tools), safe_resolve_path, auth
resolver.pyPathResolver: glob matching, longest-match precedence, explicit-deny override
audit.pyAuditLogger: JSON Lines audit trail writer
users.pyUser authentication: SHA-256 salted keys, access modes (open/allowlist/blocklist)
server.pyBaseMCPServer: abstract base class for all MCP servers

mcp-webui/src/​

PathPurpose
middleware.tsAuth guard: checks iron-session cookie for all /api/* routes
app/layout.tsxRoot layout: dark theme, Toaster provider
app/page.tsxDashboard: server cards, health, stats, bulk actions
app/login/page.tsxAPI key login form
app/[server]/page.tsxServer detail: path tree, commands, tools, audit log
app/agents/page.tsxUser management: mode selector, user table, key generation
app/settings/page.tsxApp settings: scan interval, excludes, page size, sections
app/api/REST API routes (see API Routes)
components/Reusable UI components (see Components)
lib/API client, types, auth, config utilities

docs-site/docs/​

docs/
├── user/ # User Guide
│ ├── intro.md
│ ├── getting-started/ # 5 pages
│ ├── mcp-servers/ # 5 pages
│ ├── webui/ # 7 pages
│ ├── security/ # 4 pages
│ ├── deployment/ # 4 pages
│ └── troubleshooting/ # 3 pages
└── dev/ # Developer Guide
├── architecture/ # 3 pages
├── permission-engine/ # 8 pages
├── mcp-servers/ # 6 pages
├── proxy-server/ # 4 pages
├── webui/ # 7 pages
├── docs-site/ # 3 pages
└── contributing/ # 5 pages