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 testmust be onPATH)
Install
From npm (recommended for users):
npm install -g swifttest-mcp-server
# or: pnpm add -g swifttest-mcp-server
# or: bunx swifttest-mcp-server (runs without installing globally)
From source (for contributors):
bun install
bun run build
If your environment restricts temp/cache locations, set
TMPDIRand/orXDG_CACHE_HOMEbefore 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
bunto be available onPATH(the published CLI shims tobun 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:
{}
- command:
-
Programmatic (TypeScript SDK):
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "swifttest-mcp-server",
args: [],
});
const client = new Client({ name: "example", version: "0.0.0" });
await client.connect(transport);
const result = await client.callTool({
name: "swift-test",
arguments: { packagePath: "/path/to/swift/package" },
});
console.log(result);
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
| Field | Type | Description |
|---|---|---|
packagePath | string? | Absolute or relative path to the Swift package root. Defaults to the server's current working directory. |
swiftArgs | string[]? | Extra arguments appended after 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 todist/server.mjsvia 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. prepublishOnlybuilds automatically when publishing to npm.
- Bundled with Vite + SWC to a single ESM entry:
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:
bun test
Troubleshooting:
- If you see an error like
keyValidator._parse is not a functionduring 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
bunat runtime for the CLI and server. - Requires a Swift toolchain available on
PATH. - ESM-only module; exports an entry at
dist/server.mjsfor completeness, though typical use is via the CLI.
License
MIT License. See LICENSE for details.
License
MIT License. See LICENSE for details.