tableau-graphql-mcp 0.1.0__tar.gz

tableau_graphql_mcp-0.1.0/.env.example

@@ -0,0 +1,26 @@
+# Copy to .env and fill in, or set these in your MCP client's "env" block.
+# Works with Tableau Server (on-prem) and Tableau Cloud.
+
+# --- Required: your Tableau server ---
+# On-prem:      https://tableau.company.com
+# Tableau Cloud: https://<pod>.online.tableau.com   (pod = the prefix in your browser URL, e.g. 10ax)
+TABLEAU_SERVER=https://10ax.online.tableau.com
+
+# Site content URL (the slug in /#/site/<contentUrl>/...).
+# Empty = the Default site (Tableau Server only). Tableau Cloud always has a site.
+TABLEAU_SITE_CONTENT_URL=
+
+# --- Recommended auth: a Personal Access Token ---
+# Create one under your Tableau account settings. The secret is ONE string, do not split it.
+TABLEAU_PAT_NAME=my-token-name
+TABLEAU_PAT_SECRET=the-full-secret-string
+
+# --- Optional ---
+# TABLEAU_TIMEOUT=60
+# TABLEAU_API_VERSION=3.25          # else auto-detected from /api/serverinfo
+# TABLEAU_METADATA_PATH=/api/metadata/graphql   # else auto-detected (falls back to /relationship-service-war/graphql)
+
+# --- Advanced fallback for SSO tenants where PATs are disabled ---
+# Grab an X-Tableau-Auth token, or the full Cookie header, from an authenticated browser session.
+# TABLEAU_AUTH_TOKEN=
+# TABLEAU_COOKIE=

tableau_graphql_mcp-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything in this repo.
+* @tdries

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

@@ -0,0 +1,62 @@
+name: Bug report
+description: Something isn't working
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report! Please **redact your PAT / auth token** from every field below.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, and what happened instead?
+      placeholder: I asked "..." and the tool returned ...
+    validations:
+      required: true
+  - type: input
+    id: mcp-client
+    attributes:
+      label: MCP client and version
+      placeholder: Claude Desktop 0.x / Claude Code / Cursor / Cline ...
+    validations:
+      required: true
+  - type: dropdown
+    id: tableau-kind
+    attributes:
+      label: Tableau deployment
+      options:
+        - Tableau Server (on-prem)
+        - Tableau Cloud
+    validations:
+      required: true
+  - type: input
+    id: tableau-version
+    attributes:
+      label: Tableau version
+      placeholder: e.g. 2025.1.8
+  - type: dropdown
+    id: auth-mode
+    attributes:
+      label: Auth mode
+      options:
+        - Personal Access Token (PAT)
+        - TABLEAU_AUTH_TOKEN
+        - TABLEAU_COOKIE
+    validations:
+      required: true
+  - type: textarea
+    id: tool-call
+    attributes:
+      label: Exact tool call and error
+      description: The tool name, arguments, and the full error text.
+      render: text
+    validations:
+      required: true
+  - type: checkboxes
+    id: redacted
+    attributes:
+      label: Confirmation
+      options:
+        - label: I redacted my PAT / auth token and any private content from this report
+          required: true

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

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and ideas (Discussions)
+    url: https://github.com/tdries/tableau-graphQL-mcp/discussions
+    about: How do I connect it, which auth, general how-to. Please ask here, not in issues.
+  - name: Security vulnerability
+    url: https://github.com/tdries/tableau-graphQL-mcp/security/policy
+    about: Report privately. Do not open a public issue for security reports.

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

@@ -0,0 +1,22 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: The lineage/metadata question or workflow you can't do today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: A new tool, argument, or behavior. Remember this server is read-only.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

tableau_graphql_mcp-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+<!-- Thanks for contributing! Keep PRs focused and small where possible. -->
+
+## What and why
+
+<!-- What does this change, and why? Link any related issue: Closes #123 -->
+
+## Checklist
+
+- [ ] `uv run pytest` passes (and I added/updated tests for the change)
+- [ ] `uv run ruff check .` and `uv run ruff format --check .` are clean
+- [ ] `uv run mypy` is clean (strict)
+- [ ] No new **runtime** dependency (this project is stdlib + `mcp` only)
+- [ ] The server stays **read-only** (no mutations, no shell, no writes)
+- [ ] README / CHANGELOG updated if behavior or the tool schema changed
+- [ ] If a tool name or argument changed, I updated `tests/tool_contract.json` **on purpose** and noted it in the CHANGELOG (the tool schema is the public API)

tableau_graphql_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

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

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - name: Type-check (mypy --strict)
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        run: uv run mypy
+      - run: uv run pytest -q --cov=tableau_graphql_mcp --cov-report=xml
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

tableau_graphql_mcp-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,27 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "27 4 * * 1"
+
+permissions: {}
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: github/codeql-action/init@02c5e83432fe5497fd85b873b6c9f16a8578e1d9 # v3
+        with:
+          languages: python
+          queries: security-and-quality
+      - uses: github/codeql-action/analyze@02c5e83432fe5497fd85b873b6c9f16a8578e1d9 # v3

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

@@ -0,0 +1,34 @@
+name: Release
+
+# Tag a version (vX.Y.Z) to build and publish to PyPI via Trusted Publishing (OIDC),
+# then cut a GitHub Release with generated notes.
+# Requires a PyPI project + a configured trusted publisher for this repo/workflow.
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC for Trusted Publishing + PEP 740 attestations
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # create the GitHub Release
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        with:
+          generate_release_notes: true

tableau_graphql_mcp-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,30 @@
+name: Scorecard
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "30 5 * * 1"
+  push:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write   # upload the SARIF result
+      id-token: write          # publish results to the OpenSSF API (badge)
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@02c5e83432fe5497fd85b873b6c9f16a8578e1d9 # v3
+        with:
+          sarif_file: results.sarif

tableau_graphql_mcp-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Secrets: never commit real credentials
+.env
+.env.local
+*.pat
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp

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

@@ -0,0 +1,15 @@
+# Local guardrails that mirror CI. Install once: `pipx run pre-commit install`
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        args: [--strict]
+        files: ^src/
+        additional_dependencies: ["mcp>=1.2.0"]

tableau_graphql_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

tableau_graphql_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# 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/). Note that the **tool schema is the public
+API**: renaming a tool or a required argument is a MAJOR change.
+
+## [Unreleased]
+
+### Added
+- `impact_analysis` tool: full transitive **multi-hop** downstream blast radius of a column,
+  field, or table (every dependent field, plus affected sheets, dashboards, workbooks, and the
+  de-duplicated owners to notify) — no longer leaves the recursion to the model.
+- `search_content` tool: case-insensitive **substring** search across workbooks, datasources,
+  tables (and optionally fields/columns), since the Metadata API filters are exact-match only.
+- Read-only enforcement: `graphql_query` rejects `mutation`/`subscription` operations.
+
+### Changed
+- `graphql_query` flags `partial_results: true` with a `warning` when a query hits the
+  ~20,000-node limit, instead of passing the truncation through silently.
+- `search_content` adds an exact-match fast path (complete, instant) and reports per-type
+  `scanned`/`total` coverage so partial substring scans are explicit.
+- Fully typed: the package ships a verified PEP 561 `py.typed` marker and passes
+  `mypy --strict` in CI, so consumers importing it get complete types.
+
+### Internal
+- CI now runs `ruff format --check` and `mypy --strict`, uploads coverage to Codecov
+  (85% floor), and scans with CodeQL and OpenSSF Scorecard. GitHub Actions are pinned to
+  commit SHAs; a tool-schema contract test guards the public tool API.
+
+## [0.1.0] - 2026-07-09
+
+### Added
+- Initial release: a read-only MCP server over the Tableau Metadata API (GraphQL).
+- Five tools: `graphql_query`, `introspect_schema`, `lineage_examples`, `where_used`, `server_info`.
+- Generic auth for Tableau **Server** and **Cloud** via Personal Access Token, with a
+  cookie/token fallback for SSO tenants.
+- Auto-detection of the REST API version (`/api/serverinfo`) and the GraphQL endpoint
+  (`/api/metadata/graphql`, falling back to `/relationship-service-war/graphql`).
+- Robust `where_used` resolution via core lineage (works without the Data Management add-on).
+- Embedded schema cheat-sheet and 28 curated question→GraphQL examples across 8 categories.
+- `uvx`-runnable console entry point; no runtime dependencies beyond the MCP SDK.
+
+[Unreleased]: https://github.com/tdries/tableau-graphQL-mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tdries/tableau-graphQL-mcp/releases/tag/v0.1.0

tableau_graphql_mcp-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**tim.dries@biztory.be**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

tableau_graphql_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for your interest! This is a small, focused MCP server; contributions that keep it
+that way are very welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/tdries/tableau-graphQL-mcp && cd tableau-graphQL-mcp
+uv sync                       # installs the package + dev tools
+uv run pytest                 # tests run offline, no Tableau needed
+uv run ruff check .
+uv run ruff format .
+```
+
+Run the server from source, pointed at your own Tableau site:
+
+```bash
+export TABLEAU_SERVER=https://<pod>.online.tableau.com
+export TABLEAU_SITE_CONTENT_URL=YourSite
+export TABLEAU_PAT_NAME=... TABLEAU_PAT_SECRET=...
+uv run tableau-graphql-mcp
+# or exercise it interactively:
+npx @modelcontextprotocol/inspector uv run tableau-graphql-mcp
+```
+
+## Guidelines
+
+- **Keep the tool surface small.** Every tool is tokens in the model's context. Prefer
+  extending `graphql_query`/examples over adding a narrow tool.
+- **Read-only.** No mutating operations.
+- **Stdlib first.** The only runtime dependency is the MCP SDK; keep it that way unless there's
+  a strong reason.
+- **Secrets via env only**, never as tool arguments, never logged.
+- **No writes to stdout**: it carries the JSON-RPC protocol. Log to stderr.
+- Add/adjust a test for behavior changes; update `CHANGELOG.md` under `[Unreleased]`.
+- A tool rename or required-arg change is a **MAJOR** version bump; call it out in the PR.
+
+## Reporting issues
+
+Open an issue with your Tableau flavor (Server/Cloud + version), whether Data Management is
+licensed, and the exact tool call and (sanitized) response.

tableau_graphql_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Dries
+
+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.