DD-338 Phase E.python — stallari-mcp-helpers v0.1.0 initial release #1

Merged

piersdd merged 1 commit from feat/dd-338-e-python-mcp-helpers-v0.1.0 into main

2026-05-23 23:14:25 +00:00

piersdd commented

2026-05-23 23:12:43 +00:00

(Migrated from github.com)

Summary

Foundational substrate ship — first PyPI release of stallari-mcp-helpers, the canonical helper library for first-party Stallari Python MCP servers.

Lifts meta_envelope + append_meta (canonical _meta: {...} JSON-tail audit envelope) from syncthing-blade-mcp (sha256 pinned)
Lifts Pattern + compute_domain_hint + load_patterns_from_yaml (per-record domain attribution engine) from gmail-blade-mcp (sha256 pinned), generalised to use dot-path field navigation in place of gmail's field_projector callable
Eliminates 5×/7× duplication across gmail-, home-assistant-, mastodon-, tailscale-, syncthing-, caldav-, fastmail-blade-mcp
Spec B (architect-driven, post-merge + PyPI publish) will flip the 7 Python blades to consume this package

Public API

from stallari_mcp_helpers import (
    Pattern, compute_domain_hint, load_patterns_from_yaml,  # domain_hint
    meta_envelope, append_meta,                              # audit_envelope
)

Locked encoding for meta_envelope: tight JSON separators ((",", ":")), alphabetically-sorted filtered_by, ensure_ascii=False, required fields always present (filtered_by defaults [], next_cursor defaults JSON null), optional error_notes / domain_hints omitted when None or empty (Convention #22). Kwarg-only signature.

Verification

52 tests pass (28 domain_hint, 24 audit_envelope)
100% line + branch coverage on both helper modules
uv run ruff check clean
uv run ruff format --check clean
uv run mypy --strict clean
uv build produces dist/stallari_mcp_helpers-0.1.0.tar.gz + .whl

Source-pin verification

Source	sha256	Match
`~/src/gmail-blade-mcp/src/gmail_blade_mcp/domain_hint.py`	`1977670f39a0b3b2db37842d25e985f06d15296814cfb8daa0f725798138dba4`	✓
`~/src/syncthing-blade-mcp/src/syncthing_mcp/formatters.py`	`2ea00ebdb6da2577cfcd8c616e7560a914dd6d79f720a00d848612b49d0a79f8`	✓

API divergences from sources (architect-spec'd)

compute_domain_hint(record, patterns) — gmail's reference takes a third field_projector callable. The spec lifts this to a generic public API by dropping the projector and using built-in dot-path navigation (labels.priority reads record["labels"]["priority"]). All gmail-specific projector behaviour for nested lists / scalar-coercion preserved.
meta_envelope(...) — syncthing's reference omitted next_cursor + error_notes fields and used kwarg shape latency_ms positioned after redactions. Spec adopts the canonical wire-contract shape with next_cursor ALWAYS-present (JSON null default) and error_notes per DEVFU 2026-05-23-granularity-doc-optional-envelope-fields.
append_meta(body, meta_line) — syncthing's reference was a fat helper accepting full meta_envelope kwargs and constructing both. Spec collapses to a simple 2-arg joiner; callers compose meta_envelope(...) separately.

Test plan

uv sync --group dev clean
uv run pytest tests/ -v → 52 passed
uv run pytest tests/ --cov=src/stallari_mcp_helpers --cov-report=term-missing --cov-branch → 100% line + branch on domain_hint.py and audit_envelope.py
uv run ruff check src/ tests/ clean
uv run ruff format --check src/ tests/ clean
uv run mypy src/stallari_mcp_helpers clean (strict)
uv build produces sdist + wheel
Single commit on branch; Convention #17 trailer; SSH-signed
Architect post-merge: tag v0.1.0 + PyPI publish (out of scope for this PR)

References

Spec: ~/master-ai/atlas/utilities/agent-harness/specs/2026-05-24-dd-338-e-python-mcp-helpers-package.md
Decision record: DD-338 § "Substrate correction 2026-05-24" + DD-338 Phase E.python amendment

🤖 Generated with Claude Code

## Summary Foundational substrate ship — first PyPI release of `stallari-mcp-helpers`, the canonical helper library for first-party Stallari Python MCP servers. - Lifts `meta_envelope` + `append_meta` (canonical `_meta: {...}` JSON-tail audit envelope) from `syncthing-blade-mcp` (sha256 pinned) - Lifts `Pattern` + `compute_domain_hint` + `load_patterns_from_yaml` (per-record domain attribution engine) from `gmail-blade-mcp` (sha256 pinned), generalised to use dot-path field navigation in place of gmail's `field_projector` callable - Eliminates 5×/7× duplication across `gmail-`, `home-assistant-`, `mastodon-`, `tailscale-`, `syncthing-`, `caldav-`, `fastmail-blade-mcp` - Spec B (architect-driven, post-merge + PyPI publish) will flip the 7 Python blades to consume this package ## Public API ```python from stallari_mcp_helpers import ( Pattern, compute_domain_hint, load_patterns_from_yaml, # domain_hint meta_envelope, append_meta, # audit_envelope ) ``` Locked encoding for `meta_envelope`: tight JSON separators (`(",", ":")`), alphabetically-sorted `filtered_by`, `ensure_ascii=False`, required fields always present (`filtered_by` defaults `[]`, `next_cursor` defaults JSON `null`), optional `error_notes` / `domain_hints` omitted when None or empty (Convention #22). Kwarg-only signature. ## Verification - **52 tests pass** (28 `domain_hint`, 24 `audit_envelope`) - **100% line + branch coverage** on both helper modules - `uv run ruff check` clean - `uv run ruff format --check` clean - `uv run mypy --strict` clean - `uv build` produces `dist/stallari_mcp_helpers-0.1.0.tar.gz` + `.whl` ## Source-pin verification | Source | sha256 | Match | |---|---|---| | `~/src/gmail-blade-mcp/src/gmail_blade_mcp/domain_hint.py` | `1977670f39a0b3b2db37842d25e985f06d15296814cfb8daa0f725798138dba4` | ✓ | | `~/src/syncthing-blade-mcp/src/syncthing_mcp/formatters.py` | `2ea00ebdb6da2577cfcd8c616e7560a914dd6d79f720a00d848612b49d0a79f8` | ✓ | ## API divergences from sources (architect-spec'd) - **`compute_domain_hint(record, patterns)`** — gmail's reference takes a third `field_projector` callable. The spec lifts this to a generic public API by dropping the projector and using built-in dot-path navigation (`labels.priority` reads `record["labels"]["priority"]`). All gmail-specific projector behaviour for nested lists / scalar-coercion preserved. - **`meta_envelope(...)`** — syncthing's reference omitted `next_cursor` + `error_notes` fields and used kwarg shape `latency_ms` positioned after `redactions`. Spec adopts the canonical wire-contract shape with `next_cursor` ALWAYS-present (JSON `null` default) and `error_notes` per DEVFU `2026-05-23-granularity-doc-optional-envelope-fields`. - **`append_meta(body, meta_line)`** — syncthing's reference was a fat helper accepting full `meta_envelope` kwargs and constructing both. Spec collapses to a simple 2-arg joiner; callers compose `meta_envelope(...)` separately. ## Test plan - [x] `uv sync --group dev` clean - [x] `uv run pytest tests/ -v` → 52 passed - [x] `uv run pytest tests/ --cov=src/stallari_mcp_helpers --cov-report=term-missing --cov-branch` → 100% line + branch on `domain_hint.py` and `audit_envelope.py` - [x] `uv run ruff check src/ tests/` clean - [x] `uv run ruff format --check src/ tests/` clean - [x] `uv run mypy src/stallari_mcp_helpers` clean (strict) - [x] `uv build` produces sdist + wheel - [x] Single commit on branch; Convention #17 trailer; SSH-signed - [ ] Architect post-merge: tag `v0.1.0` + PyPI publish (out of scope for this PR) ## References - Spec: `~/master-ai/atlas/utilities/agent-harness/specs/2026-05-24-dd-338-e-python-mcp-helpers-package.md` - Decision record: DD-338 § "Substrate correction 2026-05-24" + DD-338 Phase E.python amendment 🤖 Generated with [Claude Code](https://claude.com/claude-code)