windows-host-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP server (Node/TypeScript, stdio transport) that gives an MCP agent SSH access to one or more Windows machines — running commands, transferring files, and driving long-running/interactive jobs, all over ssh2. It's the windows-host MCP server available in this session (mcp__windows-host__* tools).

Commands

npm run dev      # tsx watch src/index.ts — run against live env vars
npm run check    # tsc --noEmit — type-check only, fastest correctness check
npm run build    # tsc → dist/
npm run inspect  # npx @modelcontextprotocol/inspector node dist/index.js — interactive tool testing

No test suite exists in this repo. npm run check is the main correctness gate before committing.

The server needs a host configuration to start (WINDOWS_HOSTS_CONFIG pointing at a JSON file, or the flat WINDOWS_SSH_* env vars — see README.md and hosts.example.json/.env.example). Without one, loadConfig() in src/config.ts throws immediately.

Published only via GitHub (no npm registry publish access from this environment) — releases are git tags (vX.Y.Z) on github.com/thnak/windows-host-mcp. Install/update is git clone + npm link, not npm install -g git+https://...: that was the original design but testing found it genuinely corrupts the install on some npm versions — npm's git-dependency packing step silently dropped top-level files from this package's dist/ and dropped @modelcontextprotocol/sdk's dist/ entirely, even with --ignore-scripts. git clone + npm install + npm link was verified to work reliably and is now the only documented path; cliUpdate.ts's update subcommand mirrors it (git fetch --tags + git checkout <tag> + npm install inside the existing checkout, resolved via import.meta.url back to the package root) rather than re-invoking npm's git-install machinery. dist/ is committed to the repo (unusual for a TS project, but deliberate — it's what makes a bare git checkout <tag> immediately runnable with no build step, and was also motivated by an earlier, now-moot problem: a prepare: npm run build script couldn't reliably find tsc on PATH inside npm's git-dependency install path). Rebuild and commit dist/ before tagging any release (npm run build, then git add dist) — nothing else does this for you.