# swiftMCP

A comprehensive Swift implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), demonstrating multiple transport mechanisms for client-server communication.

## Overview

swiftMCP provides complete, working examples of MCP clients and servers in Swift, showcasing three different transport implementations:

- **stdio** - Standard input/output transport for process-based communication
- **httpPOST** - HTTP POST-based transport using Hummingbird web framework
- **httpGET** - HTTP GET with Server-Sent Events (SSE) for streaming responses

Each example includes both client and server implementations, making it easy to understand how MCP works across different transport layers.

The examples are designed to build on each other progressively. Start with **1_stdio** to learn the core MCP concepts using the simplest transport mechanism. Once you understand the fundamentals, move to **2_httpPOST** to see how the same protocol works over HTTP with request-response patterns. Finally, explore **3_httpGET** to understand real-time streaming responses with Server-Sent Events. This learning path takes you from basic process communication to a more sophisticated web service architecture.

## What is MCP?

The Model Context Protocol is a standardized protocol for communication between AI assistants and external tools/services. It enables:

- **Tool Discovery** - Dynamically list available capabilities
- **Tool Invocation** - Execute tools with structured parameters
- **Resource Access** - Read and manipulate external resources
- **Prompts** - Templated interactions for common tasks

## Project Structure

```
swiftMCP/
├── 1_stdio/           # Standard I/O transport example
│   ├── client/        # Swift client using subprocess pipes
│   └── server/        # Swift server using stdin/stdout
├── 2_httpPOST/        # HTTP POST transport example
│   ├── client/        # Swift HTTP client
│   ├── server/        # Hummingbird-based HTTP server
│   └── web-client.html # Browser-based client
├── 3_httpGET/         # HTTP GET + SSE transport example
│   ├── client/        # Swift HTTP client with streaming
│   ├── server/        # Hummingbird server with SSE support
│   └── web-client.html # Browser client with event streaming
└── common/            # Shared code
    ├── tools/         # Reusable tool implementations
    └── util/          # Common utilities (JSON-RPC, debug, etc.)
```

## Requirements

- macOS 14.0 or later
- Swift 6.1 or later
- Xcode 16.0 or later (for development)

## Getting Started

### 1. stdio Transport Example

The simplest example using standard input/output:

```bash
cd 1_stdio/client
swift run
```

This will:
1. Start the server as a subprocess
2. Connect to it via stdin/stdout pipes
3. List available tools
4. Call the tools
5. Display results

### 2. httpPOST Transport Example

HTTP-based communication:

```bash
# Terminal 1 - Start the server
cd 2_httpPOST/server
swift run

# Terminal 2 - Run the client
cd 2_httpPOST/client
swift run
```

Or open `2_httpPOST/web-client.html` in a browser to use the web interface.

### 3. httpGET Transport Example

Streaming HTTP with Server-Sent Events:

```bash
# Terminal 1 - Start the server
cd 3_httpGET/server
swift run

# Terminal 2 - Run the client
cd 3_httpGET/client
swift run
```

Or open `3_httpGET/web-client.html` in a browser for the streaming web interface.

## Features

### Transport Implementations

- **StdioTransport** - Efficient process-to-process communication
- **HTTPTransport** - RESTful API communication with JSON-RPC
- **SSETransport** - Real-time streaming updates

### Common Utilities

- **JSON-RPC 2.0** - Full implementation with request/response handling
- **Tool Framework** - Extensible tool registration and invocation
- **Health Checks** - Server health monitoring
- **Debug Utilities** - Comprehensive logging system
- **Notifications** - Event notification support

### Example Tools

- **Tool_1** - System LINUX command (Swift version check)
- **Tool_2** - Custom method handler demonstration
- **Tool_3** - Streaming data demonstration

## Architecture

Each example follows the same pattern:

1. **Server Setup**
   - Initialize MCP server with capabilities
   - Register tool handlers
   - Start transport listener

2. **Client Connection**
   - Create MCP client
   - Connect via chosen transport
   - Initialize handshake

3. **Tool Operations**
   - List available tools
   - Call tools with parameters
   - Handle responses

## Dependencies

This project uses the official [MCP Swift SDK](https://github.com/modelcontextprotocol/swift-sdk):

```swift
.package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.10.2")
```

HTTP examples also use:

```swift
.package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0")
```

## Development

### Building

```bash
# Build a specific example
cd 1_stdio/client
swift build

# Build in release mode
swift build -c release
```


## Use Cases

- **AI Assistant Integration** - Connect AI models to external tools
- **Development Tools** - Build IDE plugins and development assistants
- **Automation** - Create automated workflows with tool orchestration
- **Learning** - Understand MCP protocol implementation in Swift

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Resources

- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [MCP Swift SDK](https://github.com/modelcontextprotocol/swift-sdk)
- [Hummingbird Web Framework](https://github.com/hummingbird-project/hummingbird)

## Acknowledgments

Built with the official Model Context Protocol Swift SDK from the Model Context Protocol organization.

---

**Repository:** [github.com/koawood/swiftMCP](https://github.com/koawood/swiftMCP)