segment-mcp 0.1.0__tar.gz

segment_mcp-0.1.0/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

segment_mcp-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# Public API token. Only a Workspace Owner can mint one:
+# Segment App -> Workspace Settings -> Access Management -> Tokens ->
+# Create Token -> Public API (not Config API). Requires Team or Business
+# tier — the Public API is not available on Free or Add-on plans.
+SEGMENT_API_TOKEN=
+
+# Workspace region. Changes every base URL. An EU workspace token used
+# against the US base URL fails silently (BUILD-PLAN.md §0.6) — get this
+# right, don't leave it to default.
+SEGMENT_REGION=us
+
+# read (default) | write | admin. Tier 1 (regulation/deletion creation) is
+# unreachable in every mode — see docs/decisions/0002-tier-1-permanently-unreachable.md.
+SEGMENT_MCP_MODE=read
+
+# Separate credential for the Profile API (v0.2+). Distinct trust tier from
+# SEGMENT_API_TOKEN — returns PII on named individuals. Absent = no profile
+# tool is registered at all. See README.md's Profile API section and
+# client/profile_api.py.
+SEGMENT_PROFILE_TOKEN=
+
+# The Unify Space ID the Profile API looks up profiles in — not the same
+# as your workspace ID. Find it in Segment App -> Unify -> Spaces -> (your
+# space) -> Settings. Required only if SEGMENT_PROFILE_TOKEN is set.
+SEGMENT_PROFILE_SPACE_ID=

segment_mcp-0.1.0/.gitattributes

@@ -0,0 +1,8 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

segment_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug report
+description: Something is broken or behaving incorrectly.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including what you expected instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to reproduce
+      description: Minimal steps to reproduce, including your `SEGMENT_MCP_MODE` and `SEGMENT_REGION` (redact your token).
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: segment-mcp version
+      placeholder: e.g. 0.1.0
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: e.g. 3.12.4
+    validations:
+      required: true
+
+  - type: dropdown
+    id: region
+    attributes:
+      label: Workspace region
+      options:
+        - US
+        - EU
+        - Not sure / not applicable
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output / traceback
+      description: This will be rendered as a code block — do not paste your API token or any real Segment workspace data.
+      render: shell
+    validations:
+      required: false

segment_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

segment_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Propose something new — a tool, a composed question, a capability.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: What can't you answer today that this would enable? Prefer a concrete workspace scenario over an abstract capability.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed approach
+      description: If you have one. It's fine to leave this blank and just describe the problem.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked BUILD-PLAN.md to see if this is already scoped for a future version, deferred, or explicitly a non-goal.
+          required: true
+        - label: This is not a request to expose Tier 1 (regulation/deletion creation) — see docs/decisions/0002-tier-1-permanently-unreachable.md. Requests to relax that line will be closed.
+          required: true

segment_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    cooldown:
+      default-days: 7

segment_mcp-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,26 @@
+## What and why
+
+<!-- What does this change, and what problem does it solve? -->
+
+## AI disclosure
+
+<!-- Required. See CONTRIBUTING.md § Use of AI. -->
+
+- AI-assisted: <!-- yes/no -->
+- Model / harness: <!-- e.g. Claude Sonnet 5 via Claude Code -->
+- What was and wasn't AI-generated:
+
+## New dependencies
+
+<!-- One line of justification per new dependency, or "None". -->
+
+## Checklist
+
+- [ ] `uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest` passes locally
+- [ ] `CHANGELOG.md` has an entry under `## Unreleased`
+- [ ] New behavior has a test, or this PR explains why not
+- [ ] An ADR is included if this decision is expensive to reverse
+- [ ] This PR does not add any path — in any mode — that reaches Tier 1 (regulation/deletion creation)
+- [ ] Any new write tool is gated by `SEGMENT_MCP_MODE` and echoes the change back for confirmation before executing
+- [ ] Region is resolved explicitly wherever this change makes an API call
+- [ ] I reviewed the full diff myself before opening this PR

segment_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  # A real Python version matrix. This was a single job while the repo was
+  # private, since Actions minutes are metered there; the repo is public
+  # now, so there's real value in catching a version-specific regression
+  # instead of only ever testing 3.12. See docs/plans/going-public-checklist.md.
+  check:
+    name: lint, format, types, tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Pyright
+        run: uv run pyright
+
+      - name: Pytest
+        run: uv run pytest

segment_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,134 @@
+name: Release
+
+# Tag-triggered, on the parsedmarc pattern: verify the tag matches the
+# package version -> verify CHANGELOG.md has a section for it -> run the
+# full CI suite -> build -> publish to PyPI via Trusted Publishing (OIDC,
+# no API token secret anywhere) into an environment that requires manual
+# approval -> create the GitHub Release from the CHANGELOG section.
+#
+# Set up the PyPI Trusted Publisher BEFORE pushing the first tag -- PyPI
+# needs to already trust this repo/workflow/environment combination, or the
+# publish step has nothing to authenticate against. See
+# docs/plans/going-public-checklist.md.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: verify tag matches version, CHANGELOG has a section
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          # This workflow publishes release artifacts; a cache poisoned by
+          # an earlier run must never be trusted here, so caching is off
+          # for this workflow specifically (unlike ci.yml, which runs far
+          # more often and has more to gain from it).
+          enable-cache: false
+
+      - name: Verify tag matches package version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(uvx hatch version)"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME (version $tag_version) does not match" \
+                 "package version $pkg_version (src/segment_mcp/__init__.py)"
+            exit 1
+          fi
+          echo "OK: tag $GITHUB_REF_NAME matches package version $pkg_version"
+
+      - name: Verify CHANGELOG.md has a section for this version
+        run: |
+          pkg_version="$(uvx hatch version)"
+          if ! grep -qE "^## \[?${pkg_version//./\\.}\]?" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no '## $pkg_version' section"
+            exit 1
+          fi
+          echo "OK: CHANGELOG.md has a section for $pkg_version"
+
+  ci:
+    name: run CI
+    needs: verify
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: build sdist and wheel
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: false # see the same note in the verify job above
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/project/segment-mcp/
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC); no API token anywhere
+      contents: read
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      # PEP 740 attestations are generated and uploaded automatically here
+      # under Trusted Publishing -- no extra configuration -- and show up
+      # as a provenance badge on the PyPI project page.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    name: create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Extract this version's CHANGELOG section
+        run: |
+          pkg_version="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/segment_mcp/__init__.py)"
+          awk -v ver="$pkg_version" '
+            $0 ~ "^## \\[?" ver { found=1; next }
+            found && /^## / { exit }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file release-notes.md

segment_mcp-0.1.0/.github/workflows/zizmor.yml

@@ -0,0 +1,37 @@
+name: zizmor
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  zizmor:
+    name: zizmor GitHub Actions security audit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      actions: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Run zizmor
+        run: uvx zizmor --format sarif . > results.sarif
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload SARIF file
+        # The repo is public now and code scanning (CodeQL default setup)
+        # is on — see docs/plans/going-public-checklist.md — so this no
+        # longer needs the continue-on-error it had while private and
+        # GHAS-gated.
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          sarif_file: results.sarif
+          category: zizmor

segment_mcp-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Secrets — never commit
+.env
+*.sqlite
+*.sqlite3
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.pytype/
+
+# Tooling
+.ruff_cache/
+
+# Editors / OS
+.DS_Store
+.idea/
+*.swp

segment_mcp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+# Fast, local checks only. Types (pyright) and tests (pytest) run in CI, not
+# here — a slow pre-commit gets disabled. See AGENTS.md.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml

segment_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md
+
+## Stop and read this before you write code
+
+This repo has conventions. Violating them wastes a review cycle.
+
+## Commands
+
+- Install: `uv sync`
+- Test: `uv run pytest`
+- Lint: `uv run ruff check . && uv run ruff format --check .`
+- Types: `uv run pyright`
+- All of it: `uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest`
+
+## Layout
+
+- `src/segment_mcp/` — the package. `tests/` mirrors it. Never put tests inside the package.
+- `docs/decisions/` — ADRs (MADR 4). Permanent, numbered, never renumbered.
+- `docs/plans/` — dated design plans. Disposable once executed.
+- `.env.example` — every var the server reads, no values. Copy to `.env` to use.
+
+## Non-negotiable
+
+1. **Never commit directly to `main`.** Branch, commit, open a PR. Even for a typo.
+2. **Tests before implementation.** If you are adding behavior, the failing test comes first.
+3. **No secrets in the repo, ever** — not in tests, not in fixtures, not in examples. Use env vars and `.env.example`.
+4. **Never re-type a file's contents from tool output.** Output can be truncated. Edit in place.
+5. **Every dependency added needs a one-line justification in the PR body.**
+6. **If a decision is expensive to reverse, write an ADR in the same PR.**
+7. **Linter versions are pinned exactly.** Do not float them to fix a failure — fix the code, or bump deliberately in its own PR.
+
+## Project-specific non-negotiables
+
+1. **READ-ONLY IS THE DEFAULT.** `SEGMENT_MCP_MODE` defaults to `read`.
+   Shipping v1 with zero write tools is a FEATURE, not a limitation — it
+   beats everything currently on the market. See BUILD-PLAN.md §2.
+2. **TIER 1 IS PERMANENTLY UNREACHABLE.** `POST /regulations` and
+   `POST /regulations/sources/{id}` permanently destroy user data with no
+   undo. They must not be callable in ANY mode. This is a line, not a v3
+   feature waiting for the right gate. See
+   `docs/decisions/0002-tier-1-permanently-unreachable.md` and
+   `docs/what-this-refuses-to-do.md`. `tests/test_tier1_unreachable.py`
+   must keep passing, deliberately redundantly (modes.py, the client, and
+   tool introspection each refuse it independently) — never simplify that
+   test down to one check.
+3. **`PUT`-replace endpoints (`tracking-plans/{id}/rules`,
+   `sources/{id}/labels`) are not exposed before v0.3, and only then with
+   the full-set-diff requirement in `docs/what-this-refuses-to-do.md`
+   implemented, not skipped as scope creep.**
+4. **NEVER auto-generate tools from the OpenAPI spec.** It would produce
+   ~200 flat tools including every `DELETE`, with no notion of blast
+   radius. Hand-pick and COMPOSE.
+5. **Compose reads into QUESTIONS, not endpoints.** The value is the join.
+   An LLM chaining four endpoint calls per source hits rate limits and
+   loses the thread. See BUILD-PLAN.md §5.
+6. **Resolve region EXPLICITLY on every call. Never default.** An EU
+   workspace hitting the wrong base URL fails silently — no error, data
+   simply never appears or never arrives. See BUILD-PLAN.md §0.6.
+7. **No live API calls in tests.** Recorded fixtures only, under
+   `tests/fixtures/{us,eu}/`.
+8. **The Profile API is a separate trust tier.** Never construct
+   `ProfileAPIClient` implicitly or fall back to `SEGMENT_API_TOKEN` for
+   it. A profile-lookup tool must not be registered when
+   `SEGMENT_PROFILE_TOKEN` is unset, and every lookup must be logged. See
+   `client/profile_api.py` and README.md's Profile API section.
+
+## Before opening a PR
+
+- [ ] The full check command above passes locally
+- [ ] `CHANGELOG.md` has an entry under `## Unreleased`
+- [ ] No new file lacks a test, or the PR says why
+- [ ] The PR body discloses: model, harness, and that it was AI-assisted
+- [ ] You showed the human the full diff and got approval
+
+## What gets rejected
+
+- Direct commits to `main`
+- Reformatting unrelated code
+- New dependencies without justification
+- "Improvements" nobody asked for, bundled into an unrelated PR
+- Removing a test to make CI pass
+- Anything that makes an approval gate optional
+- Any tool call, mode, or code path that can reach Tier 1 (regulation/deletion creation)
+- Live API calls in tests
+- Auto-generated tool surfaces from the OpenAPI spec