Repository navigation
Expand file tree
/
Copy pathmcp_server.py
More file actions
executable file
·5247 lines (4694 loc) · 225 KB
/
Copy pathmcp_server.py
File metadata and controls
executable file
·5247 lines (4694 loc) · 225 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env python3
"""
ZenHub MCP server — exposes ZenHub backlog operations to any Claude Code session
on this machine via the `zh` CLI.
Wraps tools/zh so that:
- Read tools (board, pipeline, issue, mine, epic_list, epic_show,
subissue_list) return structured data parseable by callers.
- Write tools (create_issue, close_issue, move_issue, reorder, comment,
epic_create, epic_update, epic_add_children, epic_remove_children,
epic_close, epic_reopen, subissue_add_children, subissue_remove_children,
subissue_reorder, assign, unassign, estimate, pipeline_create,
pipeline_move, pipeline_rename, pipeline_delete) are explicit verbs
so callers can audit which destructive operations they invoked.
- Release tools (release_list, release_show, release_create, release_edit,
release_close, release_reopen, release_add, release_remove) wrap
`zh release`; there is no release_delete because ZenHub's API cannot
delete a release.
v1.9.0 model migration: ZenHub removed Legacy Epics and ZenhubEpics in June
2025. The epic_* tools no longer hit the dead ZenhubEpic API; an epic is now a
normal issue whose issue-type is Epic, with children wired via Sub-Issues. The
same machinery backs first-class tools for every planning level (initiative /
project / epic / subtask) plus set_issue_type and list_priorities. Type
discovery uses assignableIssueTypes (the full 5-level hierarchy), not the old
githubIssueTypes repo query.
Every tool optionally accepts a `repo_path` argument — the absolute path of a
git checkout that the underlying `zh` invocation runs from. This is required
because `zh` detects the GitHub repo via `git config --get remote.origin.url`
from its working directory. If omitted, falls back to:
1. ZH_DEFAULT_REPO_PATH environment variable
2. The MCP server's current working directory at launch time
Run as a subprocess (stdio transport):
/usr/bin/python3 mcp_server.py
The script self-bootstraps a durable venv under XDG_DATA_HOME (default
`~/.local/share/zh/venv`) on first run, validates it on every launch, and
re-execs under that venv. Any python3 on PATH that can run `python3 -m venv`
works as the launcher.
Register user-scope so every Claude Code session sees it:
claude mcp add --scope user zenhub \\
/usr/bin/python3 \\
/path/to/zenhub-cli/mcp_server.py
Environment overrides:
ZH_DEFAULT_REPO_PATH — default git-checkout dir to run zh from
(otherwise uses MCP server cwd at launch)
ZH_BIN_PATH — path to zh bash script (default: peer to this file)
ZH_MCP_VENV — full ABSOLUTE path of the venv directory to use;
overrides the XDG_DATA_HOME-derived default. Useful
for pinning to a project-local venv during
development. Relative paths are rejected.
XDG_DATA_HOME — standard XDG override for the data root; the venv
is created at `$XDG_DATA_HOME/zh/venv`.
ZH_MCP_PROBE_TIMEOUT — seconds for the per-launch `import` probe that
validates the venv (default 30). Widen on slow
media (NFS home, FileVault cold cache) where the
import can otherwise time out and trigger a
needless rebuild.
"""
from __future__ import annotations
import fcntl
import hashlib
import json
import logging
import os
import re
import shutil
import subprocess
import sys
from contextlib import contextmanager
from pathlib import Path
# Module logger (issue #39): diagnostics from the outcome-sentinel parser
# route through the standard logging machinery instead of a raw stderr
# write, so operators of a long-running MCP stdio server can configure
# where MCP-internal logs go without those lines colliding with FastMCP's
# framing-adjacent stderr output.
log = logging.getLogger(__name__)
# -----------------------------------------------------------------------------
# Self-bootstrap: build (or rebuild, if broken / stale) a durable venv under
# XDG_DATA_HOME, validate it, and re-exec under it. Must run before any
# third-party import (mcp).
# -----------------------------------------------------------------------------
def _default_venv_dir() -> tuple[Path, bool]:
"""Compute the default venv location.
Returns `(venv_dir, user_supplied)`. `user_supplied` is True when
the path came from the explicit `ZH_MCP_VENV` env var (subject to
strict typo protection downstream) and False when the path is the
server-chosen XDG default (subject to permissive auto-mkdir).
Threading the flag through to downstream callers (rather than
re-reading the env in each consumer) keeps the classification
coupled to the path it produced — env mutation between calls
can't defeat the typo guard.
Priority:
1. ZH_MCP_VENV environment variable (full path) → user_supplied=True
2. $XDG_DATA_HOME/zh/venv (standard XDG; defaults to
~/.local/share/zh/venv when XDG_DATA_HOME is unset) →
user_supplied=False
"""
raw_override = os.environ.get("ZH_MCP_VENV")
if raw_override is not None and not raw_override.strip():
# Distinguish unset from set-to-empty so a CI/Docker config that
# did `ENV ZH_MCP_VENV=` (clearing an inherited value) or
# `ZH_MCP_VENV="$UNSET_VAR"` doesn't silently fall through to
# XDG. Surface the situation; still fall through so the launch
# can succeed.
print(
"[zenhub-mcp] warning: ZH_MCP_VENV is set but empty / "
"whitespace; ignoring and using XDG_DATA_HOME default.",
file=sys.stderr,
flush=True,
)
override = (raw_override or "").strip()
if override:
expanded = Path(override).expanduser()
if str(expanded).startswith("~"):
# HOME unset → expanduser leaves `~` unchanged → resolve()
# would pin it to cwd, producing a literal `~` directory +
# rebuild loop across cwds.
raise RuntimeError(
f"[zenhub-mcp] cannot resolve home directory in "
f"ZH_MCP_VENV={override!r} (HOME is unset). Set HOME or "
f"give ZH_MCP_VENV an absolute path."
)
if not expanded.is_absolute():
# A relative ZH_MCP_VENV (e.g. `./venv` or `venv`) would be
# `.resolve()`-d against whatever cwd the MCP launched from.
# Claude Code launches the server from different project
# repo_paths, so a relative path produces a DIFFERENT venv
# per project — orphaned ~500MB venvs scattered across
# trees. Require an absolute (or `~`-prefixed) path.
raise RuntimeError(
f"[zenhub-mcp] ZH_MCP_VENV must be an absolute path "
f"(or start with `~`); got {override!r}. A relative "
f"path would resolve differently per launch cwd."
)
return expanded.resolve(), True
xdg_raw = os.environ.get("XDG_DATA_HOME") or "~/.local/share"
xdg_data = os.path.expanduser(xdg_raw)
if xdg_data.startswith("~"):
# `expanduser` leaves `~` unchanged only when it can resolve
# neither HOME nor a passwd entry for the uid — i.e. HOME is
# unset AND `pwd.getpwuid(os.getuid())` has no home dir
# (distroless / scratch containers, `nobody`, some sandboxes).
# In that case `Path("~/...").resolve()` would pin against cwd
# and produce a literal `~` directory, different across
# launches → rebuild loops. Raise instead.
raise RuntimeError(
f"[zenhub-mcp] cannot resolve home directory in {xdg_raw!r} "
f"(HOME is unset). Set HOME, set XDG_DATA_HOME to an "
f"absolute path, or set ZH_MCP_VENV to point at the venv "
f"location explicitly."
)
# `.resolve()` on both branches — pins relative paths (e.g. a
# mis-configured `XDG_DATA_HOME=./local-data`) at startup so the
# MCP doesn't thrash between projects when it launches from
# different cwds, and produces consistent paths in error messages
# regardless of which branch was taken.
return (Path(xdg_data) / "zh" / "venv").resolve(), False
# INVARIANT: keep the LIGHTEST dependency first. `_venv_per_launch_probe`
# imports `_VENV_DEPS[0]` on every MCP launch to validate the venv, so
# the first entry must be cheap to import. Reordering this so
# `sentence-transformers` (→ torch, multi-second cold import) lands at
# [0] would make every launch slow without tripping any error — exactly
# the cost the per-launch/full probe split exists to avoid.
_VENV_DEPS = (
# Pinned below 2.0: the 2.x MCP SDK restructured and dropped
# `mcp.server.fastmcp`, which this server imports, so an unpinned bootstrap
# resolves to a version that cannot start. Every existing working install
# is on 1.x only because it predates the 2.0 release.
"mcp>=1.0,<2",
# similarity search: sentence-transformers brings in torch + transformers
# + huggingface_hub. The model weights themselves are cached under
# ~/.cache/huggingface/ so they survive even if the venv is rebuilt.
"sentence-transformers",
"numpy",
)
_VENV_MIN_PY = (3, 10) # mcp package requires >= 3.10
_VENV_MARKER = ".zh-deps-hash" # records the _VENV_DEPS hash this venv was built for
_BUILD_SENTINEL = ".zh-build-in-progress" # written during _build_venv; absent on success
_BOOTSTRAP_LOCK = ".zh-bootstrap.lock" # fcntl.flock file for concurrent-launch serialization
def _probe_timeout_default() -> int:
"""Per-launch probe timeout, overridable via ZH_MCP_PROBE_TIMEOUT.
Defaults to 30s. The probe (`import mcp` and its ~30 transitive
modules — pydantic, httpx, anyio, sse-starlette, …) can exceed a
tight bound on a cold disk (FileVault sleep/wake, NFS-mounted home,
Docker bind mount, AV-scanning laptop, Spotlight first read), and a
timeout there triggers a needless multi-minute rebuild. 30s is a
safer floor than the original 15s; the env var lets operators on
slow media widen it further.
"""
raw = os.environ.get("ZH_MCP_PROBE_TIMEOUT", "").strip()
return int(raw) if raw.isdigit() and int(raw) > 0 else 30
# Subprocess timeouts. The per-launch probe stays snappy (one import) so
# slow cold-disk transformers imports don't trigger needless rebuild
# loops; the post-build probe runs once when caches are warm anyway.
# Captured once at import. The env override (ZH_MCP_PROBE_TIMEOUT) must
# therefore be set BEFORE the process starts — it won't pick up a
# mid-process change. That's correct for a real MCP server (env comes
# from the launch config), and the unit tests call _probe_timeout_default()
# directly so they're unaffected.
_VENV_PER_LAUNCH_PROBE_TIMEOUT = _probe_timeout_default()
_VENV_FULL_PROBE_TIMEOUT = 60 # all _VENV_DEPS — cold-cache torch import can take ~30s
_VENV_BUILD_TIMEOUT = 60 # `python -m venv ...`
_VENV_PIP_TIMEOUT = 600 # `pip install ...` (torch is ~400MB)
# A requirement specifier's name is everything before the first version
# constraint, extras bracket, marker, or whitespace.
_DEP_NAME_RE = re.compile(r"^\s*([A-Za-z0-9._-]+)")
def _dep_module_name(spec: str) -> str:
"""Importable module name for a `_VENV_DEPS` entry.
Entries are PyPI REQUIREMENT SPECIFIERS, not module names, so the version
constraint has to come off before the name can be imported: a pin like
`mcp>=1.0,<2` must probe `import mcp`, never `import mcp>=1.0,<2` — which
is a SyntaxError, so the probe fails, the freshly-built venv is judged
broken and deleted, and every subsequent launch rebuilds and fails the same
way. Extras (`pkg[extra]`) are stripped for the same reason. The remaining
PyPI dash convention maps to the module underscore convention.
"""
match = _DEP_NAME_RE.match(spec)
base = match.group(1) if match else spec
return base.replace("-", "_")
def _venv_per_launch_probe() -> str:
"""Lightweight probe — imports just the first declared dep (`mcp`) —
runs on every MCP launch.
Importing the full _VENV_DEPS tuple (sentence_transformers + torch +
numpy) takes seconds on a warm cache and tens of seconds on a cold
one — far too costly to pay on every launch. The post-build probe
(`_venv_full_probe`) catches half-installed venvs once; per-launch
just confirms the interpreter still runs and the primary dep
imports. Derived from `_VENV_DEPS[0]` (not hardcoded) so a future
rename/reorder of the deps tuple can't leave this probing a module
that no longer exists.
"""
return f"import {_dep_module_name(_VENV_DEPS[0])}"
def _venv_full_probe() -> str:
"""Heavyweight probe — every declared dep — runs once after build.
Catches a partial install where one wheel landed cleanly and
another failed mid-stream. Recomputes from `_VENV_DEPS` at call
time so monkeypatching tests see matching imports. If a future dep has a
non-trivial name→module mapping (`Pillow` → `PIL`), the probe fails loudly
at the call site — desired behavior.
"""
return "; ".join(
f"import {_dep_module_name(name)}" for name in _VENV_DEPS
)
def _deps_hash() -> str:
"""Stable hash of _VENV_DEPS — used to detect dep changes between launches.
A 16-char SHA-256 prefix is plenty: collisions don't matter for a
cache-invalidation token that's only compared against itself.
"""
return hashlib.sha256("|".join(_VENV_DEPS).encode()).hexdigest()[:16]
def _venv_is_valid(venv_dir: Path, deps_hash: str) -> bool:
"""Return True iff `venv_dir` is a working venv built for `deps_hash`.
Catches all the failure modes that have happened in practice:
- bin/python missing (venv never built, or partial wipe)
- pyvenv.cfg missing (venv structure incomplete — Python won't add
the venv's site-packages to sys.path, so installed wheels are
unreachable)
- deps-hash marker missing or mismatched (deps tuple changed since
the venv was built — needs reinstall)
- `import mcp` fails under the venv's python (interpreter or
site-packages broken, e.g. pyenv updated underneath us)
`venv_dir` and `deps_hash` are arguments (not module globals) so this
function is unit-testable with synthetic temp-dir fixtures.
"""
venv_py = venv_dir / "bin" / "python3"
if not venv_py.exists():
return False
if not (venv_dir / "pyvenv.cfg").exists():
return False
marker = venv_dir / _VENV_MARKER
if not marker.exists():
return False
try:
marker_value = marker.read_text(encoding="utf-8").strip()
except (OSError, UnicodeDecodeError):
# Corrupt, root-owned, or non-UTF-8 marker → treat as invalid so
# the bootstrap rebuilds instead of crashing with a traceback.
return False
if marker_value != deps_hash:
return False
try:
subprocess.check_call(
[str(venv_py), "-c", _venv_per_launch_probe()],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
timeout=_VENV_PER_LAUNCH_PROBE_TIMEOUT,
)
except (subprocess.CalledProcessError, subprocess.TimeoutExpired, OSError):
# Probe failed, timed out, or interpreter is unrunnable —
# rebuild rather than try to limp along.
return False
return True
def _find_builder_python(venv_dir: Path) -> str:
"""Return a python3 executable suitable for building the venv at `venv_dir`.
Prefer the interpreter that invoked us; fall back to common Homebrew /
pyenv locations. Skips anything below `_VENV_MIN_PY`. `venv_dir` is
used only for the error message — passed as a parameter so the
function doesn't depend on a module-level `_VENV_DIR` snapshot.
"""
if sys.version_info >= _VENV_MIN_PY:
return sys.executable
candidates = [
"/opt/homebrew/opt/pyenv/shims/python3",
os.path.expanduser("~/.pyenv/shims/python3"),
shutil.which("python3"),
"/opt/homebrew/bin/python3",
"/usr/local/bin/python3",
"/usr/bin/python3",
]
probe = (
"import sys; "
f"sys.exit(0 if sys.version_info >= {_VENV_MIN_PY} else 1)"
)
seen = set()
for cand in candidates:
if not cand or cand in seen or not os.path.exists(cand):
continue
seen.add(cand)
try:
subprocess.check_call(
[cand, "-c", probe],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
timeout=10, # probe is `sys.exit(0 if ver >= ...)` — <100ms in practice
)
return cand
except (subprocess.CalledProcessError,
subprocess.TimeoutExpired,
OSError):
continue
raise RuntimeError(
f"No python3 >= {_VENV_MIN_PY[0]}.{_VENV_MIN_PY[1]} found to build "
f"{venv_dir}; install one (e.g. via pyenv or `brew install python`) "
f"and retry."
)
def _looks_like_zh_venv(venv_dir: Path) -> bool:
"""Return True iff `venv_dir` is safe for `_build_venv` to rmtree.
A user-controlled `ZH_MCP_VENV` (or a typo'd `XDG_DATA_HOME`) could
point the venv path at any directory on disk — including `$HOME`, a
project venv, or a regular file. Without this guard, a stale/wrong
path plus a routine "venv looks invalid" verdict would silently
`shutil.rmtree` arbitrary user data on the next launch.
Safe to delete only when:
- the path doesn't exist yet (nothing to remove)
- the path is a directory AND empty (nothing to lose)
- the path is a directory AND carries our `_VENV_MARKER`
(a venv we built and certified) OR `_BUILD_SENTINEL` (a venv
a prior `_build_venv` crashed in the middle of). The sentinel
is what makes the bootstrap self-healing across crashes /
Ctrl-C / SIGKILL mid-build: even with no marker, the sentinel
certifies "we own this directory, safe to wipe and retry."
`pyvenv.cfg` alone is NOT sufficient — the user may have
pointed ZH_MCP_VENV at their own project's venv.
Anything else (a regular file, an unreadable dir, a foreign venv,
`~/Documents`) must be removed by the user explicitly.
"""
if not venv_dir.exists():
return True
if not venv_dir.is_dir():
return False # regular file, FIFO, etc.
try:
is_empty = not any(venv_dir.iterdir())
except OSError:
return False # unreadable, race-deleted, etc.
if is_empty:
return True
return (
(venv_dir / _VENV_MARKER).exists()
or (venv_dir / _BUILD_SENTINEL).exists()
)
def _ensure_safe_parent(venv_dir: Path, *, user_supplied: bool) -> None:
"""Validate the path's parent before any mkdir.
Two modes, distinguished by the explicit `user_supplied` flag from
`_default_venv_dir`:
1. **Server-chosen default** (`user_supplied=False`): the path comes
from `_default_venv_dir`'s XDG branch — `$XDG_DATA_HOME/zh/venv`,
typically `~/.local/share/zh/venv`. `~/.local/share` is NOT
guaranteed to exist on fresh macOS accounts, minimal Linux
containers (python:slim, distroless, Alpine), DynamicUser=
systemd sandboxes, or CI runners with bespoke $HOME. Auto-
create the full ancestor tree; the path is server-controlled
and not subject to typo risk.
2. **User-supplied** (`user_supplied=True`): apply strict typo
protection. Require the grandparent to pre-exist and only
create ONE new directory level. A typo'd path like
`ZH_MCP_VENV=~/something-typo/sub/venv` refuses rather than
silently materializing a 500MB venv tree at an unexpected
location.
The flag is threaded as a parameter (not re-read from env at each
call boundary) so the classification stays coupled to the path
`_default_venv_dir` produced. Env mutation between calls can't
defeat the typo guard.
In both modes, a pre-existing regular file at the parent path
raises a clear RuntimeError (avoiding the unhelpful
`FileExistsError: [Errno 17]` traceback from `mkdir`).
"""
parent = venv_dir.parent
if parent.exists():
# NOTE: `exists()` / `is_dir()` follow symlinks. A symlinked
# parent (e.g. `~/.local/share` → a tmpfs-backed dir, or a
# bespoke dotfile layout) is accepted as-is — we deliberately
# do NOT reject symlinked parents, since that's a legitimate
# and common setup. The downstream consequence is that if the
# symlink's target vanishes between launches (tmpfs cleared on
# reboot), the venv is simply rebuilt at the new target — no
# data loss, just a one-time rebuild.
if not parent.is_dir():
raise RuntimeError(
f"[zenhub-mcp] refusing to bootstrap into {venv_dir}: "
f"parent {parent} exists but is not a directory. Remove "
f"or rename the stray file, or set ZH_MCP_VENV / "
f"XDG_DATA_HOME to point elsewhere."
)
return
if not user_supplied:
# Server-chosen XDG default. Auto-create the ancestor tree;
# the path is server-controlled. Without this, a fresh user
# account where `~/.local/share` doesn't exist yet would fail
# to bootstrap — the most common first-launch failure on a
# vanilla macOS install.
parent.mkdir(parents=True, exist_ok=True)
return
grandparent = parent.parent
if not grandparent.exists():
raise RuntimeError(
f"[zenhub-mcp] refusing to bootstrap into {venv_dir}: "
f"ancestor {grandparent} does not exist. Auto-creating a "
f"deep directory tree from a typo'd ZH_MCP_VENV would "
f"silently pollute user space — create the parent "
f"directory manually and retry."
)
# `exist_ok=True` because _ensure_safe_parent runs BEFORE the
# bootstrap lock is acquired — two concurrent launches can both
# pass the `parent.exists()` check above; the second one would
# otherwise raise FileExistsError. The single-level-creation
# safety property is enforced by the `grandparent.exists()` check
# above, not by mkdir's mode.
parent.mkdir(exist_ok=True)
def _safe_rmtree(path: Path, *, ignore_errors: bool = False) -> None:
"""Robust rmtree that handles symlinks + a NARROW class of EACCES.
Plain `shutil.rmtree` raises on symlinked dirs (`OSError: Cannot
call rmtree on a symbolic link`) and on permission errors mid-walk.
This wrapper:
- unlinks symlinks instead of recursing (preserves the target)
- on `PermissionError` during a walk, chmods BOTH the failing
path AND its parent and retries
- re-raises if a retry still fails, unless `ignore_errors=True`
Recoverable cases:
- file-unlink failure where the parent dir had write/execute
bits dropped (chmod parent → retry unlink succeeds)
- empty-dir rmdir failure where the dir itself had mode 000
(chmod dir → retry rmdir succeeds)
NOT recoverable here (despite the chmod retry firing):
- `os.scandir` failure on a non-empty user-owned mode-000 dir.
CPython's `shutil.rmtree` discards the retried iterator and
treats the dir as empty, then `os.rmdir` raises `ENOTEMPTY`.
Use `chmod -R u+rwx <path>` manually first.
- any file/dir owned by another user (the chmod itself raises
`PermissionError`).
Cleanup-path callers (inside `_build_venv` except blocks) pass
`ignore_errors=True` so a failed cleanup doesn't mask the
original build failure.
"""
try:
if path.is_symlink():
# Don't follow the symlink and rmtree the target! Just
# remove the link itself.
path.unlink()
return
# Bind the rmtree root in the closure so the chmod-parent
# retry below can verify the parent it's about to chmod is
# INSIDE the cleanup target. Round-3 #1: when shutil.rmtree
# fails at the root itself (e.g. `os.scandir(venv_dir)` raises),
# `os.path.dirname(p)` is `venv_dir.parent` — a directory
# OUTSIDE our cleanup scope. Chmod-ing it silently downgrades
# perms on a shared `~/.local/share/zh` or `/srv/shared/...`.
# Never modify dirs outside the rmtree root.
rmtree_root = path
def _handle(func, p, exc):
# `exc` is an exception instance (the unified form). Defensive
# None guard: shutil can theoretically hand us something odd.
if exc is not None and isinstance(exc, PermissionError):
# Permission to unlink depends on the PARENT dir's
# write+execute bits, not on the file's mode. Chmod the
# parent ONLY if it sits at or inside the rmtree root —
# never the root's own parent.
p_parent = Path(p).parent
if p_parent == rmtree_root or rmtree_root in p_parent.parents:
try:
os.chmod(str(p_parent), 0o700)
except OSError:
pass
try:
os.chmod(p, 0o700)
func(p)
return
except OSError:
pass
raise exc
# Python 3.12 deprecated `onerror=(func, path, exc_info_tuple)`
# in favor of `onexc=(func, path, exc_instance)`, and emits a
# DeprecationWarning to stderr on every call — which lands in
# the MCP stdio transport's visible output. Dispatch by version
# so 3.12+ uses onexc and 3.10/3.11 keep onerror. Both adapt to
# the single `_handle(func, p, exc_instance)` shape.
if sys.version_info >= (3, 12):
shutil.rmtree(path, onexc=_handle)
else:
shutil.rmtree(
path,
onerror=lambda func, p, info: _handle(func, p, info[1]),
)
except OSError:
if not ignore_errors:
raise
def _build_venv(venv_dir: Path, deps_hash: str, *, user_supplied: bool) -> None:
"""Tear down (if present and safe) and rebuild the venv at `venv_dir`.
Refuses to rebuild a directory that doesn't look like a venv (no
`_VENV_MARKER`, no `_BUILD_SENTINEL`) to prevent destroying user
data pointed at by a typo'd `ZH_MCP_VENV`. Writes a sentinel file
at the start of the build so a crash mid-flight (Ctrl-C, SIGKILL,
OOM, network failure, double-Ctrl-C-during-cleanup) leaves a
self-recoverable state: `_looks_like_zh_venv` recognizes the
sentinel and the next launch can safely rmtree + rebuild without
manual cleanup. The marker is written only after the full
post-build probe passes; sentinel is removed last.
"""
if not _looks_like_zh_venv(venv_dir):
raise RuntimeError(
f"[zenhub-mcp] refusing to bootstrap into {venv_dir}: it "
f"exists but does not look like a venv we built (no "
f"{_VENV_MARKER} marker, no {_BUILD_SENTINEL} sentinel). "
f"Check your ZH_MCP_VENV / XDG_DATA_HOME settings; remove "
f"the directory manually if you really want it rebuilt."
)
builder = _find_builder_python(venv_dir)
venv_py = venv_dir / "bin" / "python3"
if venv_dir.exists():
print(
f"[zenhub-mcp] rebuilding {venv_dir} "
f"(missing/broken or _VENV_DEPS changed)",
file=sys.stderr,
flush=True,
)
else:
print(
f"[zenhub-mcp] bootstrapping {venv_dir} with {builder}",
file=sys.stderr,
flush=True,
)
_ensure_safe_parent(venv_dir, user_supplied=user_supplied)
try:
# rmtree lives INSIDE the try so a partial rmtree failure
# (EACCES on a root-owned `__pycache__/*.pyc`, NFS stale
# handle, antivirus quarantine race) hits the cleanup path
# rather than escaping uncaught and bricking the next launch.
if venv_dir.exists():
_safe_rmtree(venv_dir)
# Pre-create the venv dir and write the sentinel BEFORE any
# subprocess. `python -m venv` preserves pre-existing files
# in the target dir (it doesn't `--clear` by default), so the
# sentinel survives the build. If anything between here and
# the final marker write crashes — Ctrl-C, OOM, SIGKILL,
# subprocess error — the sentinel stays on disk so the next
# launch's _looks_like_zh_venv returns True and recovery is
# automatic.
venv_dir.mkdir()
sentinel = venv_dir / _BUILD_SENTINEL
# Sentinel CONTENT is irrelevant to correctness — only its
# PRESENCE matters (it marks the dir as ours so a crashed build
# is safely rebuildable). Deliberately no timestamp: a
# machine-readable `started_at` would invite a future
# "stale sentinel" age-check that breaks the simple
# presence-means-ours invariant, and would record nonsense on
# clock-skewed hosts. Human-readable note only.
sentinel.write_text(
"zenhub-cli MCP venv build in progress.\n"
"Presence of this file marks the directory as ours, so a "
"crashed/interrupted build can be safely wiped and rebuilt "
"on the next launch. Safe to delete if no build is running.\n",
encoding="utf-8",
)
subprocess.check_call(
[builder, "-m", "venv", str(venv_dir)],
timeout=_VENV_BUILD_TIMEOUT,
)
subprocess.check_call(
[str(venv_py), "-m", "pip", "install",
"--quiet", "--no-cache-dir", "--upgrade", "pip"],
timeout=_VENV_PIP_TIMEOUT,
)
subprocess.check_call(
[str(venv_py), "-m", "pip", "install",
"--quiet", "--no-cache-dir", *_VENV_DEPS],
timeout=_VENV_PIP_TIMEOUT,
)
except (KeyboardInterrupt, SystemExit):
# First-time bootstrap takes minutes (torch is ~400MB). On
# Ctrl-C / SIGTERM, attempt cleanup — but if that fails (e.g.
# second Ctrl-C during rmtree), the sentinel on disk still
# marks the dir as ours, so the next launch can recover
# without manual intervention.
_safe_rmtree(venv_dir, ignore_errors=True)
raise
except (subprocess.TimeoutExpired,
subprocess.CalledProcessError,
OSError) as exc:
# Build crashed mid-flight — clean up so the next launch's
# _looks_like_zh_venv sees a missing path (safe to rebuild)
# instead of needing the sentinel recovery path.
_safe_rmtree(venv_dir, ignore_errors=True)
if isinstance(exc, subprocess.TimeoutExpired):
reason = (f"timed out after {exc.timeout}s "
f"({exc.cmd[0] if exc.cmd else '?'} ...)")
else:
reason = f"build subprocess failed: {exc}"
raise RuntimeError(
f"[zenhub-mcp] venv build at {venv_dir} {reason}. Cleaned "
f"up partial state; check your network (slow PyPI mirror?) "
f"and Python installation, then retry."
) from exc
# Post-build sanity check BEFORE writing the marker. Uses the FULL
# probe (every declared dep, not just `mcp`) so a half-installed
# venv where `sentence-transformers` failed mid-stream isn't
# certified good. The per-launch probe stays light to avoid cold-
# cache transformers-import rebuild loops.
try:
subprocess.check_call(
[str(venv_py), "-c", _venv_full_probe()],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
timeout=_VENV_FULL_PROBE_TIMEOUT,
)
except (subprocess.CalledProcessError,
subprocess.TimeoutExpired,
OSError) as exc:
_safe_rmtree(venv_dir, ignore_errors=True)
raise RuntimeError(
f"[zenhub-mcp] venv at {venv_dir} was built but cannot "
f"import all declared deps ({', '.join(_VENV_DEPS)}). "
f"Cleaned up; retry the launch. Check your network and "
f"Python installation."
) from exc
# Atomic + durable marker write. os.replace makes the rename
# atomic w.r.t. directory-entry visibility, but NOT durable: on
# ext4 `data=ordered`, a power loss between the write and the
# metadata commit can leave a zero-byte marker post-recovery —
# which then fails the hash compare and triggers a rebuild loop
# after every unclean shutdown. fsync the file contents before the
# rename, and fsync the directory after, so the marker + its
# directory entry are both on stable storage.
marker = venv_dir / _VENV_MARKER
tmp_marker = marker.with_suffix(".tmp")
with open(tmp_marker, "w", encoding="utf-8") as fh:
fh.write(deps_hash)
fh.flush()
os.fsync(fh.fileno())
os.replace(tmp_marker, marker)
try:
dir_fd = os.open(str(venv_dir), os.O_RDONLY)
try:
os.fsync(dir_fd)
finally:
os.close(dir_fd)
except OSError:
# Directory fsync is best-effort (not supported on every
# filesystem). The file-level fsync + atomic rename already
# give us the critical guarantee.
pass
# Sentinel last — the build is fully certified before we declare
# it complete. A crash here leaves the marker (good) AND the
# sentinel (also harmless — next launch will see the marker and
# treat the venv as valid). Swallow non-FileNotFoundError too
# (PermissionError, AV-scanner race) — the marker is the source
# of truth at this point; the sentinel is cosmetic cleanup.
try:
sentinel.unlink(missing_ok=True)
except OSError:
pass
@contextmanager
def _venv_build_lock(venv_dir: Path, *, user_supplied: bool):
"""Serialize concurrent `_build_venv` invocations via fcntl.flock.
Two MCP launches that fire within seconds (Claude Code session
restart, supervisor reconnect, two terminal windows) used to race
on rmtree + pip install with non-deterministic outcomes — one
process could rmtree the other's in-flight site-packages, leaving
a corrupt venv that the surviving process then certifies as
valid. fcntl.flock on a parent-dir lockfile gives us serialization
cheaply on POSIX. Callers should re-check `_venv_is_valid` AFTER
acquiring the lock — another process may have completed the
rebuild while we were waiting.
Calls `_ensure_safe_parent` BEFORE creating the lock file so a
typo'd `ZH_MCP_VENV` doesn't materialize an unintended ancestor
tree just to host the lockfile. The lock file lands at
`venv_dir.parent / _BOOTSTRAP_LOCK`.
`user_supplied` is threaded from `_default_venv_dir` so the
typo-protection in `_ensure_safe_parent` stays coupled to the
path's origin.
"""
_ensure_safe_parent(venv_dir, user_supplied=user_supplied)
lock_path = venv_dir.parent / _BOOTSTRAP_LOCK
# `O_NOFOLLOW` defeats the symlink-redirect attack vector that's
# widest when ZH_MCP_VENV points at a shared-writable parent
# (`/tmp`, `/srv/shared`, `/var/cache`). Without it, a local user
# with write access to the parent could plant a symlink at
# `_BOOTSTRAP_LOCK` → `~/.bashrc` (or any sensitive file).
# Currently harmless because we only flock and never write, but
# safe against future diagnostic-write additions.
# `O_CLOEXEC` ensures the fd doesn't leak into the re-exec'd venv
# python or any subprocess pip spawns.
# Mode `0o600` keeps the lockfile single-user since it's per-process
# coordination state, not data anyone else needs to read.
fd = os.open(
str(lock_path),
os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW | os.O_CLOEXEC,
0o600,
)
try:
fcntl.flock(fd, fcntl.LOCK_EX)
try:
yield
finally:
fcntl.flock(fd, fcntl.LOCK_UN)
finally:
os.close(fd)
def _bootstrap_venv() -> None:
# Compute paths at call time (not at module import) so a future
# test that monkeypatches the env vars sees them — and so an
# unreadable parent path doesn't crash module import for tests
# that set ZH_MCP_SKIP_BOOTSTRAP=1.
venv_dir, user_supplied = _default_venv_dir()
venv_py = venv_dir / "bin" / "python3"
deps_hash = _deps_hash()
if not _venv_is_valid(venv_dir, deps_hash):
# Serialize concurrent bootstraps. After acquiring the lock,
# re-check validity — another process may have finished while
# we were waiting, in which case skipping the rebuild saves
# ~5 minutes of redundant torch download.
with _venv_build_lock(venv_dir, user_supplied=user_supplied):
if not _venv_is_valid(venv_dir, deps_hash):
_build_venv(venv_dir, deps_hash, user_supplied=user_supplied)
# Re-exec into the venv if we're not already running under it.
# Compare sys.prefix (the canonical "which prefix am I running under")
# to the venv dir, NOT realpath(sys.executable) vs realpath(venv_py)
# — those resolve to the same target on Linux when the venv's bin/python
# is a symlink to the same builder interpreter as the launcher, which
# incorrectly skips the re-exec and leaves us running outside the venv.
if Path(sys.prefix).resolve() != venv_dir.resolve():
# Flush before execv: stderr is block-buffered under the MCP stdio
# transport, so the "bootstrapping" / "rebuilding" messages would
# otherwise be lost. `__file__` is resolved to an absolute path so
# the child works even if a wrapper script changes cwd between
# launch and bootstrap.
sys.stderr.flush()
sys.stdout.flush()
argv = [str(venv_py), str(Path(__file__).resolve()), *sys.argv[1:]]
try:
os.execv(str(venv_py), argv)
except OSError:
# TOCTOU: the venv was wiped between _venv_is_valid and
# execv (concurrent rm, broken symlink, race-deleted bin/
# by a stale clean-up script). Rebuild once and retry; if
# the second exec also fails, let it propagate.
print(
f"[zenhub-mcp] {venv_py} missing at exec time; "
f"rebuilding once and retrying...",
file=sys.stderr,
flush=True,
)
with _venv_build_lock(venv_dir, user_supplied=user_supplied):
if not _venv_is_valid(venv_dir, deps_hash):
_build_venv(venv_dir, deps_hash, user_supplied=user_supplied)
sys.stderr.flush()
sys.stdout.flush()
try:
os.execv(str(venv_py), argv)
except OSError as exc:
# Second exec failed too — the venv was rebuilt but
# still can't be exec'd (noexec mount, broken interpreter,
# SELinux/AppArmor exec denial, or a second TOCTOU race).
# Surface an actionable error instead of a bare OSError
# traceback at MCP startup.
raise RuntimeError(
f"[zenhub-mcp] failed to re-exec into {venv_py} even "
f"after rebuilding the venv: {exc}. The venv may be on "
f"a noexec mount or the interpreter is broken/blocked. "
f"Delete {venv_dir} and relaunch; if it persists, set "
f"ZH_MCP_VENV to a path on an exec-capable filesystem."
) from exc
# Test-mode escape hatch: setting ZH_MCP_SKIP_BOOTSTRAP=1 in the
# environment skips the venv bootstrap AND substitutes a minimal
# `FastMCP` stub for the import below. This lets the pytest suite
# exercise the guard logic and result-dict shapes in MCP tools
# without pulling in mcp / torch / transformers / numpy. Production
# (the actual MCP server transport) must NEVER set this — without
# the real FastMCP, the server doesn't serve.
_MCP_SKIP_BOOTSTRAP = os.environ.get("ZH_MCP_SKIP_BOOTSTRAP", "") == "1"
if not _MCP_SKIP_BOOTSTRAP:
_bootstrap_venv()
from mcp.server.fastmcp import FastMCP
else:
# Minimal no-op stub. `@mcp.tool()` returns the function unchanged
# so tests can call the wrapped tool directly. The stub class is
# callable as `FastMCP("name")` and exposes a `.run()` that just
# raises (we don't want a test accidentally launching a server).
class FastMCP: # type: ignore[no-redef]
def __init__(self, name: str) -> None:
self.name = name
def tool(self, *args, **kwargs): # noqa: ARG002
def _decorator(fn):
return fn
return _decorator
def run(self) -> None:
raise RuntimeError(
"FastMCP stub: ZH_MCP_SKIP_BOOTSTRAP is set. The MCP "
"server cannot run in this mode; it's for unit tests only."
)
# =============================================================================
# Paths and configuration
# =============================================================================
HERE = Path(__file__).resolve().parent
ZH_BIN = Path(os.environ.get("ZH_BIN_PATH", str(HERE / "zh")))
# Make sibling modules (zh_api.py, zh_graphql_ops.py, similarity.py)
# importable when the MCP server is launched via the bootstrapped venv
# from any cwd. sys.path may not include __file__'s directory in that
# case.
if str(HERE) not in sys.path:
sys.path.insert(0, str(HERE))
# ANSI escape regex — zh emits colored output for terminals; strip for MCP.
#
# v1.9.2 round-4 (PR #27) finding #15: extend beyond pure SGR/CSI
# `\x1b[...m` to handle the broader CSI family (any final letter,
# not just 'm') plus OSC sequences (`ESC ] ... BEL` / `ESC ] ... ESC \`).
# Downstream tools that emit OSC-8 hyperlinks (`gh` with terminal-link
# autodetect, modern `jq --rgb`) used to leak raw escape bytes through
# this regex into MCP `stderr_plain` / `stdout_plain`, surfacing in the
# client as garbled diagnostics. The order matters: CSI strip runs
# first; OSC strip handles whatever remains. Both alternation branches
# are non-greedy.
_ANSI_RE = re.compile(
r"\x1b\[[0-9;?]*[a-zA-Z]" # CSI: ESC [ params final-byte (any letter)
r"|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)" # OSC: ESC ] text BEL or ST
)
_SUBPROCESS_ENCODING = "utf-8"
def _as_text(value: bytes | str | None) -> str:
"""Coerce a subprocess output field to str.
`subprocess.run(text=True)` decodes stdout/stderr only on normal
completion. When `communicate()` times out on POSIX, `TimeoutExpired.stdout`
and `.stderr` carry the raw bytes read so far, so anything that treats them
as text (the str-pattern `_ANSI_RE`, an f-string) must decode first. On
Windows, `run()` re-runs `communicate()` after `kill()` and repopulates the
fields as already-decoded str. Accepts None (nothing captured), bytes, and
str so the caller need not branch on the platform.
"""
if value is None:
return ""
if isinstance(value, bytes):
return value.decode(_SUBPROCESS_ENCODING, errors="replace")
return value
# Matches `zh`'s per-issue header rows in mine / pipeline / etc. listings:
# ` #645 │ owner/repo │ ...` (2-space indent). Two tightening choices
# both implemented as `[ \t]` (horizontal whitespace only, never \n):
# - Leading indent `^[ \t]{0,3}`: bounded to 0-3 so a 4-space title
# line that legitimately starts with `#NNN │` (cross-reference
# convention) isn't mistaken for the next header. Tab support is
# defensive — `zh` currently emits spaces.
# - Post-digit gap `\d+[ \t]*│`: previously `\s*` (which matches \n).
# Pins the single-line-match contract — a header that wraps mid-
# field (terminal resize, malformed unicode in a repo name) won't
# span lines and trip the title-walker bail-out. The walker only
# ever feeds one line at a time today; this is defense-in-depth.
_ISSUE_HEADER_RE = re.compile(r"^[ \t]{0,3}#\d+[ \t]*│")
# =============================================================================
# Helpers
# =============================================================================
def _resolve_cwd(repo_path: str = "") -> str:
"""Resolve the working directory zh should run from.
Priority:
1. Explicit `repo_path` arg (if non-empty)
2. ZH_DEFAULT_REPO_PATH env var
3. Current working directory at server launch time
"""
if repo_path:
return repo_path
return os.environ.get("ZH_DEFAULT_REPO_PATH", os.getcwd())
def _safe_int(value, default: int = 0) -> int:
"""Coerce `value` to int defensively; never raise.
v1.9.2 round-4 (PR #27) finding #8: round-3 #11 added
`int(r.get("exit_code") or 0)` to guard against `None` / `0` /
empty-string from a hypothetical serialization roundtrip. That
still raises `ValueError` on any non-numeric string (e.g. a
future `_run_zh` middleware emitting `exit_code='timeout'`
or `exit_code='killed'`). Wrapping it here means every
partial_applied derivation site degrades to `default` (0)
instead of raising MCP InternalError, which preserves the rest
of the response envelope for the agent.
v1.9.3 pattern-sweep finding #13: the bool branch's asymmetry
(`int(True) == 1` would otherwise apply) is INTENTIONAL.
Documented semantic: a bool here represents "a serialization
layer flipped a numeric exit_code into True/False" and cannot
be trusted to honestly report the underlying integer. The
alternative (return 1 for True) would silently encode
"partial-applied" for a value that may simply be the JSON
boolean `True`, leading every partial_applied derivation site
downstream to claim a partial that the subprocess never
signaled. Returning `default` (0) means such corrupt input is