teams-transcripts 0.5.0__tar.gz → 0.5.2__tar.gz

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/.gitignore

@@ -2,6 +2,7 @@ __pycache__
 .claude
 .git
 .ruff_cache
+.uv-cache
 .venv
 .opencode
 

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/.gitlab-ci.yml

@@ -1,17 +1,14 @@
 stages:
   - verify
   - package
+  - publish
+
+variables:
+  UV_CACHE_DIR: "/tmp/uv-cache"
 
 default:
   image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
-  variables:
-    UV_CACHE_DIR: "$CI_PROJECT_DIR/.uv-cache"
-  cache:
-    key:
-      files:
-        - uv.lock
-    paths:
-      - .uv-cache/
+
 verify:
   stage: verify
   parallel:
@@ -43,3 +40,18 @@ package:
   artifacts:
     paths:
       - dist/
+
+publish:
+  stage: publish
+  dependencies:
+    - package
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  environment:
+    name: pypi
+  resource_group: pypi
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+([a-zA-Z0-9.-]+)?$/'
+  script:
+    - uv publish --trusted-publishing always dist/*

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teams-transcripts
-Version: 0.5.0
+Version: 0.5.2
 Summary: Download Microsoft Teams transcripts, chat, and meeting metadata from the macOS desktop app
 Project-URL: Homepage, https://gitlab.com/jamiemills-choreograph/teams-transcripts
 Project-URL: Repository, https://gitlab.com/jamiemills-choreograph/teams-transcripts
@@ -49,13 +49,20 @@ uvx teams-transcripts \
   --gcp-project your-project
 ```
 
-To run one of the package's differently named commands, specify the package:
+The MCP server has a different executable name from the PyPI package, so use
+`--from` to tell `uvx` which package provides it:
 
 ```sh
-uvx --from teams-transcripts teams-transcripts-mcp
+uvx --from 'teams-transcripts==0.5.2' teams-transcripts-mcp
 uvx --from teams-transcripts transcript-download --help
 ```
 
+Use `teams-transcripts==0.5.2` for a reproducible MCP configuration, or replace
+it with `teams-transcripts` to follow the latest release. Do not run
+`uvx teams-transcripts-mcp`: that asks PyPI for a package named
+`teams-transcripts-mcp`, rather than running the executable supplied by this
+package.
+
 `uvx` creates an isolated temporary environment. The Teams desktop app, CDP,
 and authentication prerequisites below still apply.
 
@@ -171,8 +178,12 @@ file.
 
 ### 3. Python dependencies
 
-The script requires Python 3.10+ and is managed with
-[uv](https://docs.astral.sh/uv/). To install all dependencies:
+The package requires Python 3.10+ and is managed with
+[uv](https://docs.astral.sh/uv/). When using `uvx`, dependencies are installed
+automatically in an isolated environment; no project checkout or `uv sync` is
+needed.
+
+For development from a source checkout, install the locked dependencies:
 
 ```sh
 uv sync --locked
@@ -631,6 +642,22 @@ tools directly.
 
 ### Running the MCP server
 
+From PyPI, with no repository checkout or persistent installation:
+
+```sh
+# Pinned release (recommended for MCP client configuration)
+uvx --from 'teams-transcripts==0.5.2' teams-transcripts-mcp
+
+# Latest release
+uvx --from teams-transcripts teams-transcripts-mcp
+```
+
+STDIO is the default transport. When run manually, the command waits quietly
+for MCP messages on standard input; normally an MCP client starts and manages
+this process for you.
+
+If the package is already installed, run the entry point directly:
+
 ```sh
 # STDIO transport (default, for subprocess spawning by MCP clients)
 teams-transcripts-mcp
@@ -658,8 +685,10 @@ MCP transport for local subprocess spawning).  When `--port` is specified,
 the server runs as an SSE HTTP server on that port, accessible over the
 network.
 
-The server inherits environment variables for GCP configuration
-(see [Environment variables](#environment-variables)).
+The server inherits environment variables for GCP configuration, including
+`GOOGLE_CLOUD_PROJECT` and the optional `CLOUD_ML_REGION`, `MODEL_ID`,
+`GOOGLE_ADC`, and `TEAMS_TENANT` settings (see
+[Environment variables](#environment-variables)).
 
 ### Available tools
 
@@ -712,9 +741,43 @@ Or for a known meeting:
 1. download(meeting="Weekly Standup", date="2026-04-29")
 ```
 
-### Configuration for Claude Desktop
+### MCP client configuration with uvx
 
-Add to your `claude_desktop_config.json`:
+Use `uvx` as the MCP command and pass the package plus its MCP executable as
+arguments. This works with clients that accept the standard JSON MCP server
+configuration format, including Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "teams-transcripts": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "teams-transcripts==0.5.2",
+        "teams-transcripts-mcp"
+      ],
+      "env": {
+        "GOOGLE_CLOUD_PROJECT": "your-gcp-project"
+      }
+    }
+  }
+}
+```
+
+For Claude Desktop, add that entry to `claude_desktop_config.json` and restart
+Claude Desktop. Other MCP clients use the same command and arguments in their
+local-server configuration. Add any optional environment variables your setup
+needs to the `env` object. The MCP process must run as the same macOS user as
+Teams so it can connect to the desktop app and use that user's credentials.
+
+To track the newest PyPI release instead of pinning one, change the package
+argument from `teams-transcripts==0.5.2` to `teams-transcripts`.
+
+### Configuration from an installed checkout
+
+If the project is already installed in a virtual environment, point the MCP
+client at its entry point:
 
 ```json
 {
@@ -729,7 +792,8 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-Or using `uv run`:
+For a source checkout managed by `uv`, configure the client to run in the
+repository directory:
 
 ```json
 {
@@ -1370,6 +1434,41 @@ uv add <package>
 
 This updates both `pyproject.toml` and `uv.lock`.
 
+### Publishing a release
+
+Version tags publish the verified wheel and source distribution to PyPI through
+GitLab CI/CD. The `publish` job runs only for tags such as `v0.6.0`, only after
+both verification jobs and the package job succeed, and uses PyPI Trusted
+Publishing with a short-lived GitLab OIDC token. No PyPI password or API token
+is stored in GitLab.
+
+Before the first automated release, add a GitLab CI/CD trusted publisher under
+the PyPI project's **Manage > Publishing** settings with these values:
+
+| Setting | Value |
+|---------|-------|
+| Namespace | `jamiemills-choreograph` |
+| Project | `teams-transcripts` |
+| Top-level pipeline file | `.gitlab-ci.yml` |
+| Environment | `pypi` |
+
+To release a new version:
+
+```sh
+uv version 0.6.0 --no-sync
+git add pyproject.toml uv.lock
+git commit -m "Prepare 0.6.0 release"
+git push origin main
+
+# After the main pipeline succeeds:
+git tag -a v0.6.0 -m "teams-transcripts 0.6.0"
+git push origin v0.6.0
+```
+
+The package job verifies that the tag exactly matches the built package version
+before publishing. PyPI releases are immutable, so never move or reuse a
+version tag; increment the project version and create a new tag instead.
+
 ### Running tests
 
 ```sh

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/README.md

@@ -20,13 +20,20 @@ uvx teams-transcripts \
   --gcp-project your-project
 ```
 
-To run one of the package's differently named commands, specify the package:
+The MCP server has a different executable name from the PyPI package, so use
+`--from` to tell `uvx` which package provides it:
 
 ```sh
-uvx --from teams-transcripts teams-transcripts-mcp
+uvx --from 'teams-transcripts==0.5.2' teams-transcripts-mcp
 uvx --from teams-transcripts transcript-download --help
 ```
 
+Use `teams-transcripts==0.5.2` for a reproducible MCP configuration, or replace
+it with `teams-transcripts` to follow the latest release. Do not run
+`uvx teams-transcripts-mcp`: that asks PyPI for a package named
+`teams-transcripts-mcp`, rather than running the executable supplied by this
+package.
+
 `uvx` creates an isolated temporary environment. The Teams desktop app, CDP,
 and authentication prerequisites below still apply.
 
@@ -142,8 +149,12 @@ file.
 
 ### 3. Python dependencies
 
-The script requires Python 3.10+ and is managed with
-[uv](https://docs.astral.sh/uv/). To install all dependencies:
+The package requires Python 3.10+ and is managed with
+[uv](https://docs.astral.sh/uv/). When using `uvx`, dependencies are installed
+automatically in an isolated environment; no project checkout or `uv sync` is
+needed.
+
+For development from a source checkout, install the locked dependencies:
 
 ```sh
 uv sync --locked
@@ -602,6 +613,22 @@ tools directly.
 
 ### Running the MCP server
 
+From PyPI, with no repository checkout or persistent installation:
+
+```sh
+# Pinned release (recommended for MCP client configuration)
+uvx --from 'teams-transcripts==0.5.2' teams-transcripts-mcp
+
+# Latest release
+uvx --from teams-transcripts teams-transcripts-mcp
+```
+
+STDIO is the default transport. When run manually, the command waits quietly
+for MCP messages on standard input; normally an MCP client starts and manages
+this process for you.
+
+If the package is already installed, run the entry point directly:
+
 ```sh
 # STDIO transport (default, for subprocess spawning by MCP clients)
 teams-transcripts-mcp
@@ -629,8 +656,10 @@ MCP transport for local subprocess spawning).  When `--port` is specified,
 the server runs as an SSE HTTP server on that port, accessible over the
 network.
 
-The server inherits environment variables for GCP configuration
-(see [Environment variables](#environment-variables)).
+The server inherits environment variables for GCP configuration, including
+`GOOGLE_CLOUD_PROJECT` and the optional `CLOUD_ML_REGION`, `MODEL_ID`,
+`GOOGLE_ADC`, and `TEAMS_TENANT` settings (see
+[Environment variables](#environment-variables)).
 
 ### Available tools
 
@@ -683,9 +712,43 @@ Or for a known meeting:
 1. download(meeting="Weekly Standup", date="2026-04-29")
 ```
 
-### Configuration for Claude Desktop
+### MCP client configuration with uvx
 
-Add to your `claude_desktop_config.json`:
+Use `uvx` as the MCP command and pass the package plus its MCP executable as
+arguments. This works with clients that accept the standard JSON MCP server
+configuration format, including Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "teams-transcripts": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "teams-transcripts==0.5.2",
+        "teams-transcripts-mcp"
+      ],
+      "env": {
+        "GOOGLE_CLOUD_PROJECT": "your-gcp-project"
+      }
+    }
+  }
+}
+```
+
+For Claude Desktop, add that entry to `claude_desktop_config.json` and restart
+Claude Desktop. Other MCP clients use the same command and arguments in their
+local-server configuration. Add any optional environment variables your setup
+needs to the `env` object. The MCP process must run as the same macOS user as
+Teams so it can connect to the desktop app and use that user's credentials.
+
+To track the newest PyPI release instead of pinning one, change the package
+argument from `teams-transcripts==0.5.2` to `teams-transcripts`.
+
+### Configuration from an installed checkout
+
+If the project is already installed in a virtual environment, point the MCP
+client at its entry point:
 
 ```json
 {
@@ -700,7 +763,8 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-Or using `uv run`:
+For a source checkout managed by `uv`, configure the client to run in the
+repository directory:
 
 ```json
 {
@@ -1341,6 +1405,41 @@ uv add <package>
 
 This updates both `pyproject.toml` and `uv.lock`.
 
+### Publishing a release
+
+Version tags publish the verified wheel and source distribution to PyPI through
+GitLab CI/CD. The `publish` job runs only for tags such as `v0.6.0`, only after
+both verification jobs and the package job succeed, and uses PyPI Trusted
+Publishing with a short-lived GitLab OIDC token. No PyPI password or API token
+is stored in GitLab.
+
+Before the first automated release, add a GitLab CI/CD trusted publisher under
+the PyPI project's **Manage > Publishing** settings with these values:
+
+| Setting | Value |
+|---------|-------|
+| Namespace | `jamiemills-choreograph` |
+| Project | `teams-transcripts` |
+| Top-level pipeline file | `.gitlab-ci.yml` |
+| Environment | `pypi` |
+
+To release a new version:
+
+```sh
+uv version 0.6.0 --no-sync
+git add pyproject.toml uv.lock
+git commit -m "Prepare 0.6.0 release"
+git push origin main
+
+# After the main pipeline succeeds:
+git tag -a v0.6.0 -m "teams-transcripts 0.6.0"
+git push origin v0.6.0
+```
+
+The package job verifies that the tag exactly matches the built package version
+before publishing. PyPI releases are immutable, so never move or reuse a
+version tag; increment the project version and create a new tag instead.
+
 ### Running tests
 
 ```sh

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "teams-transcripts"
-version = "0.5.0"
+version = "0.5.2"
 description = "Download Microsoft Teams transcripts, chat, and meeting metadata from the macOS desktop app"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,6 +34,13 @@ Issues = "https://gitlab.com/jamiemills-choreograph/teams-transcripts/-/issues"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build]
+exclude = [
+    "/.uv-cache",
+    "/.venv",
+    "/dist",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["legacy", "teams_transcripts"]
 

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/scripts/verify_distribution.py

@@ -10,6 +10,7 @@ import zipfile
 from email.parser import Parser
 
 EXPECTED_PACKAGES = ("legacy/", "teams_transcripts/")
+EXCLUDED_SDIST_PATHS = ("/.uv-cache/", "/.venv/", "/dist/")
 EXPECTED_SCRIPTS = {
     "teams-transcripts = teams_transcripts.__main__:main",
     "teams-transcripts-mcp = teams_transcripts.mcp_server:main",
@@ -51,6 +52,9 @@ def _verify_sdist(path: pathlib.Path) -> None:
     for package in EXPECTED_PACKAGES:
         if not any(f"/{package}" in name for name in names):
             raise SystemExit(f"{path.name} does not contain {package}")
+    for excluded in EXCLUDED_SDIST_PATHS:
+        if any(excluded in f"/{name}/" for name in names):
+            raise SystemExit(f"{path.name} unexpectedly contains {excluded.strip('/')}")
 
 
 def main() -> None:

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/teams_transcripts/infrastructure/config.py

@@ -94,9 +94,10 @@ def parse_args() -> argparse.Namespace:
             "       gcloud auth application-default login\n"
             "     Or point --adc / GOOGLE_ADC at a service account key file.\n"
             "\n"
-            "  3. Python dependencies (websockets, anthropic[vertex], mcp) are managed\n"
-            "     by uv.  Run 'uv sync' to install from the lockfile.  After setup,\n"
-            "     use ./bin/teams-transcripts (or 'uv run teams-transcripts') to run.\n"
+            "  3. Python 3.10+ and uv are required.  uvx installs dependencies in an\n"
+            "     isolated environment automatically; no checkout or uv sync is needed.\n"
+            "     For a source checkout, run 'uv sync --locked', then use\n"
+            "     'uv run teams-transcripts'.\n"
             "\n"
             "environment variables (used as fallbacks when CLI flags are omitted):\n"
             "  GOOGLE_CLOUD_PROJECT  GCP project ID for Vertex AI (required if\n"
@@ -425,7 +426,13 @@ def parse_args() -> argparse.Namespace:
             "\n"
             "mcp server:\n"
             "  An MCP (Model Context Protocol) server is available for tool-use by\n"
-            "  AI agents.  Start with: teams-transcripts-mcp\n"
+            "  AI agents.  Run from PyPI without installing:\n"
+            "    uvx --from teams-transcripts teams-transcripts-mcp\n"
+            "  For a reproducible client config, pin the package version:\n"
+            "    uvx --from 'teams-transcripts==VERSION' teams-transcripts-mcp\n"
+            "  MCP client command: uvx\n"
+            "  MCP client args: --from teams-transcripts teams-transcripts-mcp\n"
+            "  If installed locally, start with: teams-transcripts-mcp\n"
             "  Or on a network port: teams-transcripts-mcp --port 8080\n"
             "  Recommended tool: download(meeting_id=UUID) -- the unified entry point.\n"
             "  Also available: restart_teams, list_tenants, list_transcripts,\n"
@@ -434,6 +441,7 @@ def parse_args() -> argparse.Namespace:
             "  AI agents should prefer MCP tools over direct CLI invocation.\n"
             "  STDIO transport (default) for subprocess spawning by MCP clients.\n"
             "  SSE transport (--port) for network access.\n"
+            "  The server inherits GOOGLE_CLOUD_PROJECT and other documented env vars.\n"
         ),
     )
     p.add_argument(

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/teams_transcripts/mcp_server.py

@@ -795,7 +795,24 @@ def main() -> None:
     import argparse
 
     p = argparse.ArgumentParser(
-        description="Teams Transcripts MCP server",
+        description=(
+            "Teams Transcripts MCP server. Uses STDIO by default so an MCP "
+            "client can start and manage it as a local subprocess."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""Run directly from PyPI without installing:
+  uvx --from teams-transcripts teams-transcripts-mcp
+
+Pin a release for a reproducible MCP client configuration:
+  uvx --from 'teams-transcripts==VERSION' teams-transcripts-mcp
+
+MCP client configuration:
+  command: uvx
+  args: --from teams-transcripts teams-transcripts-mcp
+
+The server inherits GOOGLE_CLOUD_PROJECT and the other environment variables
+documented in the project README. Do not use `uvx teams-transcripts-mcp`;
+the PyPI package name is `teams-transcripts`.""",
     )
     p.add_argument(
         "--port",

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/tests/test_component_flags.py

@@ -9,6 +9,7 @@ Covers:
 from __future__ import annotations
 
 import argparse
+from datetime import datetime, timedelta
 
 import pytest
 
@@ -20,6 +21,7 @@ from teams_transcripts.domain.models import (
     TranscriptCue,
 )
 from teams_transcripts.domain.summary import build_result_summary
+from teams_transcripts.domain.timestamps import parse_meeting_times
 from teams_transcripts.infrastructure.config import resolve_config
 
 # ---------------------------------------------------------------------------
@@ -331,11 +333,16 @@ class TestComposableJsonOutput:
 
     def test_chat_message_has_offset(self) -> None:
         """Chat messages in JSON include offset from meeting start."""
+        meeting_time_text = "22 April 2026 11:00 -  12:00"
+        meeting_start, _ = parse_meeting_times(meeting_time_text, "2026-04-22")
+        message_timestamp = (
+            datetime.fromisoformat(meeting_start) + timedelta(minutes=15)
+        ).isoformat()
         messages = [
-            ChatMessage(timestamp="2026-04-22T11:15:00+01:00", author="Bob", text="Hi"),
+            ChatMessage(timestamp=message_timestamp, author="Bob", text="Hi"),
         ]
         result = build_result_summary(
-            _base_config(meeting_time_text="22 April 2026 11:00 -  12:00"),
+            _base_config(meeting_time_text=meeting_time_text),
             chat_messages=messages,
             chat_count=1,
             include_transcript=False,

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/tests/test_infrastructure_config.py

@@ -18,6 +18,23 @@ from pydantic import ValidationError
 from teams_transcripts.domain.models import MeetingConfig
 from teams_transcripts.infrastructure.config import parse_args, resolve_config
 
+
+def test_main_help_documents_uvx_mcp_configuration(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr("sys.argv", ["teams-transcripts", "--help"])
+
+    with pytest.raises(SystemExit) as exc_info:
+        parse_args()
+
+    assert exc_info.value.code == 0
+    help_text = capsys.readouterr().out
+    assert "uvx --from teams-transcripts teams-transcripts-mcp" in help_text
+    assert "MCP client command: uvx" in help_text
+    assert "teams-transcripts==VERSION" in help_text
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/tests/test_mcp_server.py

@@ -25,6 +25,7 @@ from teams_transcripts.mcp_server import (
     _run_cli,
     _run_cli_list,
     download,
+    main,
     mcp,
 )
 
@@ -33,6 +34,23 @@ from teams_transcripts.mcp_server import (
 # ---------------------------------------------------------------------------
 
 
+def test_mcp_help_documents_uvx_configuration(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr("sys.argv", ["teams-transcripts-mcp", "--help"])
+
+    with pytest.raises(SystemExit) as exc_info:
+        main()
+
+    assert exc_info.value.code == 0
+    help_text = capsys.readouterr().out
+    assert "uvx --from teams-transcripts teams-transcripts-mcp" in help_text
+    assert "teams-transcripts==VERSION" in help_text
+    assert "GOOGLE_CLOUD_PROJECT" in help_text
+    assert "STDIO" in help_text
+
+
 class TestToolDiscovery:
     """Verify all MCP tools are registered with correct metadata."""
 

{teams_transcripts-0.5.0 → teams_transcripts-0.5.2}/uv.lock

@@ -1156,7 +1156,7 @@ wheels = [
 
 [[package]]
 name = "teams-transcripts"
-version = "0.5.0"
+version = "0.5.2"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic", extra = ["vertex"] },