mcpkit-guide

name	mcpkit-guide
description	Guide for using MCPKit Swift package to build MCP (Model Context Protocol) tool servers. Use when creating new MCP servers, defining tools, or integrating MCP into Swift projects.
allowed-tools	Read, Glob, Grep, Write, Edit, Bash

MCPKit Guide

This skill helps use the MCPKit Swift package to build MCP (Model Context Protocol) tool servers.

Package Overview

MCPKit is a Swift implementation of Model Context Protocol for building AI tool servers.

• Repository: https://github.com/Sunalamye/MCPKit
• Platforms: macOS 13+, iOS 16+
• License: MIT

Installation

// Package.swift
dependencies: [
    .package(url: "https://github.com/Sunalamye/MCPKit.git", from: "1.0.0"),
]

targets: [
    .target(
        name: "YourApp",
        dependencies: ["MCPKit"]
    ),
]

Architecture

MCPKit/
├── Core/
│   ├── MCPTool.swift          - Protocol & Schema types
│   ├── MCPContext.swift       - Execution context
│   ├── MCPToolRegistry.swift  - Tool registration
│   └── MCPHandler.swift       - JSON-RPC handler
├── Transport/
│   └── MCPHTTPServer.swift    - HTTP server
└── Tools/
    └── BuiltInTools.swift     - Basic tools

Quick Start

1. Define a Tool

import MCPKit

struct MyTool: MCPTool {
    static let name = "my_tool"
    static let description = "Description for AI to understand when to use this tool"

    static let inputSchema = MCPInputSchema(
        properties: [
            "param1": .string("Parameter description"),
            "param2": .integer("Optional param description")
        ],
        required: ["param1"]
    )

    private let context: MCPContext

    init(context: MCPContext) {
        self.context = context
    }

    func execute(arguments: [String: Any]) async throws -> Any {
        guard let param1 = arguments["param1"] as? String else {
            throw MCPToolError.missingParameter("param1")
        }

        // Your logic here...

        return ["success": true, "result": "..."]
    }
}

2. Create Context

class MyContext: MCPContext {
    var serverPort: Int = 8080

    func executeJavaScript(_ script: String) async throws -> Any? {
        return nil
    }

    func getBotStatus() -> [String: Any]? {
        return ["status": "ready"]
    }

    func triggerAutoPlay() {}

    func getLogs() -> [[String: Any]] { logs }
    func clearLogs() { logs.removeAll() }
    func log(_ message: String) {
        logs.append(["message": message, "timestamp": Date()])
    }

    private var logs: [[String: Any]] = []
}

3. Register Tools & Start Server

import MCPKit

let context = MyContext()
let registry = MCPToolRegistry.shared

// Register built-in tools
registry.registerBuiltInTools(context: context)

// Register custom tools
registry.register(MyTool.self, context: context)

// Start HTTP server
let server = MCPHTTPServer(port: 8765, context: context)
try await server.start()

Input Schema Types

// No parameters
static let inputSchema = MCPInputSchema.empty

// With parameters
static let inputSchema = MCPInputSchema(
    properties: [
        "stringParam": .string("String parameter"),
        "intParam": .integer("Integer parameter"),
        "numberParam": .number("Number parameter"),
        "boolParam": .boolean("Boolean parameter"),
        "objectParam": .object("Object parameter")
    ],
    required: ["stringParam"]
)

Error Handling

throw MCPToolError.missingParameter("paramName")
throw MCPToolError.invalidParameter("paramName", expected: "string")
throw MCPToolError.executionFailed("Reason")
throw MCPToolError.notAvailable("Resource name")

Built-in Tools

Tool	Description
get_status	Get MCP server status
get_help	Get API documentation
get_logs	Get debug logs
clear_logs	Clear all logs

JSON-RPC Methods

// Initialize
{"jsonrpc": "2.0", "method": "initialize", "id": 1}

// List tools
{"jsonrpc": "2.0", "method": "tools/list", "id": 2}

// Call tool
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {"name": "my_tool", "arguments": {"param1": "value"}},
  "id": 3
}

Checklist for New Tools

• Unique name (snake_case format)
• Clear description (helps AI understand usage)
• Correct inputSchema definition
• Implement execute() method (async throws)
• Handle errors with MCPToolError
• Register in registry

Reference Documentation

• MCPKit Reference - Full protocol, context API, and examples