Swift Test MCP Server

An MCP server that exposes a single swift-test tool for running swift test in a given Swift package directory. Useful when your MCP client (e.g., editor/agent) can call tools over stdio but you don’t want to give it a full interactive shell.

Prerequisites

• Bun v1.0+ (runtime used by the server and CLI)

• Swift toolchain (swift test must be on PATH)

Install

From npm (recommended for users):

From source (for contributors):

If your environment restricts temp/cache locations, set TMPDIR and/or XDG_CACHE_HOME before installing.

Usage

You can run the server as a CLI over stdio or embed it via MCP-aware clients.

• CLI (stdio server):

  • swifttest-mcp-server – starts the MCP server on stdio.

  • It requires bun to be available on PATH (the published CLI shims to bun dist/server.mjs).

MCP client configuration (stdio)

Point your MCP client at the CLI command (examples):

• Claude Desktop (JSON snippet conceptual example):

  • command: swifttest-mcp-server

  • args: []

  • env: {}

• Programmatic (TypeScript SDK):

MCP Usage

The server connects over stdio. After starting it (either bun run dev or bun run start), register it with your MCP-aware client using a stdio transport pointing at the Bun command you chose.

Tool: swift-test

The tool validates that the directory exists and contains Package.swift. It streams back combined stdout/stderr plus metadata (exit code, duration, command). Non-zero exits are reported as MCP tool errors so clients can react appropriately while still receiving the captured output.

Development

• Scripts

  • bun run dev – Run from TypeScript with live reload.

  • bun run typecheck – TypeScript type checking.

  • bun run build – Bundle to dist/server.mjs via Vite + SWC.

  • bun run start – Execute the bundled server.

  • bun test – Run tests.

• Build

  • Bundled with Vite + SWC to a single ESM entry: dist/server.mjs.

  • Runtime deps (@modelcontextprotocol/sdk, zod) are external and loaded at runtime.

  • prepublishOnly builds automatically when publishing to npm.

Testing

The repository uses Bun’s built‑in test runner. Tests spin up the MCP server over stdio and exercise the swift-test tool. One test injects a fake swift executable via PATH to avoid requiring a real Swift toolchain.

Run all tests:

Troubleshooting:

• If you see an error like keyValidator._parse is not a function during tests or calls, this server bypasses the SDK’s tool-argument schema conversion and validates inputs internally with Zod, avoiding that pathway. Ensure you are on the published version or rebuild from source.

Requirements and compatibility

• Requires bun at runtime for the CLI and server.

• Requires a Swift toolchain available on PATH.

• ESM-only module; exports an entry at dist/server.mjs for completeness, though typical use is via the CLI.

License

MIT License. See LICENSE for details.

License

MIT License. See LICENSE for details.