feat: add Nix package for zhtw-mcp

[pan93412]

增加 Nix 套件，在有安裝 Nix 的情況下，可以使用 nix run sysprog21/zhtw-mcp 來執行 zhtw-mcp（而且不會影響到現有 $PATH 裡面的內容）：

$ claude mcp add zhtw-mcp -- nix run github:pan93412/zhtw-mcp/add-nix-package --
Added stdio MCP server zhtw-mcp with command: nix run github:pan93412/zhtw-mcp/add-nix-package -- to local config
File modified: /Users/yjpan/.claude.json [project: /Volumes/Dev/tmp/clawd-on-desk]

❯ /mcp
  Manage MCP servers
  9 servers

    Local MCPs (/Users/yjpan/.claude.json [project: /Volumes/Dev/tmp/clawd-on-desk])
  ❯ zhtw-mcp · ✔ connected · 1 tool

Note

AI Disclosure: buildRustPackage 的啟發式探索（包括 doCheck、OpenCC 等等的版本固定）均由 Codex 完成。Nix 更新教學和 README 也是由 Codex 更新，但人類有確認可以編譯。

---

Nix 套件的維護略顯複雜。它為了達到可復現編譯 (reproducible build)，要求把 Cargo.lock 以及 OpenCC 的 hash 定義上去。因此，如果 Cargo.lock 有更新，或者是想要更新 flake.nix 中 OpenCC 的修訂版本，就需要另外開一個 PR 來更新 Nix 上面的 Hash。

之後可以另外寫一個 GitHub Actions 來自動執行下面的任務（類似於 cc-statusline 的做法），在此之前應該是需要「如果壞了，再讓有興趣的人上去修 PR」的形式，而使用者則需要做好 Git 版本的鎖定（而不能盲目跟著主幹更新 Nix 套件）。

Nix 更新教學

1. Enter the Nix development shell

If the repository has flake.nix, run all project commands through
nix develop.

nix develop

For one-off commands, prefer:

nix develop -c <command>

2. Update package metadata

The package definition lives in flake.nix under:

overlays.default = final: prev: {
  zhtw-mcp = ...
};

When the Rust crate version changes, update both:

• Cargo.toml: package.version
• flake.nix: zhtw-mcp.version

Keep package metadata in sync with Cargo.toml, especially:

• description
• homepage
• license
• mainProgram

3. Refresh cargoHash

If Cargo.lock changes, the vendored Cargo dependency hash must be refreshed.

Temporarily replace the existing cargoHash in flake.nix with:

cargoHash = final.lib.fakeHash;

Then run:

nix develop -c nix build .#zhtw-mcp

The build should fail with a fixed-output hash mismatch and print a got:
hash. Copy that value back into cargoHash.

Example:

cargoHash = "sha256-...";

Re-run the package build after updating the hash.

4. Refresh OpenCC dictionary inputs

zhtw-mcp generates src/engine/s2t_data.rs from three OpenCC dictionary
files during the Nix build:

• STPhrases.txt
• STCharacters.txt
• TWVariants.txt

The Nix package pins these files through:

openccRev = "...";
openccDicts = final.linkFarm "opencc-dictionaries" [ ... ];

To update the OpenCC source revision:

nix develop -c git ls-remote https://github.com/BYVoid/OpenCC.git refs/heads/master

Copy the commit hash into openccRev.

Then prefetch each dictionary at the new revision:

nix develop -c nix store prefetch-file --json \
  https://raw.githubusercontent.com/BYVoid/OpenCC/<openccRev>/data/dictionary/STPhrases.txt

nix develop -c nix store prefetch-file --json \
  https://raw.githubusercontent.com/BYVoid/OpenCC/<openccRev>/data/dictionary/STCharacters.txt

nix develop -c nix store prefetch-file --json \
  https://raw.githubusercontent.com/BYVoid/OpenCC/<openccRev>/data/dictionary/TWVariants.txt

Copy each returned hash into the matching fetchurl entry in flake.nix.

5. Format the flake

After editing flake.nix, run:

nix develop -c nixfmt flake.nix

6. Build and verify

Build the named package:

nix develop -c nix build .#zhtw-mcp

Build the default package:

nix develop -c nix build .

Run the built binary:

./result/bin/zhtw-mcp --version

Remove the local result symlink before committing:

rm result

7. Optional flake input updates

If you need newer nixpkgs or fenix inputs, update flake.lock:

nix develop -c nix flake update

Then rebuild:

nix develop -c nix build .#zhtw-mcp
nix develop -c nix build .

Review flake.lock carefully before committing. Input updates can change the
Rust toolchain, dependency build hooks, or platform behavior.

Troubleshooting

Missing src/engine/s2t_data.rs

The generated S2T table is intentionally ignored by Git. The Nix package
creates it in preBuild from the fixed OpenCC dictionary inputs. If the build
fails with a missing s2t_data.rs, check that preBuild still runs:

python3 scripts/gen-s2t-tables.py

Cargo vendor hash mismatch

This is expected after changing Rust dependencies. Use the fake-hash workflow
in "Refresh cargoHash".

CLI integration tests fail in the Nix check phase

The package check phase is limited to:

cargoTestFlags = [
  "--lib"
  "--bins"
];

Some CLI integration tests derive a binary path from Cargo's local target
layout and are not reliable inside the Nix build sandbox. Run the full test
suite from the development shell when changing application behavior:

nix develop -c make check

---

Summary by cubic

Add a Nix flake for zhtw-mcp so it can be run with nix run or installed with nix profile, plus a dev shell for contributors. Also fixes toolchain selection and build metadata to improve cross-compilation, reproducibility, and docs.

• New Features

  • Flake exposes zhtw-mcp as the default package; run with nix run github:sysprog21/zhtw-mcp -- or install via nix profile.
  • Dev shell with fenix Rust toolchain and common Cargo tools; .envrc enables use flake.
  • Reproducible build with pinned cargoHash and OpenCC dictionaries; s2t_data.rs generated in preBuild; pins nixpkgs/fenix in flake.lock.

• Bug Fixes

  • Toolchain and build: select fenix via final.stdenv for correct system/cross builds; read version from Cargo.toml using builtins.fromTOML; include rustToolchain in nativeBuildInputs and use PATH rustfmt.
  • Metadata and docs: update meta (adds Unix platforms), remove incorrect opencode mcp add example, and ignore /result.

^{Written for commit 54de53d. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 4 files

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a Nix flake to build and run zhtw-mcp reproducibly, enabling nix run usage and a Nix-based dev shell, plus documentation for running/registering the MCP server via Nix.

Changes:

• Introduce flake.nix with zhtw-mcp package, pinned OpenCC dictionaries, and Rust toolchain via fenix.
• Add Nix usage instructions to README for running and registering MCP servers without global installs.
• Add .envrc to enable direnv/Nix flake development environment.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 3 comments.

File	Description
flake.nix	Defines Nix flake outputs: overlay, package build, devShell, formatter; pins OpenCC inputs for reproducibility.
README.md	Documents nix run / nix profile install workflows and MCP client registration examples.
.envrc	Enables use flake for direnv-based local development.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 5 changed files in this pull request and generated 2 comments.

[pan93412]

改成在 https://github.com/pan93412/zhtw-mcp-nix 維護。