How cocoanetics/swiftmcp works
Overall Project Components
a. Core Library (Sources/SwiftMCP)
• Components:
• Extensions: Utility extensions enhancing arrays, dictionaries, and strings.
• Models: Structures defining the JSON-RPC messages, schema, and resource representations.
• Protocols: Definition of the MCP server protocol.
• Transport: Contains the implementations for different transports such as HTTP+SSE and standard I/O.
• OpenAPI integration: Components for generating and serving OpenAPI specifications and AI plugin manifests.
• Documentation: The “.docc” folder with articles, tutorials, and examples describing the core concepts.
b. Macros & Diagnostics (Sources/SwiftMCPMacros)
• Handles the compile-time extraction of metadata and documentation using macros like @MCPServer and @MCPTool.
• These macros add an aspect of automated documentation generation and diagnostic logging.
c. Demo Application (Demos/SwiftMCPDemo)
• Provides a command-line application demo showing how to utilize different transport options.
• Contains examples like the Calculator, different command implementations (StdioCommand, HTTPSSECommand), and support for logging and error handling.
d. Tests (Tests/SwiftMCPTests)
• Encompasses unit tests ensuring the correct functionality of tools, transport mechanisms, macros, and server behaviors.
Relationships and Interactions
• The MCP Server and Tools: Annotated with the custom macros, the server classes (for example in the demos) are enhanced with automatic metadata extraction. Tools defined by the @MCPTool attribute become available to clients over JSON-RPC.
• Transports: The core library offers multiple transport implementations that abstract how messages flow:
– HTTP+SSE Transport (HTTPSSETransport) for web applications.
– StdioTransport for command-line usage.
These transports interact with the MCP Server component by forwarding incoming JSON-RPC requests and relaying responses.
• OpenAPI Integration: When enabled, the server exposes endpoints such as /openapi.json and the AI plugin manifest at /.well-known/ai-plugin.json. This makes it easier for external systems (like AI models) to integrate with the MCP server.
• Authorization: The transport layer includes optional authorization checks (e.g., via a token) that gate access to server functionality.
• Logging and Diagnostics: Log handlers (like OSLogHandler) and diagnostics provided through the macros ensure that system interactions and errors are logged and reviewed in testing and production environments.
Architectural Patterns / Design Principles
• Modular design: Separation of concerns between core MCP logic, transport mechanisms, macros for metadata extraction, and separate demos/tests.
• Extensibility: Use of protocols and macros makes it straightforward to extend functionality with custom MCP servers and tools.
• Layered Communication: The JSON-RPC protocol is abstracted from transport layers, ensuring flexibility in client-server communication.
• Testing Driven: A dedicated test suite ensures that individual modules behave correctly.
• Declarative annotations (macros): They automatically generate documentation and facilitate consistent server/tool definitions.
Technologies, Frameworks, and Libraries
• Language/Platform: Swift, using features like macros and Swift Package Manager.
• JSON-RPC: For communication between clients and the server.
• HTTP+SSE: For asynchronous data handling and server-sent events.
• OpenAPI: To generate API specifications for integration (with AI plugins, etc.).
• Logging: Via custom logging handlers and the integrated OS logging facilities.