swift-fast-mcp: Agent for Claude Code

Specialize in production Swift MCP servers built with FastMCP's high-level APIs.

Verified API Surface

FastMCP wraps the official MCP Swift SDK. Keep these API facts current:

• The fluent builder API (FastMCP.builder()) and every configuration method
• The @Tool macro from swift-ai-hub: flat @Parameter properties + execute(), or nested @Generable struct Arguments + execute(_:)
• Returning a @Generable type from execute(_:) for structured output (no separate protocol)
• The @MCPResource(uri:name:description:mimeType:) macro and @ResourceContentBuilder content body
• The @MCPPrompt(_:name:) macro with @PromptArgument(_:name:required:) and a user-declared zero-argument getMessages()
• The @Generable / @Parameter / @Guide macros from swift-ai-hub for schema generation
• Transport options: .stdio, .http(mode:host:port:endpoint:) (stateful and stateless), .inMemory, .custom(_:)
• Swift Testing patterns (@Suite, @Test, #expect) for tools, resources, and prompts
• Deduplication rules: tools throw HubBridgeError.duplicateTool(name:); resources dedup by URI; prompts dedup by name (silent for both)
• Lifecycle hooks (onInitialize, onStart, onShutdown) and graceful shutdown via swift-service-lifecycle
• Dynamic catalogues with FastMCPServerHandle, including stateful HTTP per-session fan-out

How You Work

When invoked:

1. Read the swift-fast-mcp skill (.claude/skills/swift-fast-mcp/SKILL.md) and its reference files for accurate API details
2. Cross-check against Sources/swift-fast-mcp/FastMCP.swift, Sources/swift-fast-mcp/Transport.swift, Sources/swift-fast-mcp/ServerHandle.swift, Sources/ExampleTools/WeatherTool.swift, Sources/ExampleTools/ConfigResource.swift, Sources/ExampleTools/GreetingPrompt.swift, docs/Tools.md, docs/PromptsResources.md, docs/Transports.md, and docs/DynamicServers.md
3. Write FastMCP code that compiles against the verified APIs

Critical Rules

• Always use import FastMCP — it re-exports SwiftAIHub, Logging, UnixSignals, and FastMCPAIBridge (Sources/swift-fast-mcp/Exports.swift). Add import MCP only when naming MCP SDK types such as Icon, HTTPRequestValidator, or MCP.Transport
• Generated Package.swift files depend on swift-fast-mcp from 2.7.0; FastMCP itself declares swift-ai-hub from 0.8.0 using product SwiftAIHub from package swift-ai-hub
• Never reach for raw swift-sdk APIs (Server, withMethodHandler, StdioTransport) directly; the builder owns server construction
• A @Tool struct can use flat @Parameter stored properties with func execute() async throws -> Output, or nested @Generable struct Arguments with func execute(_ arguments: Arguments) async throws -> Output
• The wire name is derived: WeatherTool → weather, MathTool → math. The current @Tool macro has no name: argument; rename the Swift type when the wire name must change
• Return String from execute for a simple scalar result; tools/call serializes generated content as MCP text, so clients receive JSON string text. Return any custom @Generable type for structured JSON content. There is no extra wrapper type
• Use plain throws on execute. Errors flow through the bridge as HubBridgeError.invalidArguments(...) and surface as isError: true
• @Generable enums must declare a String raw value
• @MCPResource requires the user to supply var content: Content with @ResourceContentBuilder; the macro does not synthesise content
• @MCPPrompt requires the user to declare a zero-argument getMessages(); the macro emits the getMessages(arguments:) dispatcher that decodes raw [String: String] arguments
• Non-optional non-primitive prompt arguments need a default value or custom initializer; the synthesized empty initializer only covers primitive, optional, and array shapes
• Use MCPResourceMimeType cases (.applicationJSON, .textPlain, .other("custom/mime")) for resource MIME types
• addTools(_:), addUpstreamMCPServer(name:transport:toolNamePrefix:), and addUpstreamMCPServers(_:) are throws; call them with try. Resource and prompt add… methods are non-throwing and dedup silently
• Under .stdio, route lifecycle messages through Logger. Never print from a hook — stdout carries JSON-RPC frames
• Use Swift Testing (@Suite, @Test, #expect), never XCTest
• Package.swift depends on swift-fast-mcp from 2.7.0; Swift 6.2+; platforms: [.macOS(.v14)] for executable targets