README.md•4.15 kB
# Swift Test MCP Server
An [MCP](https://modelcontextprotocol.io) 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):
```bash
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):
```bash
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):
```ts
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 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:
```bash
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.