handoff-mcp 0.3.0__tar.gz

handoff_mcp-0.3.0/.gitattributes

@@ -0,0 +1,12 @@
+# Normalise line endings: LF in the repo for all text, regardless of OS.
+* text=auto eol=lf
+
+*.py   text eol=lf
+*.md   text eol=lf
+*.toml text eol=lf
+*.yml  text eol=lf
+*.txt  text eol=lf
+
+# Binary
+*.gif  binary
+*.png  binary

handoff_mcp-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: py${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          # Smoke-test the markdown/path handling on Windows too.
+          - os: windows-latest
+            python-version: "3.12"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Check the lockfile is in sync with pyproject.toml
+        run: uv lock --check
+
+      - name: Install project into a venv
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev]"
+
+      - name: Ruff (lint + format check)
+        run: |
+          uv run --no-sync ruff check .
+          uv run --no-sync ruff format --check .
+
+      - name: Mypy (strict)
+        run: uv run --no-sync mypy
+
+      - name: Pytest
+        run: uv run --no-sync pytest
+
+      - name: Benchmark smoke run
+        run: |
+          uv run --no-sync python benchmarks/brief_reconstruction.py
+          uv run --no-sync python benchmarks/supersession_benchmark.py
+
+  tool-surface:
+    name: MCP tool-surface smoke gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install project into a venv
+        run: |
+          uv venv --python 3.12
+          uv pip install -e .
+
+      # Drive the real MCP JSON-RPC surface through the Inspector and assert the
+      # schemas + annotations clients depend on. Inspector is pinned so this gate
+      # tracks *our* contract, not upstream churn. tools/list needs no provider —
+      # just a writable vault dir (the server's ensure_dirs() creates it).
+      - name: Assert tool schemas + annotations (MCP Inspector)
+        env:
+          HANDOFF_VAULT: ${{ runner.temp }}/handoff-vault
+        run: |
+          npx --yes @modelcontextprotocol/inspector@0.22.0 --cli \
+            uv run --no-sync handoff-mcp --method tools/list \
+            | python scripts/check_tool_surface.py

handoff_mcp-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+# Tag-driven PyPI release via trusted publishing (no API tokens):
+# push a `vX.Y.Z` tag and the matching version is built and published.
+# Requires the "pypi" trusted publisher to be configured for this repo on
+# https://pypi.org/manage/account/publishing/ (environment: pypi).
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Check the tag matches the package version
+        run: |
+          version=$(uvx --from toml-cli toml get --toml-path pyproject.toml project.version)
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "Tag v$tag does not match pyproject version $version" >&2
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/handoff-mcp
+    permissions:
+      id-token: write # OIDC token for PyPI trusted publishing
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

handoff_mcp-0.3.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenv / uv
+.venv/
+.venv*/
+# uv.lock IS committed: CI runs `uv lock --check` and the package is published to
+# PyPI, so the resolved lockfile belongs in the repo for reproducible builds.
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local vault / derived index (runtime data, never source of truth in repo)
+*.handoff-vault/
+*.db
+*.db-shm
+*.db-wal
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

handoff_mcp-0.3.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.3.0] — 2026-07-07
+
+### Added
+- **Multi-device sync** (`sync` tool + `handoff-sync` CLI) — a thin, opt-in git
+  layer over the vault: pull, commit, and push a private git remote so memory
+  follows you across machines. `handoff-sync --setup <url>` configures the remote
+  (writing a union-merge `.gitattributes` and gitignoring the derived index); set
+  `HANDOFF_AUTO_SYNC=1` for pull-on-brief / push-on-checkpoint. Core memory stays
+  fully functional with zero git.
+- Entity-note conflicts across machines resolve automatically via git's built-in
+  `union` merge driver — no custom merge engine.
+- **Tool-surface CI smoke gate** (`scripts/check_tool_surface.py`) pinning the MCP
+  tool schemas and read-only/destructive annotations against drift.
+
+### Changed
+- Git subprocesses are bounded by a timeout and refuse interactive credential
+  prompts, so a slow or unauthenticated remote can never block a session.
+
+## [0.2.0] — 2026-07-06
+
+### Added
+- **Memory consolidation** (`consolidate` tool) — opt-in LLM "sleep" pass that
+  distils old finished sessions' active decisions into durable entity notes and
+  archives the originals, to tackle memory *volume* at scale (ADR-0006).
+- **Deterministic reranking** of recall — `search_memory` reorders results by a
+  relevance + recency (time-decay) + importance blend; `rerank=False` for raw
+  order.
+- **Importers** — `handoff-import` CLI bootstraps a project's memory from a git
+  commit history (deterministic) or a Claude Code transcript (best-effort);
+  idempotent re-import.
+- **Pluggable embedding backends** — `hashing` (default, zero-dep), `openai`
+  (OpenAI-compatible incl. a self-hosted proxy), `local` (sentence-transformers, default
+  model `Qwen/Qwen3-Embedding-0.6B`); hybrid keyword+semantic via RRF (ADR-0004).
+- **Incremental, persistent index** — startup syncs only changed session notes
+  by `(mtime, size)` signature, so cost scales with new work, not history
+  (ADR-0005).
+- Benchmarks (offline, deterministic): `brief_reconstruction` (brief vs naive
+  dump) and `supersession_benchmark` (supersession on vs off, in isolation). See
+  `benchmarks/RESULTS.md`.
+- **Supersede-by-best-match** — `log_event(supersedes_query=…)` retires the best-
+  matching active event of the same type when the caller doesn't have its id;
+  deterministic, auditable, opt-in (ADR-0007).
+- **Tool annotations** — every tool now advertises `ToolAnnotations` to the host:
+  `get_brief`/`search_memory` are read-only, `consolidate` is destructive (it
+  archives sessions) and the only open-world tool (it may call an external LLM).
+- `search_memory` results include each event's **id** (feed it straight into
+  `log_event(supersedes=…)` to retire a stale decision you just found) and the
+  tool exposes a `limit` parameter (default 10).
+- **MCP registry manifest** (`server.json`) and a tag-driven **PyPI release
+  workflow** using trusted publishing (`.github/workflows/release.yml`).
+- Python **3.14** support (CI matrix, classifiers).
+
+### Changed
+- Retired the misleading `supersession_benchmark` head-to-head vs mem0 (keyword
+  retrieval masked the mechanism, an empty answer scored as a win, and it wasn't
+  reproducible offline); reframed the benchmarks honestly around the two above
+  (ADR-0008).
+- Pinned the MCP SDK to `mcp>=1.27,<2` — mcp 2.0 is a breaking rewrite
+  (`FastMCP` → `MCPServer`); the v2 migration will be deliberate, not accidental.
+- `log_event(type=…)` and `search_memory(scope=…)` are now `Literal`-typed, so
+  the published schemas are enum-constrained: invalid values (e.g. a `'curent'`
+  typo) are rejected by the protocol layer instead of being silently coerced.
+- `__version__` is sourced from package metadata (`importlib.metadata`) instead
+  of a hardcoded string, and the server no longer pokes the SDK's private
+  `_mcp_server.version` attribute.
+
+### Concurrency
+- The shared SQLite connection (keyword index + semantic store) is now serialised
+  by a reentrant lock, fixing interleaved-statement errors and lost writes when an
+  MCP transport dispatches tool calls from worker threads.
+
+### Security
+- Validate `project` / `session_id` and sanitise entity names to prevent path
+  traversal / arbitrary file writes outside the vault (covered by
+  `tests/test_path_safety.py::test_safe_segment_rejects_traversal` and the
+  engine-level `test_engine_rejects_unsafe_project`, which exercises the
+  actual tool entry point).
+- Strip ASCII control characters (except tab/newlines) from event content and
+  link targets — `\x1f` is the index's packed-list separator and could corrupt
+  the `links` column.
+
+### Fixed
+- Vault round-trip no longer loses or mis-attributes events whose content spans
+  lines or contains `<!-- -->` / lookalike metadata.
+- Cross-project supersession is resolved globally (briefs and search).
+- Hardened SQLite (WAL + busy timeout) for concurrent sessions; atomic note
+  writes; zero-vector handling consistent across the vec0 and brute-force paths.
+- Index timestamps are normalised to UTC before storage: `ORDER BY created_at`
+  compares ISO strings lexicographically, so mixed offsets (e.g. imported git
+  history) could order the brief wrongly. `rebuild` self-heals existing indexes.
+- `consolidate` archives sessions **before** appending distilled facts, so a
+  crash between the two steps can no longer duplicate every fact on the next
+  run (it merely loses regenerable facts — the sessions stay archived, intact).
+
+## [0.1.0] — 2026-06-29
+
+### Added
+- Initial release: FastMCP server with `log_event`, `get_brief`, `search_memory`,
+  `checkpoint`, `note_entity`; `session://brief` resource and `resume` prompt.
+- Markdown vault as the source of truth with a derived SQLite + FTS5 index.
+- Temporal supersession (retracted decisions excluded from briefs and recall).
+- Deterministic, token-budgeted, graph-aware hand-off brief.
+- Cross-project memory: project-scoped briefs, global `search_memory`.
+- ADRs, architecture docs, two-session demo, and a Claude Code skill.

handoff_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solrange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.