pangram-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,49 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Trusted publishing — no token needed.
+        # Configure at: https://pypi.org/manage/project/pangram-mcp/settings/publishing/
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" --title "$TAG" --generate-notes

pangram_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest -q

pangram_mcp-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+uv.lock

pangram_mcp-0.1.0/LICENSE

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

pangram_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: pangram-mcp
+Version: 0.1.0
+Summary: MCP server for Pangram Labs AI-generated-text detection
+Project-URL: Repository, https://github.com/Consiliency/pangram-mcp
+Project-URL: Homepage, https://github.com/Consiliency/pangram-mcp
+Project-URL: Issues, https://github.com/Consiliency/pangram-mcp/issues
+Author: Consiliency
+License: MIT
+License-File: LICENSE
+Keywords: ai-detection,llm,mcp,model-context-protocol,pangram
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pangram-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [Pangram Labs](https://pangram.com)
+AI-generated-text detection. Exposes a single `analyze` tool that classifies text as
+human-written, AI-generated, or AI-assisted — with an overall verdict, per-class
+fractions, and a per-segment breakdown.
+
+The API key stays in the server's environment and is sent as the `x-api-key` header; it
+is never returned to the model or logged. Callers pass text and receive a classification
+— they never handle the credential.
+
+## Install / run
+
+Requires an API key from [Pangram Labs](https://pangram.com):
+
+```sh
+export PANGRAM_API_KEY="your-key"
+uvx pangram-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "pangram": {
+      "command": "uvx",
+      "args": ["pangram-mcp"],
+      "env": { "PANGRAM_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Env var | Required | Default | Purpose |
+|---|---|---|---|
+| `PANGRAM_API_KEY` | yes | — | Pangram Labs API key. |
+| `PANGRAM_API_BASE` | no | `https://text.api.pangram.com/v3` | Endpoint override. |
+| `PANGRAM_TIMEOUT` | no | `60` | Request timeout (seconds). |
+
+## Tool: `analyze`
+
+Detect AI-generated text. Provide **either** `text` **or** `file`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `text` | string | Raw text to classify. |
+| `file` | string | Path to a local UTF-8 text file to read and classify. |
+| `public_dashboard_link` | bool | Request a shareable Pangram dashboard link (default `false`). |
+
+Returns structured output: `prediction`, `prediction_short`, `headline`,
+`fraction_ai` / `fraction_ai_assisted` / `fraction_human` (0.0–1.0),
+`num_ai_segments` / `num_ai_assisted_segments` / `num_human_segments`, a `windows`
+array (per-segment `label`, `ai_assistance_score`, `confidence`, indices), and an
+optional `dashboard_link`.
+
+## Development
+
+```sh
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+uv run mypy src
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

pangram_mcp-0.1.0/README.md

@@ -0,0 +1,70 @@
+# pangram-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [Pangram Labs](https://pangram.com)
+AI-generated-text detection. Exposes a single `analyze` tool that classifies text as
+human-written, AI-generated, or AI-assisted — with an overall verdict, per-class
+fractions, and a per-segment breakdown.
+
+The API key stays in the server's environment and is sent as the `x-api-key` header; it
+is never returned to the model or logged. Callers pass text and receive a classification
+— they never handle the credential.
+
+## Install / run
+
+Requires an API key from [Pangram Labs](https://pangram.com):
+
+```sh
+export PANGRAM_API_KEY="your-key"
+uvx pangram-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "pangram": {
+      "command": "uvx",
+      "args": ["pangram-mcp"],
+      "env": { "PANGRAM_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Env var | Required | Default | Purpose |
+|---|---|---|---|
+| `PANGRAM_API_KEY` | yes | — | Pangram Labs API key. |
+| `PANGRAM_API_BASE` | no | `https://text.api.pangram.com/v3` | Endpoint override. |
+| `PANGRAM_TIMEOUT` | no | `60` | Request timeout (seconds). |
+
+## Tool: `analyze`
+
+Detect AI-generated text. Provide **either** `text` **or** `file`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `text` | string | Raw text to classify. |
+| `file` | string | Path to a local UTF-8 text file to read and classify. |
+| `public_dashboard_link` | bool | Request a shareable Pangram dashboard link (default `false`). |
+
+Returns structured output: `prediction`, `prediction_short`, `headline`,
+`fraction_ai` / `fraction_ai_assisted` / `fraction_human` (0.0–1.0),
+`num_ai_segments` / `num_ai_assisted_segments` / `num_human_segments`, a `windows`
+array (per-segment `label`, `ai_assistance_score`, `confidence`, indices), and an
+optional `dashboard_link`.
+
+## Development
+
+```sh
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+uv run mypy src
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

pangram_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "pangram-mcp"
+version = "0.1.0"
+description = "MCP server for Pangram Labs AI-generated-text detection"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Consiliency" }]
+keywords = ["mcp", "model-context-protocol", "pangram", "ai-detection", "llm"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Repository = "https://github.com/Consiliency/pangram-mcp"
+Homepage = "https://github.com/Consiliency/pangram-mcp"
+Issues = "https://github.com/Consiliency/pangram-mcp/issues"
+
+[project.scripts]
+pangram-mcp = "pangram_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21", "ruff>=0.6", "mypy>=1.11"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pangram_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100

pangram_mcp-0.1.0/src/pangram_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""pangram-mcp — an MCP server for Pangram Labs AI-generated-text detection."""
+
+__version__ = "0.1.0"

pangram_mcp-0.1.0/src/pangram_mcp/server.py

@@ -0,0 +1,223 @@
+"""Pangram MCP server — AI-generated-text detection via the Pangram Labs API.
+
+Exposes a single ``analyze`` tool that classifies text as human-written,
+AI-generated, or AI-assisted, with an overall verdict, per-class fractions, and a
+per-segment breakdown.
+
+Configuration (environment variables):
+- ``PANGRAM_API_KEY`` (required): a Pangram Labs API key (https://pangram.com).
+- ``PANGRAM_API_BASE`` (optional): override the endpoint. Defaults to the canonical
+  synchronous v3 endpoint ``https://text.api.pangram.com/v3``.
+- ``PANGRAM_TIMEOUT`` (optional): request timeout in seconds (default 60).
+
+The API key is read from the environment and sent as the ``x-api-key`` header. It is
+never logged or returned in tool output.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated, Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import BaseModel, Field
+
+DEFAULT_API_BASE = "https://text.api.pangram.com/v3"
+API_KEY_ENV = "PANGRAM_API_KEY"
+# Guard against accidentally shipping a whole book; Pangram bounds request size and
+# very long inputs waste credits. Callers should chunk larger documents themselves.
+MAX_CHARS = 100_000
+
+mcp = FastMCP("pangram")
+
+
+class Window(BaseModel):
+    """A per-segment classification returned by Pangram."""
+
+    text: str = Field(description="The segment of the input this window covers.")
+    label: str = Field(description="Human-readable segment label, e.g. 'AI' / 'Human'.")
+    ai_assistance_score: float = Field(
+        description="AI-assistance score for this segment (0.0-1.0)."
+    )
+    confidence: str = Field(description="Confidence bucket, e.g. 'High'/'Medium'/'Low'.")
+    start_index: int | None = None
+    end_index: int | None = None
+    word_count: int | None = None
+    token_length: int | None = None
+
+
+class AnalyzeResult(BaseModel):
+    """Structured result of a Pangram AI-detection call."""
+
+    prediction: str = Field(description="Overall verdict for the whole text.")
+    prediction_short: str | None = Field(
+        default=None, description="Short form of the verdict."
+    )
+    headline: str | None = Field(default=None, description="One-line human summary.")
+    version: str | None = Field(
+        default=None, description="Pangram model version that produced this result."
+    )
+    fraction_ai: float = Field(
+        description="Fraction of the text classified as AI-generated (0.0-1.0)."
+    )
+    fraction_ai_assisted: float = Field(
+        description="Fraction classified as AI-assisted (0.0-1.0)."
+    )
+    fraction_human: float = Field(
+        description="Fraction classified as human-written (0.0-1.0)."
+    )
+    num_ai_segments: int | None = None
+    num_ai_assisted_segments: int | None = None
+    num_human_segments: int | None = None
+    windows: list[Window] = Field(
+        default_factory=list, description="Per-segment breakdown."
+    )
+    dashboard_link: str | None = Field(
+        default=None, description="Shareable dashboard URL (only if requested)."
+    )
+
+
+def _resolve_input(text: str | None, file: str | None) -> str:
+    """Return the text to classify from exactly one of ``text`` or ``file``."""
+    provided = [x for x in (text, file) if x]
+    if len(provided) != 1:
+        raise ValueError(
+            "Provide exactly one of `text` or `file` (got "
+            f"{'both' if len(provided) == 2 else 'neither'})."
+        )
+    if file:
+        try:
+            with open(file, encoding="utf-8") as fh:
+                content = fh.read()
+        except FileNotFoundError:
+            raise ValueError(f"File not found: {file}") from None
+        except OSError as exc:
+            raise ValueError(f"Could not read {file}: {exc}") from None
+    else:
+        content = text or ""
+    content = content.strip()
+    if not content:
+        raise ValueError("The text to analyze is empty.")
+    if len(content) > MAX_CHARS:
+        raise ValueError(
+            f"Input is {len(content)} chars; the limit is {MAX_CHARS}. "
+            "Chunk the document and analyze segments separately."
+        )
+    return content
+
+
+def _explain_http_error(status: int, body: str) -> str:
+    """Map a Pangram HTTP status to an actionable message."""
+    hints = {
+        400: "Bad request — check the text payload.",
+        401: f"Unauthorized — the {API_KEY_ENV} is missing or invalid.",
+        402: "Payment required — the Pangram account is out of credits.",
+        404: "Endpoint not found — verify PANGRAM_API_BASE.",
+        422: "Unprocessable input — the text may be too short or malformed.",
+        429: "Rate limited by Pangram — retry after a short backoff.",
+        500: "Pangram server error — retry later.",
+    }
+    hint = hints.get(status, "Unexpected Pangram API error.")
+    snippet = body.strip()[:300]
+    return f"Pangram API {status}: {hint}" + (f" ({snippet})" if snippet else "")
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Detect AI-generated text",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    )
+)
+async def analyze(
+    text: Annotated[
+        str | None,
+        Field(description="Raw text to classify. Provide this OR `file`, not both."),
+    ] = None,
+    file: Annotated[
+        str | None,
+        Field(
+            description="Path to a local UTF-8 text file to read and classify. "
+            "Provide this OR `text`, not both."
+        ),
+    ] = None,
+    public_dashboard_link: Annotated[
+        bool,
+        Field(description="Request a shareable Pangram dashboard link for the result."),
+    ] = False,
+) -> AnalyzeResult:
+    """Detect AI-generated text with Pangram Labs.
+
+    Classifies the input as human-written, AI-generated, or AI-assisted and returns an
+    overall verdict (`prediction`), per-class fractions 0.0-1.0
+    (`fraction_ai` / `fraction_ai_assisted` / `fraction_human`), segment counts, and a
+    per-segment breakdown (`windows`). Provide either `text` or `file`.
+
+    Requires the PANGRAM_API_KEY environment variable.
+    """
+    content = _resolve_input(text, file)
+
+    api_key = os.environ.get(API_KEY_ENV)
+    if not api_key:
+        raise ValueError(
+            f"{API_KEY_ENV} is not set. Configure a Pangram API key "
+            "(https://pangram.com) in the server environment."
+        )
+    api_base = os.environ.get("PANGRAM_API_BASE", DEFAULT_API_BASE)
+    timeout = float(os.environ.get("PANGRAM_TIMEOUT", "60"))
+
+    payload: dict[str, Any] = {"text": content}
+    if public_dashboard_link:
+        payload["public_dashboard_link"] = True
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(
+                api_base, headers={"x-api-key": api_key}, json=payload
+            )
+    except httpx.TimeoutException:
+        raise ValueError(
+            f"Pangram request timed out after {timeout}s (PANGRAM_TIMEOUT)."
+        ) from None
+    except httpx.HTTPError as exc:
+        raise ValueError(f"Could not reach Pangram: {exc}") from None
+
+    if resp.status_code != 200:
+        raise ValueError(_explain_http_error(resp.status_code, resp.text))
+
+    try:
+        data = resp.json()
+    except ValueError:
+        raise ValueError("Pangram returned a non-JSON response.") from None
+
+    # Drop the echoed input text to keep the result compact; tolerate schema drift by
+    # ignoring unknown fields (Pydantic default) and filling known ones.
+    data.pop("text", None)
+    windows = [Window(**w) for w in data.get("windows", []) if isinstance(w, dict)]
+    return AnalyzeResult(
+        prediction=str(data.get("prediction", "unknown")),
+        prediction_short=data.get("prediction_short"),
+        headline=data.get("headline"),
+        version=data.get("version"),
+        fraction_ai=float(data.get("fraction_ai", 0.0)),
+        fraction_ai_assisted=float(data.get("fraction_ai_assisted", 0.0)),
+        fraction_human=float(data.get("fraction_human", 0.0)),
+        num_ai_segments=data.get("num_ai_segments"),
+        num_ai_assisted_segments=data.get("num_ai_assisted_segments"),
+        num_human_segments=data.get("num_human_segments"),
+        windows=windows,
+        dashboard_link=data.get("dashboard_link"),
+    )
+
+
+def main() -> None:
+    """Console-script entry point: run the server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pangram_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,115 @@
+"""Unit tests for the pangram-mcp server (API mocked with respx)."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+import respx
+
+from pangram_mcp import server
+from pangram_mcp.server import AnalyzeResult, _explain_http_error, _resolve_input, analyze
+
+API = server.DEFAULT_API_BASE
+
+SAMPLE = {
+    "text": "echoed back input",
+    "version": "3.3.2",
+    "prediction": "Likely AI-generated",
+    "prediction_short": "AI",
+    "headline": "This text is likely AI-generated.",
+    "fraction_ai": 0.92,
+    "fraction_ai_assisted": 0.05,
+    "fraction_human": 0.03,
+    "num_ai_segments": 3,
+    "num_ai_assisted_segments": 0,
+    "num_human_segments": 1,
+    "windows": [
+        {
+            "text": "A segment.",
+            "label": "AI",
+            "ai_assistance_score": 0.9,
+            "confidence": "High",
+            "start_index": 0,
+            "end_index": 10,
+            "word_count": 2,
+            "token_length": 3,
+        }
+    ],
+}
+
+
+# --- input resolution -------------------------------------------------------
+
+def test_resolve_text():
+    assert _resolve_input("  hello  ", None) == "hello"
+
+
+def test_resolve_file(tmp_path):
+    p = tmp_path / "doc.txt"
+    p.write_text("from a file")
+    assert _resolve_input(None, str(p)) == "from a file"
+
+
+def test_resolve_requires_exactly_one():
+    with pytest.raises(ValueError, match="exactly one"):
+        _resolve_input("a", "b")
+    with pytest.raises(ValueError, match="exactly one"):
+        _resolve_input(None, None)
+
+
+def test_resolve_empty_text():
+    with pytest.raises(ValueError, match="empty"):
+        _resolve_input("   ", None)
+
+
+def test_resolve_missing_file():
+    with pytest.raises(ValueError, match="File not found"):
+        _resolve_input(None, "/no/such/file.txt")
+
+
+def test_resolve_too_long():
+    with pytest.raises(ValueError, match="limit"):
+        _resolve_input("x" * (server.MAX_CHARS + 1), None)
+
+
+# --- error mapping ----------------------------------------------------------
+
+@pytest.mark.parametrize(
+    "status,needle",
+    [(401, "missing or invalid"), (402, "out of credits"), (429, "Rate limited")],
+)
+def test_explain_http_error(status, needle):
+    assert needle in _explain_http_error(status, "body")
+
+
+# --- analyze tool -----------------------------------------------------------
+
+@respx.mock
+async def test_analyze_happy_path(monkeypatch):
+    monkeypatch.setenv("PANGRAM_API_KEY", "test-key")
+    route = respx.post(API).mock(return_value=httpx.Response(200, json=SAMPLE))
+    result = await analyze(text="Some text to classify.")
+    assert isinstance(result, AnalyzeResult)
+    assert result.prediction == "Likely AI-generated"
+    assert result.version == "3.3.2"
+    assert result.fraction_ai == pytest.approx(0.92)
+    assert len(result.windows) == 1
+    assert result.windows[0].confidence == "High"
+    # request carried the key + payload, and did not leak text back into the result
+    sent = route.calls.last.request
+    assert sent.headers["x-api-key"] == "test-key"
+    assert b'"text"' in sent.content
+
+
+async def test_analyze_requires_key(monkeypatch):
+    monkeypatch.delenv("PANGRAM_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="PANGRAM_API_KEY is not set"):
+        await analyze(text="hello")
+
+
+@respx.mock
+async def test_analyze_http_error(monkeypatch):
+    monkeypatch.setenv("PANGRAM_API_KEY", "test-key")
+    respx.post(API).mock(return_value=httpx.Response(402, text="no credits"))
+    with pytest.raises(ValueError, match="402"):
+        await analyze(text="hello")