So when Cursor added MCP support – I was very excited. Instead of opening a Cursor window pointed at my bookmarks folder, I could build my own MCP server that indexed the bookmarks, and provide tools so that local bookmark search was available in all of my Cursor windows. I’ve successfully nerd-sniped myself into the MCP abyss for the foreseeable weekends.

Just gimme the code

Ok ok! Here’s my barebones MCP server in Swift that uses loopwork-ai/mcp-swift-sdk.

MCP in Swift

It’s not hard to find example MCP servers, it’s a bit harder to find MCP servers that work, and it’s very hard to find MCP servers written in Swift. I found two SDKs on Github that look promising, the first one I found is https://github.com/gsabran/mcp-swift-sdk, and the second is the similarly-named-but-different https://github.com/loopwork-ai/mcp-swift-sdk. Both are under active development, so by the time you read this the ‘best’ one of these two may change, or even have more libraries available on Github.

I started with gsabran‘s repo, and now I’m happier with loopwork-ai‘s repository. Maybe it’s because their repo is better, or maybe it’s because I understand things better now, who could say?

A big benefit of loopwork-ai‘s repo – it also contains a fully functional Mac app that attaches to the MCP server. So how does that work? what is an “MCP server” anyway?

MCP Architecture

Servers need to accept input requests and provide responses somehow. MCP is based on JSON-RPC v2.0, which makes the format of its input and output very clear. The MCP specification gives clear definitions for the various MCP specific messages.

When I hear the word “server,” I think of HTTP servers like Apache or Nginx running on port 80, or 443 for SSL, or 8080, or etc etc. However, the recommended and most common MCP server runs on stdio input and output streams. Huh?! It’s not how I typically think of a server. The specification does also define SSE – an MCP protocol on HTTP, though the spec says that that “Clients SHOULD support stdio whenever possible.”

I suspect this is motivated as much by security and authentication as it is by simplicity. If clients spawn the MCP process locally and communication through stdin and stdout, there’s a much smaller surface area for bad actors. If I instead run a small HTTP server locally on my Mac – that’s a much bigger potential hole in my security, both by accidentally exposing the MCP outside my device, as well as any security holes in the HTTP server I use.

At the end of the day, clients and servers are just trading JSON back and forth, so custom transports are entirely possible.

Specification Summary

Very simply, MCP servers provide prompts, resources, and tools. Clients connect to servers and discover what’s provided, and then surface those to the LLM and/or user as they see fit. The easiest way to think of an MCP server is a bag of functions – servers list the functions (tools) to the client, and the client calls those functions with some input.

Importantly, the MCP server does not see the context of the chat with the LLM – it only gets the parameters sent for a specific tool invocation. Clients are encouraged to verify with the user before calling a tool, so this means minimal context is sent to an MCP server, and all tools calls ideally go through human approval to mitigate the risk of leaking sensitive data.

Authentication

The MCP specification does not specify authentication, just like HTTP. Any authorization that you want to enforce for a client/server session you must handle yourself. For stdio servers, you can track state in your running server without issue, as its only ever connected to a single client. Since it’s using input/output streams, there’s generally no authentication for stdio connections which is much easier.

For SSE servers, you’ll need to handle authentication yourself, potentially with HTTP headers or something similar, potentially with a Bearer token header using OAuth, etc.

SSE Transport

A quick primer on the SSE protocol – while the stdio transport allows only a single client to connect to the single server, an SSE enabled MCP server can potentially serve multiple clients. It does this by exposing a single GET endpoint. When a new connection is made, the server immediately sends a POST endpoint for that client to send requests to. Since all clients are using the same GET request, the server is responsible for separating out which requests belong to which GET connection. One strategy would be to use a separate POST endpoint per connection.

This discussion in the modelcontextprotocol/specification Github is a deep dive on the tradeoffs of stateful and stateless servers and possible future changes to allow for traditional stateless HTTP architecture, or using connections like WebSockets instead of long-lived GET.

Debugging Tools

The MCP documentation lists an number of helpful debugging tools.

1. MCP Inspector: This is a small server that runs on your machine and can launch and connect to MCP servers. I strongly suggest getting your tool working with this inspector before moving on to Claude or Cursor integration.
2. Claude Desktop Developer Tools: Claude itself can be helpful for debugging your server as you develop. Add your server into claude_desktop_config.json and restart Claude. Then tail logs at
tail -f /Users/{username}/Library/Logs/Claude/mcp-server-{yourservername}.log
3. Server logs: I use Swift Logging for my server, as does the loopwork-ai/mcp-swift-sdk, which makes seeing logs in Xcode’s console very simple. The MCP specification uses stdin and stdout, so anything you send to stderr will generally show up in the client’s logs somewhere.
4. Xcode: After launching the client (which then spawns the server), I connect the debugger to it and can then use all of the normal tools in Xcode: breakpoints, logging, etc. I also use the built executables path (Xcode → Product → Show Build Folder) as the server in Claude/Cursor so that I can rebuild in Xcode → relaunch Claude and see the new version.

MCP Tools Walkthrough

When the server initializes, it tells the connecting client what capabilities it has, and for the tool capability there’s an option to notify when those tools change:

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

Once the client hears the capabilities, it requests the tool list from the server. From what I’ve seen, clients are not very well behaved, and will ask for tools, prompts, and resources regardless of the capabilities described by the server. The specification for requesting the tool list is a request from the client:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

The server would reply with its list of tools according to the specification. This example shows a helloPerson tool that accepts a name:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "helloPerson",
        "description": "Returns a friendly greeting message",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": [
              "type": "string",
              "description": "Name of the person to say hello to",
            ]
          },
          "required": ["name"]
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

At this point, the client has all of the information it needs to start calling the function:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "helloPerson",
    "arguments": {
      "name": "Adam"
    }
  }
}

And the server can send its response to stdout. Note that the response contains the id of the request that it is responding to. This allows multiple requests to be in-flight, and the client can match responses with the corresponding request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Hello, Adam!"
      }
    ],
    "isError": false
  }
}

Gotchas

stdio Format

Note that all of the JSON examples in this post and in the documentation are formatted for humans, but aren’t verbatim allowed responses. All server responses must not contain any newlines, and must be separated by a single newline.

stdin is reserved for input RPC requests, and stdout is reserved for RPC responses. Nothing else can be sent on those streams – any other logging must be sent on stderr. Those print() statements you use when debugging? Gotta find another way! I’ve been using Swift Logging instead.

Tools Changed Notification

The MCP specification allows for servers to notify clients when the list of tools updates. When the client hears this notification, it should send a new list/tools request to get the new list of available tools.

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

Once I had a barebones MCP server working with Claude, I spent quite a bit of time trying to diagnose why it wasn’t responding to my updated tools notification. Welp, it turns out Claude doesn’t support updating tools yet, and it appears Cursor doesn’t either.

Making it more confusing, the modelcontextprotocol/inspector does not show tools/list_changed notifications either. After some digging, I found that only a few notification types will appear in the UI. So when you work on your MCP and can’t seem to get this notification to work – don’t worry, it’s [possibly] not you. It seems we’re so early in MCP ecosystem that tool list updates just aren’t widely support yet. The workaround? Restart your client 😬.

List Tools

Tools are the meat and potatoes of MCP servers. The client requests available tools from the server with the tools/list method request, which accepts a single optional cursor parameter. When implementing Codable in Swift, be careful when decoding optional parameters. When I began using loopwork-ai‘s repository, there was a subtle decoding issue, and to show the issue, take a look at possible request JSON’s from a client:

// Specification for the List Tools requests to the server
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

Note that the cursor parameter is optional, so which of the following is a valid request? All of them? Probably? The right answer is “whatever the client that you need to integrate with sends you…”

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": null
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": null
}

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

When I started working with loopwork-ai‘s sdk, the decoding was a bit too strict and failed to decode this message correctly. I’ve submitted a PR for the fix to make it more lenient, and have a branch on my mcp-swift-sdk fork that I use for my development with a few other niceties.

Follow Along

I’m working on a barebones template for building MCP servers in Swift on the Mac. I’ve started a repository at adamwulf/mcp-template which uses loopwork-ai‘s SDK. My goal is to provide a simple EasyMCP server that manages the MCP server lifecyle, provides easy tool registration, and provides an App Store safe way to ship an MCP command line tool that connects to a Mac app for its functionality.

So far, I have a simple wrapper around the loopwork-ai SDK that handles the MCP stdio transport setup and provides a simple tool registration method:

        // Build the MCP server with logging
        let logger = Logger(label: "com.milestonemade.easymcp")
        let mcp = EasyMCP(logger: logger)

        // Register a simple tool that accepts a single parameter.
        // The name, description, and inputSchema will be sent to
        // the client so that the LLM knows what the tool does.
        try await mcp.register(tool: Tool(
            name: "helloPerson",
            description: "Returns a friendly greeting message",
            inputSchema: [
                "type": "object",
                "properties": [
                    "name": [
                        "type": "string",
                        "description": "Name of the person to say hello to",
                    ]
                ],
                "required": ["name"]
            ]
        )) { input in
            // It's an async closure, so you can await whatever you need to for long running tasks
            await someOtherAsyncStuffIfYouWant()
            // Return your result and flag if it is/not an error
            return Result(content: [.text(hello(input["name"]?.stringValue ?? "world"))], isError: false)
        }

        try await mcp.start()
        try await mcp.waitUntilComplete()

It’s Alive!

After two weekends of fiddling, I have the mcpexample command line server in mcp-template working in Claude and Cursor! 🎉

Since going solo with Muse in late 2023, I’ve wanted to get the transcripts of all of these episodes online, but I knew that writing transcripts manually was an insurmountable task. Whisper had recently been released, and I was hopeful for AI transcription to help solve this. While Whisper’s transcription accuracy is fantastic, it does not do speaker diarisation – it doesn’t separate the transcript per speaker.

Recently I found WavoAI, an online transcription service with a generous free tier. Their transcripts are good quality, and most importantly, they do provide speaker diarisation.

Below is the process I followed to add transcripts to every podcast episode page on the Muse website, and take a look at Metamuse Episode 1 page to see the result.

Step 1: Transcribe with WavoAI

The WavoAI website is wonderfully simple. There’s an upload button, and a list of all your transcripts – that’s it. They do have a monthly cap of total transcript duration, so over a couple of months I would upload each episode until I had all 84 episodes transcribed.

Interestingly, the export for the transcript is a *.docx file of all things. So I clicked through and downloaded each docx transcript file, and made sure to name it the same as the podcast episode mp3 file so it was easy to reference.

Step 2: Convert to Markdown

Next, I used a short script to automatically translate those docx files into md Markdown files:

for file in docx/*.docx; do
    filename=$(basename "$file" .docx)
    pandoc "$file" -t markdown -o "md/${filename}.md"
    # Use the following sed command for macOS
    sed -i '' -e 's/\\$//' -e "s/\\\\'/'/g" "md/${filename}.md"
done

Step 3: Use Cursor to update Hugo site

The Muse website is built with the Hugo framework. Each podcast episode lives as a Markdown file in a podcast directory. I’ve been using Cursor for many menial coding tasks, and I wanted to see how it would do integrating the podcast transcript files into the podcast episode files. I admittedly don’t know too much about Hugo, so I very much threw this problem over the wall to the AI to see how it would do. I have Cursor setup to use Claude-3.5-Sonnet.

Here’s my first prompt to Cursor:

separate from this repo, I also have a folder full of transcripts for all of the podcast episodes. This site uses Hugo to be built. Is there a way to auto-process the transcript files using Hugo to include them as a sub-section of the respective podcast episode page? or would i need to edit each podcast episode page individually to manually copy/paste the entire transcript in?

That’s all it took and I was off to the races! It suggested adding a transcripts subfolder to the podcast folder. Since all the filenames already matched, it built a new partial for the transcript section:

{{ $transcriptPath := printf "podcast/transcripts/%s.md" .File.BaseFileName }}
{{ with site.GetPage $transcriptPath }}
<div class="transcript">
  <h3>Transcript</h3>
  {{ $content := .Content }}
  {{ $pattern := `(\d{2}):(\d{2}):(\d{2}) - ` }}
  {{ $replacement := `<a href="#t=$1$2$3" class="timestamp" data-time="$1:$2:$3">$1:$2:$3</a> - ` }}
  {{ $processed := replaceRE $pattern $replacement $content }}
  {{ $processed | safeHTML }}
</div>
{{ end }} 

And added a single line to the single.html podcast episode page: {{ partial "podcast-transcript" . }}

Barely 30s after opening cursor, I had all of the episode transcripts imported into the website and showing up correctly! Not bad!

Step 4: Clean up and deploy

At this point, it was good enough to ship, but I spent a bit more time to keep it extra tidy. The WavoAI did a great job with the transcript, but obviously wouldn’t know my last name is spelled with a u instead of an o. I fixed up other egregious misspellings – the word “Muse” was often transcribed as “MU” or “Mu’s”, etc.

The transcription file also includes 00:00:00 styled timestamps each time the speaker changes. I asked Cursor if it it could write a script to use those timestamps to jump the inline podcast player to that timestamp. A bit of back and forth, and now the podcast episode page has links for each timestamp which update the hash of the page URL. This means anyone can jump straight to a quote by clicking in the transcript, and can also share the URL with anyone so that they can jump straight to the quote too! Here’s a great moment in Molly Mielke’s episode where she’s talking about the importance of interoperability in tools for thought.

Wrap up

This has been something I’ve wanted to do for the Metamuse podcast library since day 1 of going solo. It’s been a long wait to find the right tooling to be able to do this without spending weeks of my own time manually annotating speakers. It just wouldn’t be feasible for me to do without the help of both WavoAI and Cursor. Even the Hugo work, I could’ve eventually gotten there on my own, but it would’ve taken me hours instead of minutes to learn the necessary Hugo-isms to pull it all together.

I’m very thankful to have this project ticked off my todo list! It makes the podcast episode pages accessible to the hearing impaired, and I’m hopeful it’ll increase SEO traffic to Muse too, and also make it just a bit easier to share loved moments of your favorite episodes.

Invalidating URLSession

One tip it gives at the end is to invalidate the URLSession on app launch so that you can start from a clean slate:

Starting from scratch

First of all, it’s good to start with a clean slate. We can do this by executing the following piece of code on launch to invalidate our URLSession and its tasks:

#if DEBUG
    if debuggingBackgroundTasks {
        /// Cancel any running tasks and invalidate the session.
        URLSession.shared.invalidateAndCancel()
    }
#endif

I’m not sure this is a good idea, or at the very least requires relaunching your app after invalidating all tasks. The issue is that this is invalidating URLSession.shared, not the background URLSession we created to handle background uploads.

The Apple Documentation for URLSession.invalidateAndCancel() states:

Calling this method on the session returned by the shared method has no effect.

If we invalidate our background URLSession instead, we run into a new problem: Only a single URLSession for a given configuration identifier will ever be created. This means that if we invalidate and then re-create our background URLSession, we actually get back the same URLSession that we just invalidated!

        backgroundSession.invalidateAndCancel()
        let config = URLSessionConfiguration.background(withIdentifier: Self.backgroundSessionIdentifier)
        config.sessionSendsLaunchEvents = true
        config.isDiscretionary = false
        backgroundSession = URLSession(configuration: config)  // <--- This returns the same `backgroundSession` that we just invalidated!

The Apple Documentation for URLSession.invalidateAndCancel() states:

Once invalidated, references to the delegate and callback objects are broken. After invalidation, session objects cannot be reused.

This does mention we shouldn’t use the same session, but doesn’t mention that the exact same URLSession will be returned from the init(configuration:), which I found surprising.

Instead of invalidating the session to clear out old upload tasks, simply iterate through the tasks and cancel them individually:

let tasks = await yourBackgroundURLSession.allTasks
for task in tasks {
    task.cancel()
}

Forcing App Background

One other note, in the article Antoine recommends calling exit(0) from applicationDidEnterBackground(_:):

Make your app suspend sooner

Waiting for your app to suspend is a waste of time. By using exit(0) we can force our app to suspend:

func applicationDidEnterBackground(_ application: UIApplication) {
    #if DEBUG
        if debuggingBackgroundTasks {
            /// Exit to make our app suspend directly.
            exit(0)
        }
    #endif
}

However, the Apple documentation for that method notes that applicationDidEnterBackground(_:) will not be called for applications using scenes:

If you’re using scenes (see Scenes), UIKit will not call this method. Use sceneDidEnterBackground(_:) instead to perform any final tasks. UIKit posts a didEnterBackgroundNotification regardless of whether your app uses scenes.

Oops! I’d completely forgotten about this, and I was left wondering why my app delegate method wasn’t call. The fix is easy, I switched to use
sceneDidEnterBackground(_ scene: UIScene) in your scene delegate.

Conclusion

If you want to cancel all background tasks and start from scratch, call cancel() on your background URLSession.allTasks. Otherwise, if you invalidate your background session, the background session will not be able to be re-used in the same app session that it was invalidated in. To start new background tasks, you would need to relaunch the app and not invalidateAndCancel() a second time.

Unlike just a few years ago, we now live in a world with high quality AI translations! As good as these AIs are, they’re still not human, and they’ll still miss important context about how these translations are used and viewed in the app, so having a human in the loop is still incredibly important. However – they do reduce the human-time cost of adding and maintaining multiple languages.

I’ve recently shipped a French translation for Muse, and I have German and Spanish cooking and expect those to release in the next week or two. Thats three languages in less than a month of time, and better yet, less than a few days of my coding time. Here’s how I’m able to translate Muse with minimal coder time and minimal volunteer time.

Step 1: Prep the codebase for localization

SwiftUI provides much of localization for free with its Text node, however all of Muse’s codebase is UIKit. Following Apple’s localization documentation, the first step is to add a Localizable.xcstrings String Catalog file into the project.

When you build your project, Xcode will automatically update this strings catalog with all of the localized strings in your codebase. As long as you use Text from SwiftUI or NSLocalizedString, the string keys will appear automatically.

Next, add the new language into the project’s settings:

Now, you’ll see the new language appear in the string catalog that you’ve just added. Xcode shows a fancy editor for the strings file, but what happens if we open as source code instead? the Localizable.xcstrings file is really just a JSON file! And what tool is good with JSON? LLMs.

Step 2: Cursor and Claude

Now that we have our application’s translations as a single JSON file, let’s use AI to automatically translate our app. Open the root folder of your project in Cursor, and open to the Localizable.xcstrings file.

Next, use Command+L to open the Chat interface, and ask to add a new translation to the file. Here’s the prompt I used to translate Muse into German:

Here are the key guidelines for German localization of Muse:

Canonical translation:
- English is the original translation and should be the primary reference

Brand & Common App-Specific Terms:
- "Muse" (never translate)
- "Board(s)" (keep English term)
- "Card(s)" (keep English term)
- "Workspace(s)" (keep English term)
- "Backstage Pass" (keep English)
- File types like "PDF", "URL"
- Technical terms like "debug", "database", "sync", "cache" (only if commonly kept in English when used in German)

Formality & Tone:
- Use informal "du" form rather than formal "Sie"
- Friendly but professional tone
- Direct address to user
- Keep technical explanations simple and clear

Gender & Inclusivity:
- Use gender-inclusive forms with -In suffix where applicable (e.g., "BenutzerIn", "MitarbeiterIn")
- When possible, use gender-neutral terms

Capitalization & Grammar:
- Capitalize nouns per German rules
- Compound words with English terms maintain English spelling (e.g., "Workspace-Karten")
- Maintain English terms in their original form when part of compound words
- Use German quotation marks („") for quotes

UI Elements:
- Button text should be concise
- Menu items use infinitive form
- Error messages should be clear and direct
- Maintain consistent terminology throughout

Special Considerations:
- Preserve emoji and formatting tags (e.g., <highlight>, <small>)
- Maintain placeholder syntax (e.g., %@, %d)
- Keep technical command references (e.g., ⌘, ⇧) unchanged
- Preserve HTML tags and links exactly as in source

Length:
- German translations tend to be longer than English
- Keep UI elements as concise as possible while maintaining clarity
- Consider space constraints in buttons and menus


If you see a string that does not match the guidelines, please generate a replacement JSON that can be applied to the file to replace it with a corrected version. explain the change.

That’s quite a prompt! My goal is for the prompt to give the LLM enough context to know how to translate my app with the correct tone and localization decisions. Each language has its own nuance: gender, plurals, formality, etc. Explain to the LLM how you want your app to be translated for the given language.

For extremely long xcstrings files, I will select the range of keys that I want translated, use Command+Shift+L to add that snippet to the chat context, and ask to translate only that portion. Then I’ll copy/paste into Cursor to replace the selection. Why not use Apply? For extremely long files, Apply can both take too long and use too many tokens for the model’s limited output size.

For all of Muse’s translations, I used Claude Sonnet 3.5.

After updating the xcstrings file, save it in Cursor and open it in Xcode to verify that the JSON is still in the valid format. Save again in Xcode, as Xcode will format it with alphabetical language keys, whitespace, etc. Commit to your repo and off you go!

For Muse, a codebase with ~700 localized keys, it takes me ~2 hours to translate all of them with AI. I could probably optimize my flow to take less than an hour, but that’s only 10-15 hours total for 5 languages!

Step 3: Upload to POEditor

At this point, we have a fairly accurate translation from an AI – but we don’t know how accurate it actually is. In my first pass at German, I didn’t know about its gender or formality, so after a volunteer looked it over and gave their first feedback, I re-ran the AI with a better prompt to get a more accurate translation. Now the volunteers have fewer strings to manually edit.

But how do we get these strings to our volunteers or translation team? I use POEditor to coordinate with volunteers on Muse’s translations.

To get the translations from Xcode into POEditor, use the Export Localizations item in the Product menu.

This will export a folder at the location you choose with 1 bundle file per language that your app supports. POEditor doesn’t handle xcloc bundle files, but it does handle xliff files. To get to your xliff file, right click the bundle and choose Show Package Contents, and find the xliff file in the Localized Contents subfolder.

Upload this xliff file to the same language in POEditor. Note: There’s two different places to upload in POEditor, there’s an import link at the project level, and another import link in the specific language – you want the import link in the language.

Choose to overwrite any existing translations in POEditor, save and upload, and enjoy all of your strings in POEditor!

Step 4: Review translations

Next, add your contributors to POEditor for the language. These are the people who’ll be able to view and make changes to all of the translations.

Once your volunteers or translation team has validated and corrected your translation, it’s time to get their work back into Xcode.

Step 5: Export from POEditor

In POEditor, navigate into the language and choose its Export link. In the export menu, choose the xliff file format, and export to overwrite the exact same file you uploaded to POEditor.

Then, from Xcode, choose Import Localizations from the Product menu and select the Localizations folder that it had exported before. Since you’ve just overwritten the language’s xliff file inside that same folder, Xcode will now read in and use all of those new translations.

Congratulations! You’ve just translated your app into another language using AI, POEditor, and a small focused dose of human help.

Wrap up

This is a long post, but the core idea is simple:

• Use xcstring files in Xcode to get auto-updated translation keys, including localized plurals
• Use Cursor and AI to get a draft translation for your new language
• Upload to POEditor and validate with human helpers
• Download and import back into Xcode, and enjoy!

Muse is available today in English and French, and soon in German and Spanish as well.

I was recently told about periphery, a command line tool to find unused code in Swift projects. What’s a day off work for but for having fun playing with new tools? First up, install:

$ brew install periphery

God bless brew, amirite.

Next up, the README suggests we run its setup for a handheld first run:

$ periphery scan --setup
Welcome to Periphery!
This guided setup will help you select the appropriate configuration for your project.

* Inspecting project...

Select build targets to analyze:
? Delimit choices with a single space, e.g: 1 2 3, or 'all' to select all options
1 AppKitBridge
2 Muse
3 Muse Integration Tests
4 Muse Tests
5 MuseShare
6 SparklePlugin

...

Super easy to get setup, what a pleasure! I selected the targets I needed, then the schemes. Next it asks about Objective-C code, and I selected Yes to assume obj-c code is in use. Muse has only a little, but some interactions with UIKit or AppKit still reach into Objective-C.

Assume Objective-C accessible declarations are in use?
? Declarations exposed to the Objective-C runtime explicitly with @objc, or implicitly by inheriting NSObject will be assumed to be in use. Choose 'No' if your project is pure Swift.
(Y)es/(N)o > y

Next, it asked about assuming all public declarations are in use – which would be very useful when building a framework or library, for for an app like Muse I answered No.

Assume all 'public' declarations are in use?
? You should choose 'Yes' here if your public interfaces are not used by any selected build target, as may be the case for a framework/library project.
(Y)es/(N)o > n

Last, I saved the configuration to .periphery.yml and let the first scan run. Luckily, it found the codebase squeaky clean! 😉

I use Sourcery to auto-generate some connector files between the custom Muse sync codebase and Muse-the-application codebase. There’s also a fair bit of old CoreData code that’s still in the codebase so that very old Muse libraries can be migrated to the current sync world. For each of these, I don’t need them included in periphery‘s output.

To remove them, I used the --report-exclude command line option to remove a few paths that I don’t need in the report. I’m also not concerned with redundant public, so I included
--disable-redundant-public-analysis too. Last, I’m not worried about unused function parameters, so i used --retain-unused-protocol-func-params. I ran with --verbose which shows the .yml configuration changes I needed to make to always run with these excluded.

Last, I setup an Aggregate target in Xcode so that I can run periphery and see unused code in the Issue navigator. I updated the Build Settings to use iOS, added a User Defined setting for SUPPORTS_MACCATALYST=YES, and added a Run Script phase with the following:

export PATH="$PATH:/opt/homebrew/bin"

if which periphery >/dev/null; then
    periphery scan --config "${SRCROOT}/.periphery.yml"
else
    echo "warning: periphery not installed, install from https://github.com/peripheryapp/periphery"
fi

Now, when building the Periphery aggregate target within Xcode, I can see all of the unused code inline right inside Xcode.

Just a little bit of clean-up work to do! 😅

Thankfully, Figma came through! The strategy is to use Figma’s variables and modes. The basics flow is to:

1. Setup a variable for each piece of text that you want to translate, and set it’s initial value to the English translation
2. Update each text node in your Figma design to use that variable instead of static text
3. Setup a new mode for the variable for each new language, and then update each variable to include a translation for each language
4. Toggle the page’s default mode to set the language for all screenshots

Figma Variables and Modes

With nothing selected on the Figma page, click the button to open up the Local variables window. This is where you’ll configure each text snippet.

Once the variable window is open, add a variable for each piece of text that appears in your design. For Muse, one of my screenshots is below, and you can see I’ve translated its two header lines as a separate variable.

You can see that I’ve created separate variables for “Nested boards” and “A cozy space to think.” For simplicity, I set the Name and English value so the same text so that it’s easier for me to recognize the variables elsewhere in Figma.

After setting up the English version, click the + button to add a new variable mode. Use this new variable mode for your second language’s text.

Update Text Nodes to Use Variables

Now that you have your variables setup with all of your translations, it’s time to setup the text nodes in your designs to use them. To do that, select a text node and then click the Apply variable button.

That will open a dialog where you can choose the variable that matches your text.

Now your text node has its text pulled from that variable.

Toggle Language

That’s all there is to setup multiple languages in your Figma design. To switch between your languages, deselect everything on your page, and then click the Apply variable mode button to switch between your language modes.

Now it’s easy for me to switch between and export both English and French screenshots for the App Store!

After moving to Zoho, I found that they also had fantastic customer support! I can file a ticket and get a human response who actually helps to resolve my question. It’s been such a breath of fresh air.

Recently, I started co-teaching a product management class at Rice. As part of that, I re-activated my rice.edu email address. Rice uses Google for their email handling, so I added that email into my Zoho account as an additional IMAP email connection.

This lets me check my rice.edu email from the same zoho web app that I use for my personal email, while still keeping the two email inboxes and emails separate. It’s been wonderful, and I do this for a few other email accounts as well.

What was odd – emails in my Rice account were appearing twice in Zoho (!) while my other IMAP added accounts were behaving just fine. I contacted Zoho support, who suggested this was an issue on the Google side, and recommended I find the message identifiers to confirm if these were “different” emails or not – this could help diagnose the issue.

I found the exact same message id, and exact same .eml contents for the duplicate emails. I noticed while doing this – one email was in Inbox and the other was in Important.

I remembered that Gmail uses labels instead of folders, and this can cause strange side effects for IMAP clients. I talked out my problem and evidence so far with Claude, which suggested I change Gmail’s IMAP settings. I found the toggle in Gmail settings → full settings → labels → IMAP access and turned it off for the Important label.

Next sync – tada! Zoho removed all the duplicates from that Important flag and is correctly showing only a single email in my Unread filter.

Wins: Zoho support for helping me find clues, AI for helping me diagnose the issue with those clues, Gmail for having the correct settings to undo their non-standard IMAP implementation, and Zoho for a stellar email product!

Think On Your Feet:

Custom printed socks with thought bubble emojis all over them. So you can ‘think on your feet.’

After filtering through many search results for “custom socks,” most of which were aimed at youth sports leagues, I finally found that none other than Shutterfly offers the option. A little work creating a ‘photograph’ of the Thought Bubble emoji and one Shutterfly template later, voila!

Get a pair for the deep thinker in your life!

To record these demos, I’m using Screenflow, a wonderfully simple screen recorder and video editor.

For reasons beyond my understanding, I found that using Screenflow to record the simulator gave higher quality video than using the Simulator’s built in Record Screen functionality. Similarly, it’s better quality than recording the screen directly on the iPad as well.

I’ll have to eventually solve the quality problem, as it’s not currently possible to perform two simultaneous gestures on the simulator. For those future demo videos that do use simultaneous gestures, I’ll need to record directly on the iPad, but until then the simulator works great.

However! By default, the simulator shows two dots for the touch points of a two finger gesture. I’m using HandShadows precisely to not show touch points, so I needed a way to either edit these points out or turn them off entirely.

Luckily, there is are a few hidden user defaults for the Simulator to toggle touch points. I found the first one through Aman Mittal’s blog post about turning on the touch point for single touch gestures. To do that, you can do the following:

defaults write com.apple.iphonesimulator ShowSingleTouches 1

This turns touch points on for a single finger, which is very useful if you’re using the simulator’s touch indicators for videos, but in my case I wanted to turn them all off.

I asked colleagues if they knew any other hidden simulator defaults, and one suggested to run strings on the simulator executable and see what came up. So that’s just what I did:

strings /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/Contents/MacOS/Simulator | grep Show

And what appears? Hope!

...
ShowSingleTouches
ShowPinches
ShowPinchPivotPoint
...

And sure enough, toggling the ShowPinches removes the two finger gesture touch points from the simulator!

defaults write com.apple.iphonesimulator ShowPinches 0

And an interesting 3rd option too: ShowPinchPivotPoint. Let’s see what the simulator looks like with all of these turned on:

defaults write com.apple.iphonesimulator ShowSingleTouches 1
defaults write com.apple.iphonesimulator ShowPinches 1
defaults write com.apple.iphonesimulator ShowPinchPivotPoint 1

When toggling these settings from the command line, it seems that the Simulator app needs to be completely quit and restarted before they take effect.

These settings are a very helpful new tool in the toolbox!

Since Sparkle is an AppKit framework, and our app is a UIKit Catalyst app, I needed some help joining these two worlds together, and I found this fantastic step-by-step tutorial by Eskil Sviggum: https://betterprogramming.pub/configuring-app-updates-for-mac-catalyst-apps-with-sparkle-beef7a90a515.

After embedding the SparklePlugin.bundle into the app, tying together the UIKit and AppKit so that it could attempt to check for updates at launch, I immediately got the following error when launching the app in Debug mode from Xcode:

2023-06-15 17:54:13.028099-0500 Muse[55654:1170102] [loading] Error loading /Users/adamwulf/Library/Developer/Xcode/DerivedData/Muse-cfdmmqzcfayzhrabrpyekznonhrk/Build/Products/Debug-maccatalyst/Muse.app/Contents/PlugIns/SparklePlugin.bundle/Contents/MacOS/SparklePlugin (194):  dlopen(/Users/adamwulf/Library/Developer/Xcode/DerivedData/Muse-cfdmmqzcfayzhrabrpyekznonhrk/Build/Products/Debug-maccatalyst/Muse.app/Contents/PlugIns/SparklePlugin.bundle/Contents/MacOS/SparklePlugin, 0x0109): Library not loaded: @rpath/Sparkle.framework/Versions/B/Sparkle
  Referenced from: <3B2706F0-30A4-3FF2-84B3-191F25C6A606> /Users/adamwulf/Library/Developer/Xcode/DerivedData/Muse-cfdmmqzcfayzhrabrpyekznonhrk/Build/Products/Debug-maccatalyst/Muse.app/Contents/PlugIns/SparklePlugin.bundle/Contents/MacOS/SparklePlugin
  Reason: tried: '/Users/adamwulf/Library/Developer/Xcode/DerivedData/Muse-cfdmmqzcfayzhrabrpyekznonhrk/Build/Products/Debug/Sparkle.framework/Versions/B/Sparkle' (file system sandbox blocked open()), 
...

The issue is that the embedded plugin bundle includes an embedded Sparkle.framework, and that inner framework isn’t being codesigned with the same identity, which means the sandboxed app is refusing to load it. I found this thread pointing to the framework’s documentation about codesigning, and the solution is to add an extra code signing step to the build phases.

I modified it slightly so that it pointed explicitly at the Sparkle.framework in the BUILT_PRODUCTS_DIR. Once I did that, I got the following build error:

Showing All Messages
Apple Development: ambiguous (matches "Apple Development: Adam Wulf (SomeTeam)" and "Apple Development: Adam Wulf (OtherTeam)" in /Users/adamwulf/Library/Keychains/login.keychain-db)

My Apple ID is part of multiple teams, so I have multiple developer profiles that were matching. The fix is to use EXPANDED_CODE_SIGN_IDENTITY_NAME instead of CODE_SIGN_IDENTITY.

PluginsPath="${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME%.*}.app/Contents/PlugIns/SparklePlugin.bundle/Contents/Frameworks"

echo "Codesign Sparkle"
echo $PluginsPath

codesign -f -s "$EXPANDED_CODE_SIGN_IDENTITY_NAME" -o runtime "${PluginsPath}/Sparkle.framework/Versions/B/XPCServices/Installer.xpc"
codesign -f -s "$EXPANDED_CODE_SIGN_IDENTITY_NAME" -o runtime --entitlements Entitlements/Downloader.entitlements "${PluginsPath}/Sparkle.framework/Versions/B/XPCServices/Downloader.xpc"

codesign -f -s "$EXPANDED_CODE_SIGN_IDENTITY_NAME" -o runtime "${PluginsPath}/Sparkle.framework/Versions/B/Autoupdate"
codesign -f -s "$EXPANDED_CODE_SIGN_IDENTITY_NAME" -o runtime "${PluginsPath}/Sparkle.framework/Versions/B/Updater.app"

codesign -f -s "$EXPANDED_CODE_SIGN_IDENTITY_NAME" -o runtime "${PluginsPath}/Sparkle.framework"

After that change to the signing build phase script, it could build + run + check for updates just fine!