Initial public release: MCP SSH Unraid v1.0.0

Author: Jordan Munch O'Hare

.claude/CLAUDE.md

@@ -0,0 +1,61 @@
+# MCP SSH Unraid - Project Instructions
+
+## User Expectations
+
+### Accuracy and Verification
+- **Always count before claiming**: Never state tool counts or numbers without actually counting them first (e.g., use `grep -c` to count server.tool() calls)
+- **Be precise and consistent**: If documentation says "85 tools" and README says "86 tools", count the actual number and fix all inconsistencies
+- **Verify arithmetic**: When removing N tools from X total, actually verify the result instead of guessing
+
+### Docker Registry Push
+- **Retry on failure**: If `docker push` fails due to network timeout, retry when requested - the issue may be temporary
+- **Don't give up early**: Network issues can be transient, so attempt retries as requested
+
+### Removing Features
+When removing tools or features:
+1. Count the actual number of tools being removed
+2. Count the current total across all files
+3. Calculate the new total: current - removed = new
+4. Update ALL documentation consistently:
+   - `.claude/CLAUDE.md` - tool count
+   - `README.md` - tool count
+   - Test files - expected counts
+   - Tool registration tests
+
+## Version Bumping Workflow
+
+After bumping the version in this project, you MUST update the deployment configuration:
+
+1. **Update version in these files:**
+   - `package.json` - version field
+   - `src/http-server.ts` - McpServer version (line ~123)
+   - `src/http-server.ts` - health endpoint version (line ~313)
+   - `src/__tests__/http-server.test.ts` - expected version in test
+
+2. **Build and test:**
+   - Run `npm run build && npm test`
+   - Verify all 403 tests pass
+
+3. **Build and publish Docker image:**
+   - Build with both version tag and latest:
+     ```bash
+     docker build -f Dockerfile.http -t your-registry.com/your-org/mcp-ssh-unraid:{version} -t your-registry.com/your-org/mcp-ssh-unraid:latest .
+     ```
+   - Push both tags to registry:
+     ```bash
+     docker push your-registry.com/your-org/mcp-ssh-unraid:{version}
+     docker push your-registry.com/your-org/mcp-ssh-unraid:latest
+     ```
+   - If push fails with network timeout, retry as requested
+
+4. **Update deployment configuration:**
+   - Update your deployment config file (e.g., compose.yaml or kubernetes manifest)
+   - Update the `image:` tag to match the new version
+
+## Testing MCP Functionality
+
+When testing the deployed MCP server, use the MCP tools (e.g., `mcp__unraid-ssh__*`) to verify functionality. Test various filter combinations to ensure the filtering system works correctly.
+
+## Filter System
+
+All 82 tools support comprehensive output filtering. Filters are defined in `src/filters.ts` and applied via `...outputFiltersSchema.shape` pattern. When adding new tools, always include filter support.

.dockerignore

@@ -0,0 +1,52 @@
+# Dependencies
+node_modules
+npm-debug.log*
+yarn-error.log*
+
+# Build output
+dist
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Development files
+.devbox
+devbox.json
+devbox.lock
+.envrc
+
+# Version control
+.git
+.gitignore
+.jj
+
+# IDE and editor files
+.vscode
+.idea
+*.swp
+*.swo
+*~
+
+# Documentation
+*.md
+!README.md
+
+# Testing
+**/__tests__
+*.test.ts
+*.spec.ts
+vitest.config.ts
+coverage
+
+# Claude Code
+.claude
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+logs
+*.log

.env.example

@@ -0,0 +1,36 @@
+# SSH Connection Configuration
+
+# When running ON the Unraid server itself (in Docker):
+# - Use SSH_HOST=localhost or SSH_HOST=127.0.0.1
+# - Use network_mode: host in docker-compose.yml
+# - SSH_PRIVATE_KEY_PATH should be the path INSIDE the container (leave as is)
+# - Set SSH_KEY_HOST_PATH in docker-compose or .env for the host path
+
+# When running remotely (not on Unraid):
+# - Use SSH_HOST=unraid.local or your Unraid server's IP/hostname
+# - Comment out network_mode: host in docker-compose.yml
+
+# SSH server address (use 'localhost' when running on Unraid itself)
+SSH_HOST=localhost
+
+# SSH port
+SSH_PORT=22
+
+# SSH username (should be a dedicated read-only user)
+SSH_USERNAME=mcp-readonly
+
+# Path to SSH private key INSIDE the container (don't change this)
+SSH_PRIVATE_KEY_PATH=/home/mcp/.ssh/id_rsa
+
+# Path to SSH private key on the HOST (for docker-compose volume mount)
+# For Unraid: /root/.ssh/id_rsa_mcp or /boot/config/ssh/id_rsa_mcp
+# For other systems: /home/user/.ssh/id_rsa_mcp
+SSH_KEY_HOST_PATH=/root/.ssh/id_rsa_mcp
+
+# Command execution timeout in milliseconds (default: 15000 = 15 seconds)
+# Increase for long-running commands like database dumps
+COMMAND_TIMEOUT_MS=15000
+
+# Maximum consecutive command failures before circuit breaker opens (default: 3)
+# When circuit breaker is open, commands will fail immediately to prevent retry loops
+MAX_CONSECUTIVE_FAILURES=3

.envrc

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# Automatically sets up your devbox environment whenever you cd into this
+# directory via our direnv integration:
+
+eval "$(devbox generate direnv --print-envrc)"
+
+# check out https://www.jetify.com/docs/devbox/ide_configuration/direnv/
+# for more details

.github/workflows/docker-publish.yml

@@ -0,0 +1,58 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+
+      - name: Image digest
+        run: echo "Image pushed with digest ${{ steps.meta.outputs.digest }}"

.gitignore

@@ -0,0 +1,23 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Environment variables
+.env
+
+# Local MCP configuration
+mcp-config.json
+
+# Logs
+*.log
+logs/
+
+# Editor directories
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/project.yml

@@ -0,0 +1,84 @@
+# list of languages for which language servers are started; choose from:
+#   al               bash             clojure          cpp              csharp           csharp_omnisharp
+#   dart             elixir           elm              erlang           fortran          go
+#   haskell          java             julia            kotlin           lua              markdown
+#   nix              perl             php              python           python_jedi      r
+#   rego             ruby             ruby_solargraph  rust             scala            swift
+#   terraform        typescript       typescript_vts   yaml             zig
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "mcp-ssh-unraid"
+included_optional_tools: []

Dockerfile

@@ -0,0 +1,57 @@
+# Multi-stage build for optimal image size
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install all dependencies (including devDependencies for building)
+RUN npm ci
+
+# Copy source code and config
+COPY tsconfig.json ./
+COPY src ./src
+
+# Build TypeScript
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S mcp && \
+    adduser -u 1001 -S mcp -G mcp
+
+# Copy package files
+COPY package*.json ./
+
+# Install only production dependencies
+RUN npm ci --only=production && \
+    npm cache clean --force
+
+# Copy built application from builder
+COPY --from=builder /app/dist ./dist
+
+# Create directory for SSH keys
+RUN mkdir -p /home/mcp/.ssh && \
+    chown -R mcp:mcp /home/mcp/.ssh && \
+    chmod 700 /home/mcp/.ssh
+
+# Switch to non-root user
+USER mcp
+
+# Set environment for production
+ENV NODE_ENV=production
+
+# Health check to verify SSH connectivity
+# This will check if the SSH connection can be established
+# Runs every 30 seconds, timeout after 10 seconds
+# Note: Requires SSH_HOST, SSH_USERNAME, and SSH_PRIVATE_KEY_PATH env vars to be set
+HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
+  CMD node -e "const {NodeSSH}=require('node-ssh');const ssh=new NodeSSH();ssh.connect({host:process.env.SSH_HOST||'localhost',port:parseInt(process.env.SSH_PORT||'22'),username:process.env.SSH_USERNAME,privateKeyPath:process.env.SSH_PRIVATE_KEY_PATH}).then(()=>{ssh.dispose();process.exit(0)}).catch(()=>process.exit(1))" || exit 1
+
+# Run the HTTP/SSE MCP server
+CMD ["node", "dist/http-server.js"]