# 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.