instantly-mcp 0.1.0__tar.gz

instantly_mcp-0.1.0/.dockerignore

@@ -0,0 +1,8 @@
+.venv/
+.git/
+.pytest_cache/
+__pycache__/
+*.pyc
+.env
+audit.log
+tests/

instantly_mcp-0.1.0/.env.example

@@ -0,0 +1,58 @@
+# Copy to .env and fill in. .env is gitignored; never commit real values.
+# Full reference (defaults + behavior) in docs/configuration.md.
+
+# --- Required ---------------------------------------------------------------
+# Your Instantly v2 API key (a scoped Bearer token).
+# Generate it in Instantly -> Settings -> Integrations -> API.
+# Tip: start with a READ-ONLY scoped key to try analytics safely, then widen.
+INSTANTLY_API_KEY=
+
+# --- Optional: base URL / transport ----------------------------------------
+# Override only if Instantly changes their host. Default shown.
+# INSTANTLY_BASE_URL=https://api.instantly.ai/api/v2
+
+# Transport for the MCP server. Default "stdio" (local, launched by the client).
+# Switch to "streamable-http" or "sse" when hosting (see docs/hosting.md).
+# TRANSPORT=stdio
+# HOST=0.0.0.0
+# PORT=8000
+
+# --- Required WHEN HOSTED (TRANSPORT != stdio) ------------------------------
+# Over stdio the only caller is a local process, so these are unused. Over HTTP
+# every tool is exposed to anyone who can reach the URL, so the server REFUSES
+# TO START without them. Note AUTONOMY_LEVEL is not a defence here: `confirm`
+# is supplied by the caller, so an anonymous caller just sets it to true.
+#
+# Shared bearer token Claude must present. Min 32 chars. Generate with:
+#   python -c "import secrets; print(secrets.token_urlsafe(32))"
+# This value doubles as the passphrase on the /login page during the OAuth
+# connect flow -- there is no separate password. See docs/hosting.md.
+# MCP_AUTH_TOKEN=
+#
+# The public https:// URL Claude connects to. Must be https (a bearer token over
+# plain http is sent in clear text); http://127.0.0.1 is allowed for local tests.
+# PUBLIC_URL=https://your-app.example.com
+#
+# Hosts accepted as OAuth callbacks, comma separated. Only change this if your
+# client redirects from a domain not in the default list -- a rejected
+# registration surfaces as "invalid_redirect_uri" at connect time.
+# OAUTH_REDIRECT_HOSTS=claude.ai,claude.com,anthropic.com
+
+# --- Optional: autonomy policy ---------------------------------------------
+# manual (default) | assisted | autonomous   -- see docs/autonomy.md.
+# AUTONOMY_LEVEL=manual
+
+# Volume caps (enforced in code). Exceeding a cap forces a confirm preview
+# even in autonomous mode.
+# INSTANTLY_MAX_LEADS_PER_CALL=1000
+# INSTANTLY_MAX_LEADS_PER_DAY=5000
+# INSTANTLY_MAX_EMAILS_PER_DAY=50
+# INSTANTLY_MAX_CAMPAIGNS_PER_CALL=1
+
+# Optional allow/deny lists (comma-separated campaign UUIDs). If an allowlist
+# is set, autonomous actions may only touch those campaigns.
+# INSTANTLY_CAMPAIGN_ALLOWLIST=
+# INSTANTLY_CAMPAIGN_DENYLIST=
+
+# Where to append the audit log of executed writes. Default ./audit.log
+# INSTANTLY_AUDIT_LOG=audit.log

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

@@ -0,0 +1,91 @@
+name: Bug report
+description: A tool misbehaved, or a safety gate didn't do what the docs say it does.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. If a write executed **without** `confirm=true`
+        and without the autonomy policy explicitly permitting it, or a
+        hard-blocked tool (`delete_lead`, `delete_webhook`, `pause_account`,
+        `remove_from_blocklist`) ran autonomously, please report that
+        [privately as a security
+        issue](https://github.com/katekruger/instantly-mcp/security/advisories/new)
+        instead — that is the exact failure mode this project exists to
+        prevent.
+
+  - type: input
+    id: tool
+    attributes:
+      label: Tool name
+      description: The MCP tool involved, e.g. `add_leads`, `pause_campaign`.
+      placeholder: add_leads
+    validations:
+      required: true
+
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: What the tool did or returned.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: >
+        The tool call and arguments that trigger it. **Replace real API keys,
+        campaign IDs, and lead emails with placeholders before pasting** —
+        `example.com` addresses and `camp-xxxx` style IDs are fine.
+      render: json
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Package version (`pip show instantly-mcp`) or commit SHA.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport
+      options:
+        - stdio (local)
+        - streamable-http (hosted)
+        - sse (hosted)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: autonomy_level
+    attributes:
+      label: AUTONOMY_LEVEL
+      options:
+        - manual (default)
+        - assisted
+        - autonomous
+        - not sure
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: confirmations
+    attributes:
+      label: Before submitting
+      options:
+        - label: I have removed any real API keys, tokens, and lead contact data from this report.
+          required: true
+        - label: I checked docs/autonomy.md to confirm the behavior I'm reporting isn't documented as intended.

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

@@ -0,0 +1,11 @@
+# Discussions is not enabled on this repo, so "blank" issues stay open for
+# questions and ideas that don't fit the bug/feature forms below, rather than
+# linking to a tab that doesn't exist.
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/katekruger/instantly-mcp/security/advisories/new
+    about: >
+      Do not open a public issue. A safety gate that let a write through it
+      should have blocked — the confirm gate, an autonomy cap, or the
+      hard-block list — counts as a security issue; report it here.

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

@@ -0,0 +1,29 @@
+name: Feature request
+description: A new tool, an endpoint not yet covered, or a change to the autonomy policy.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do
+      description: The workflow this would unblock, not just the feature itself.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed tool or change
+      description: >
+        If this is a new tool, what tier should it be (READ / LOW_WRITE /
+        HIGH_WRITE) and why? If it's irreversible or high blast radius, should
+        it go in HARD_BLOCK? See CONTRIBUTING.md for what a new write tool
+        needs to wire up.
+    validations:
+      required: true
+
+  - type: textarea
+    id: api
+    attributes:
+      label: Instantly v2 API endpoint(s) involved, if known
+      description: Link to https://developer.instantly.ai/ if you have it handy.

instantly_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+
+updates:
+  # No lockfile is committed (README supports both uv and venv+pip), so
+  # Dependabot reads dependency ranges straight from pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+    labels: ["dependencies"]
+    groups:
+      dev-tooling:
+        patterns: ["pytest*", "ruff"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+    commit-message:
+      prefix: "ci"
+    labels: ["dependencies", "github-actions"]
+    groups:
+      actions:
+        patterns: ["*"]

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

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: lint, types, tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check src tests
+
+      # ruff format --check is deliberately not run: this codebase predates
+      # a formatter pass and has never been through one. Adopting it means
+      # reformatting every file in one pass, which is its own reviewed
+      # change, not a side effect of adding CI.
+      - name: Pyright
+        run: pyright
+
+      # No secrets: the suite is fully mocked and must never reach the live API.
+      - name: Test
+        run: pytest -q --cov=src/instantly_mcp --cov-report=term-missing
+
+      # policy.py is the safety module every write-gating claim in the README
+      # rests on. Gate it at a real floor so a regression there fails CI
+      # specifically, even before the whole-project number earns a threshold
+      # (see the comment in pyproject.toml's [tool.coverage.report]).
+      - name: Coverage floor for the safety module (policy.py)
+        run: coverage report --include='*/instantly_mcp/policy.py' --fail-under=95

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

@@ -0,0 +1,141 @@
+name: Release
+
+# Tag-triggered, on the segment-mcp/deliverability-guard 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.
+#
+# No MCP Registry job here (segment-mcp has one). This server is deliberately
+# staying local-stdio-only for now -- see docs/hosting.md and CHANGELOG.md --
+# so there is no hosted remote to register, and this repo's own choice has
+# been to not pursue that discoverability yet. PyPI publication is a
+# different, lower-exposure kind of distribution: it ships the same local
+# stdio install the README already documents, just via `pip install
+# instantly-mcp` instead of a git clone, with no public URL, no bearer
+# token, and no secret sitting in a third-party host.
+#
+# 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.
+
+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: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - run: python -m pip install --upgrade pip hatch
+
+      - name: Verify tag matches package version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(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/instantly_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="$(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: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: python -m pip install --upgrade pip build && python -m 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/instantly-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/instantly_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

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

@@ -0,0 +1,39 @@
+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: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Run zizmor
+        run: pipx run zizmor --format sarif . > results.sarif
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload SARIF file
+        # Code scanning confirmed enabled: run 33411592691 (2026-08-31)
+        # uploaded successfully on the first real push, so this no longer
+        # needs the continue-on-error segment-mcp's zizmor.yml carried
+        # through its own private-to-public transition.
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          sarif_file: results.sarif
+          category: zizmor

instantly_mcp-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Secrets & audit trail (audit.log may contain lead emails)
+.env
+audit.log
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+deploy-token.txt