metowolf/vCards: A Chinese Yellow Pages Contact Pack for iOS and macOS

What metowolf/vCards actually puts on your phone

Chinese carriers deliver many business calls and service SMS with a bare number. The handset has nothing to match it against, so the screen shows eleven digits. metowolf/vCards is a curated contact set that fills that gap: each entry pairs an organisation with a name and a logo, so the incoming call screen and the Messages list can render something readable instead of a number. The README frames the goal as importing common contact avatars and improving the iOS call and message interface.

The audience is narrow and clear. It is for people in mainland China, or people who receive calls from Chinese organisations, on iOS or macOS. Android appears in the repository description, but every setup path in the README is an Apple one: a configuration profile installed through Settings, a CardDAV account, or a vcf import into iCloud. The repository is a data set with a build pipeline, not a library you import. If you were looking for a package that resolves a phone number to a company name at runtime, this is the wrong shape of project.

The project also states its own boundary. Because 106 SMS sender number ranges differ between regions and carriers, the maintainers do not include numbers beginning with 106. The README suggests using the project as a base template and adding the numbers you personally need after import.

How the data pipeline and the CardDAV server fit together

The repository separates source data from generated output. Source entries live under /data/类别/, one directory per category, each holding a yaml file and a png icon. Contributors add those files, run the checks, and open a pull request. The build then turns the whole tree into contact files.

package.json shows the two build targets. bun run build runs src/build.ts build, and bun run radicale runs the same script with a radicale argument. The Radicale target is the interesting one: the Dockerfile installs git in the builder stage specifically so the task can read the commit time of the yaml and png files and use it as a revision marker. That is how the generated collection gets a REV value that lets a CardDAV client decide whether its local copy is stale.

The runtime image is Alpine with Radicale installed from the package manager, configured entirely through generated files. Storage is multifilesystem under /app/vcards, authentication type is none, the web interface is disabled, and the rights file grants read-only access to any user matching .+ at the root and principal levels. Two collections are copied in from the builder: the iOS set at /app/vcards/collection-root/cn/ and a macOS set at /app/vcards/collection-root/cnmacos/. The server listens on 0.0.0.0:5232 and [::]:5232, and the container command is radicale. Read that configuration carefully before exposing the port: auth type none means anyone who can reach 5232 can read the address book.

Installing the profile or subscribing to the CardDAV account

The README lists three routes. The recommended one is the configuration profile. Scan the QR code on the project page with the system camera to download vcards.mobileconfig, then open Settings, tap the downloaded profile entry, and tap Install in the top right, following the on-screen prompts. The profile points the device at the hosted CardDAV service, so updates arrive without you doing anything else.

If you prefer to keep the address book as a separate account rather than a profile, subscribe manually. The README gives these values: server vcards.metowolf.com, username cn, and password cn or any value. On iOS the path is Settings, Contacts, Accounts, Add Account, Other, Add CardDAV Account. On Mac it is Contacts, Settings, Accounts, Other Contacts Account. The README notes that the default iOS fetch setting is Automatic, and that under Automatic the device only pulls new data when it is connected to power and WLAN, so a fresh import may take a while to appear. That is a device behaviour, not a project bug, but it is the first thing to check if the contacts look empty.

For a fully local copy, download archive.zip from the Releases page, unzip it, and import the vcf files into iCloud, ideally into a dedicated group so the yellow pages can be hidden or removed in one action. The README links Apple's own instructions for creating groups and importing contacts on macOS, iOS and iCloud.

To run the server yourself, the Dockerfile builds the collections and serves them:

FROM oven/bun:1.4.2-alpine AS builder
WORKDIR /app
COPY . .
RUN bun install --frozen-lockfile && bun run radicale

FROM alpine:edge
EXPOSE 5232
CMD ["radicale"]

The README points to issue 208 for a self-hosting walkthrough. Nothing in the repository documents the hosted service's uptime, retention or privacy policy, so treat the public server as a convenience and the container as the option you control.

Icon rules and the 106 exclusion are the real limits

The contribution rules are stricter than they first look. Icons must be PNG, never SVG, on a 200 by 200 or 512 by 512 canvas, with the logo centred at 140 by 140 for round marks, 120 by 120 for square ones, and 160 by 80 for rectangular ones, compressed under 20 kB or 50 kB depending on canvas size. The README says to redraw SVG sources in Inkscape. Those constraints exist because the generated files are meant to survive a round trip through Apple's contact stack, but they also mean a maintainer can reasonably reject a submission over file size.

The 106 decision is the limitation that will bite most users. Chinese service SMS often arrives from a 106 number, and those are exactly the senders people most want labelled. The maintainers exclude them because the ranges vary by region and carrier, so a single national list would be wrong for many users. The README's answer is to import the project as a template and add your own numbers afterwards. That is honest, but it means the out-of-box experience for SMS verification codes and bank notifications is incomplete.

There is a second, quieter limit: this is a read-only yellow pages list. Nothing here merges with or deduplicates against your existing personal contacts. If a business is already in your address book under a different name, you now have two entries for it, which is precisely why the README recommends importing into a separate group.

How it differs from a phone-number lookup API

The obvious alternative is calling a number-identification service or a query API, which is what this project's own acknowledgements list: 114 百事通, 百度手机卫士's yellow page, and the 中国可信号码数据中心. Those services resolve a number at query time and can cover far more numbers than any static list, including newly issued ranges. The trade-off is direction of data flow. An API needs a network round trip, usually an app or an SDK to consume it, and it learns which numbers you are asking about. metowolf/vCards inverts that: the whole data set is copied to your device, lookups are local, and nothing leaves the handset after the initial sync.

That inversion explains the project's shape. It cannot match a number the list has never seen, and it cannot be updated the moment a company changes its name, only when a release ships. In exchange it works offline, inside the stock Phone and Messages apps, with no third-party app installed and no per-query cost. If you are building a product that needs caller identification at scale, a lookup API is the right primitive and this repository is not. If you are an individual who wants the stock dialer to show logos, the static list is the better fit.

Maintenance, releases and what the licence line says

The repository is not archived, and the last push was on 2026-09-21, the same day as release 2026.09.21-151054. The two prior releases, 2026.09.16-122612 and 2026.09.16-121907, landed on 2026-09-16, so the release cadence is frequent and version numbers are timestamps. Upgrading is therefore not a migration exercise: a CardDAV subscriber receives new data on the next sync, and a manual importer downloads a new archive.zip. There is no schema you have to migrate and no API that can break under you.

The cost sits on the contribution side. Adding an entry means a yaml file and a png under /data/类别/, then bun install, bun test for format checks, and a pull request. Tooling is pinned to bun 1.4.2 via packageManager, with engines requiring bun 1.4.0 or newer, and devDependencies include vcards-js, zod, pinyin-pro and TypeScript. Anyone maintaining a fork needs Bun installed and needs to keep the icon rules in mind.

On licensing, package.json declares MIT. The repository's top-level entries do not include a LICENSE file, and the README carries no licence section, so the declaration in package.json is the only statement available here. MIT is permissive, but the contact data and logos are third-party material gathered from the acknowledged sources. Whether redistributing those marks is acceptable in your jurisdiction is a question for your own counsel, not something this repository answers.

Editorial conclusion

Adopt metowolf/vCards if you want Chinese business names and logos to appear on incoming calls and messages on iOS or macOS and you are comfortable pointing a CardDAV account at vcards.metowolf.com, or running the Radicale image yourself. Do not adopt it if you need 106-prefixed SMS sender numbers, if your contacts must never leave your own infrastructure and you will not run the Dockerfile, or if you expect a library to call from code rather than a contact list to subscribe to. Verify first that your device is set to fetch new data on a schedule rather than only when charging on WLAN, and confirm the licence terms yourself: package.json declares MIT while the repository's top level carries no LICENSE file.

Frequently asked questions

Official sources

1. Issues
2. metowolf/vCards on GitHub
3. README
4. Releases