acyment/swifttest-mcp-server

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):

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 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):

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

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:

bun test

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.