xbill9/mcp-stdio-swift

Overview

This project provides a basic MCP server named hello-world-server that exposes a single tool: greet.

Key Features:

• Transport: Uses standard input/output (stdio) for MCP communication.
• Concurrency: Built on Swift's structured concurrency and ServiceLifecycle for graceful shutdown.
• Logging: Uses swift-log directed to stderr to ensure the stdout channel remains clean for protocol messages.
• SDK: Powered by the MCP Swift SDK.

Prerequisites

• Swift 6.0+ (or compatible Swift toolchain)
• Linux or macOS

Getting Started

1. Clone the repository:

``bash git clone <repository-url> cd mcp-stdio-swift ``

1. Build the project:

For development (debug build): ``bash make build # Executable will be at: .build/debug/mcp-stdio-swift ``

For production (release build): ``bash make release # Executable will be at: .build/release/mcp-stdio-swift ``

Usage

This server is designed to be executed by an MCP client (like Claude Desktop or a Gemini-powered IDE extension) that handles the stdio communication.

Manual Testing

To run the server manually for testing (starts listening on stdio):

.build/debug/mcp-stdio-swift

Testing with MCP Inspector

You can use the MCP Inspector to interactively test your server:

npx @modelcontextprotocol/inspector .build/debug/mcp-stdio-swift

Configuration for MCP Clients

If you are adding this to an MCP client config (e.g., claude_desktop_config.json), use the absolute path to the executable.

Example (using release build):

{
  "mcpServers": {
    "swift-hello-world": {
      "command": "/absolute/path/to/mcp-stdio-swift/.build/release/mcp-stdio-swift",
      "args": []
    }
  }
}

Note: Run make release before configuring the client.

Tools

greet

• Description: Get a greeting from the local stdio server.
• Parameters:

- param (string, required): The name or parameter to greet.

• Returns: The string passed in param.

Development

The project includes a Makefile to simplify common development tasks.

• Install dependencies: make install
• Run the server (debug): make run
• Build the server (debug): make build
• Build the server (release): make release
• Test: make test
• Lint: make lint
• Format: make format
• Clean artifacts: make clean

Project Structure

• Package.swift: Swift package definition, dependencies, and targets.
• Sources/mcp-stdio-swift/main.swift: Entry point defining the server, ServiceLifecycle setup, and tool implementations.
• Sources/mcp-stdio-swift/Handlers.swift: Tool implementations (greet).
• Sources/mcp-stdio-swift/MCPService.swift: Service lifecycle integration.
• Makefile: Shortcuts for build, test, and maintenance.

Package Metadata

Repository: xbill9/mcp-stdio-swift

Default branch: main

README: README.md