kvc-mcp 0.1.0__tar.gz

kvc_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    name: Build + Publish to PyPI (trusted publisher)
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  registry:
+    name: Publish server.json to MCP Registry
+    runs-on: ubuntu-latest
+    needs: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mcp-publisher
+        run: |
+          curl -sSL https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz \
+            | tar -xz -C /usr/local/bin mcp-publisher
+          chmod +x /usr/local/bin/mcp-publisher
+      - name: Login (GitHub OIDC)
+        run: mcp-publisher login github-oidc
+      - name: Publish
+        run: mcp-publisher publish

kvc_mcp-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.log
+.DS_Store

kvc_mcp-0.1.0/LICENSE

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

kvc_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: kvc-mcp
+Version: 0.1.0
+Summary: MCP server for Krystal Voice Caller — let AI agents manage your voice tenant, drive scripts, place test calls, and harvest captures.
+Project-URL: Homepage, https://krystalunity.com/voice/krystal-caller
+Project-URL: Documentation, https://github.com/KrystalUnity/kvc-mcp#readme
+Project-URL: Repository, https://github.com/KrystalUnity/kvc-mcp
+Project-URL: Issues, https://github.com/KrystalUnity/kvc-mcp/issues
+Author-email: Krystal Unity <support@krystalunity.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,claude,cursor,krystal-voice-caller,mcp,openai-realtime,outbound,reception,twilio,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# kvc-mcp
+
+MCP access is included with every Krystal Voice Caller tier. Use this package to manage a tenant from Claude, Cursor, or any MCP-aware agent.
+
+## Install
+
+```bash
+pip install kvc-mcp
+```
+
+## Configure
+
+Create or rotate an API token in the Krystal Voice Caller dashboard, then set:
+
+```bash
+export KVC_API_TOKEN="kvc_token_..."
+export KVC_BASE_URL="https://krystalunity.com/api/admin/kvc"
+```
+
+Cursor example:
+
+```json
+{
+  "mcpServers": {
+    "krystal-voice-caller": {
+      "command": "kvc-mcp",
+      "env": {
+        "KVC_API_TOKEN": "kvc_token_..."
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+The server exposes tenant config, DNC, call history, reception captures, digest send-now, Script Author draft chat, contact upload, outbound captures, and test-call tools. Product availability is enforced by the Krystal Voice Caller API, so Reception-only tenants get inbound/reception tools and Bundle/Premium tenants get outbound Email Hunter tools.
+
+Script approval is not exposed through MCP. Approval stays admin-only in the web UI.
+
+## Publish
+
+Operator-only steps:
+
+1. `cd packages/kvc-mcp && uv build`
+2. `uv publish --username __token__ --password "$PYPI_TOKEN"`
+3. Submit an MCP Registry entry named `io.github.KrystalUnity/kvc-mcp` pointing at the PyPI package.
+4. Verify from a fresh venv with `pip install kvc-mcp && kvc-mcp --help`.

kvc_mcp-0.1.0/PUBLISH.md

@@ -0,0 +1,16 @@
+# Publishing kvc-mcp
+
+Publishing is operator-only.
+
+1. `cd packages/kvc-mcp && uv build`
+2. `uv publish --username __token__ --password "$PYPI_TOKEN"`
+3. After PyPI has `kvc-mcp`, submit to the MCP Registry:
+   - registry name: `io.github.KrystalUnity/kvc-mcp`
+   - package: PyPI `kvc-mcp`
+   - source: `https://github.com/KrystalUnity/kvc-mcp`
+4. Verify in a fresh venv:
+
+```bash
+pip install kvc-mcp
+kvc-mcp --help
+```

kvc_mcp-0.1.0/README.md

@@ -0,0 +1,48 @@
+# kvc-mcp
+
+MCP access is included with every Krystal Voice Caller tier. Use this package to manage a tenant from Claude, Cursor, or any MCP-aware agent.
+
+## Install
+
+```bash
+pip install kvc-mcp
+```
+
+## Configure
+
+Create or rotate an API token in the Krystal Voice Caller dashboard, then set:
+
+```bash
+export KVC_API_TOKEN="kvc_token_..."
+export KVC_BASE_URL="https://krystalunity.com/api/admin/kvc"
+```
+
+Cursor example:
+
+```json
+{
+  "mcpServers": {
+    "krystal-voice-caller": {
+      "command": "kvc-mcp",
+      "env": {
+        "KVC_API_TOKEN": "kvc_token_..."
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+The server exposes tenant config, DNC, call history, reception captures, digest send-now, Script Author draft chat, contact upload, outbound captures, and test-call tools. Product availability is enforced by the Krystal Voice Caller API, so Reception-only tenants get inbound/reception tools and Bundle/Premium tenants get outbound Email Hunter tools.
+
+Script approval is not exposed through MCP. Approval stays admin-only in the web UI.
+
+## Publish
+
+Operator-only steps:
+
+1. `cd packages/kvc-mcp && uv build`
+2. `uv publish --username __token__ --password "$PYPI_TOKEN"`
+3. Submit an MCP Registry entry named `io.github.KrystalUnity/kvc-mcp` pointing at the PyPI package.
+4. Verify from a fresh venv with `pip install kvc-mcp && kvc-mcp --help`.

kvc_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "kvc-mcp"
+version = "0.1.0"
+description = "MCP server for Krystal Voice Caller — let AI agents manage your voice tenant, drive scripts, place test calls, and harvest captures."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Krystal Unity", email = "support@krystalunity.com" }]
+keywords = ["mcp", "krystal-voice-caller", "voice", "twilio", "openai-realtime", "ai-agent", "reception", "outbound", "claude", "cursor"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Telephony",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27",
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+kvc-mcp = "kvc_mcp.server:main"
+
+[project.urls]
+Homepage = "https://krystalunity.com/voice/krystal-caller"
+Documentation = "https://github.com/KrystalUnity/kvc-mcp#readme"
+Repository = "https://github.com/KrystalUnity/kvc-mcp"
+Issues = "https://github.com/KrystalUnity/kvc-mcp/issues"
+
+[build-system]
+requires = ["hatchling>=1.18.0"]
+build-backend = "hatchling.build"

kvc_mcp-0.1.0/server.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.KrystalUnity/kvc-mcp",
+  "title": "Krystal Voice Caller",
+  "description": "MCP server for Krystal Voice Caller — drive your voice tenant from Claude, Cursor, or any MCP-aware agent. Manage tenant config, DNC, call history, Script Author drafts, contact uploads, test calls, and reception captures.",
+  "websiteUrl": "https://krystalunity.com/voice/krystal-caller",
+  "repository": {
+    "url": "https://github.com/KrystalUnity/kvc-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "kvc-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "KVC_API_TOKEN",
+          "description": "Bearer token starting with kvc_token_. Generate at https://krystalunity.com/voice/krystal-caller/dashboard/api-tokens",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "KVC_BASE_URL",
+          "description": "API base URL (default https://krystalunity.com/api/admin/kvc).",
+          "isRequired": false,
+          "default": "https://krystalunity.com/api/admin/kvc"
+        }
+      ]
+    }
+  ]
+}

kvc_mcp-0.1.0/src/kvc_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Krystal Voice Caller MCP package."""
+
+__version__ = "0.1.0"

kvc_mcp-0.1.0/src/kvc_mcp/server.py

@@ -0,0 +1,210 @@
+"""Krystal Voice Caller MCP Server.
+
+Use these tools to manage a Krystal Voice Caller tenant: view config, manage
+DNC, browse call history, author scripts, place test calls, and upload
+outbound contacts. Script approval is intentionally not exposed via MCP; that
+admin-only action stays in the web UI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+API_TOKEN = os.getenv("KVC_API_TOKEN", "")
+BASE_URL = os.getenv("KVC_BASE_URL", "https://krystalunity.com/api/admin/kvc").rstrip("/")
+TIMEOUT = float(os.getenv("KVC_TIMEOUT", "30"))
+BILLING_URL = "https://krystalunity.com/voice/krystal-caller/dashboard/billing"
+TOKEN_URL = "https://krystalunity.com/voice/krystal-caller/dashboard/api-tokens"
+
+mcp = FastMCP(
+    "Krystal Voice Caller",
+    instructions=(
+        "Use these tools to manage a Krystal Voice Caller tenant - view config, "
+        "manage DNC, browse call history, author scripts, place test calls, "
+        "and upload outbound contacts."
+    ),
+)
+
+UPDATE_WHITELIST = {"agent_name", "business_hours", "digest_recipient_email", "digest_hour_local"}
+
+
+def _headers() -> dict[str, str]:
+    return {"Authorization": f"Bearer {API_TOKEN}", "Accept": "application/json"}
+
+
+def _client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(timeout=TIMEOUT)
+
+
+def _tenant_id() -> str:
+    token = API_TOKEN.strip()
+    if not token:
+        raise RuntimeError("KVC_API_TOKEN is required")
+    return os.getenv("KVC_TENANT_ID", "me")
+
+
+async def _request(method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+    async with _client() as client:
+        response = await client.request(method, f"{BASE_URL}{path}", headers=_headers(), **kwargs)
+        response.raise_for_status()
+        return response.json()
+
+
+def _format_error(exc: Exception) -> str:
+    if isinstance(exc, httpx.HTTPStatusError):
+        status = exc.response.status_code
+        if status == 401:
+            return f"Authentication failed. Check your KVC_API_TOKEN. Generate a new one at {TOKEN_URL}"
+        if status == 403:
+            product = "required"
+            try:
+                detail = exc.response.json().get("detail", {})
+                if isinstance(detail, dict):
+                    product = str(detail.get("product") or product)
+            except Exception:
+                pass
+            return f"This tool requires the {product} product. Upgrade at {BILLING_URL}"
+        if status == 429:
+            retry = exc.response.headers.get("Retry-After", "?")
+            return f"Rate limited. Retry after {retry}s."
+        try:
+            detail = exc.response.json().get("detail", exc.response.text)
+        except Exception:
+            detail = exc.response.text
+        return f"API error {status}: {detail}"
+    return f"Request failed: {exc}"
+
+
+def _json(data: Any) -> str:
+    return json.dumps(data, indent=2, default=str)
+
+
+@mcp.tool()
+async def kvc_get_tenant() -> str:
+    """Return current tenant config."""
+    try:
+        return _json(await _request("GET", f"/{_tenant_id()}"))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_update_tenant(updates: dict[str, Any]) -> str:
+    """Patch safe tenant config fields."""
+    disallowed = sorted(set(updates) - UPDATE_WHITELIST)
+    if disallowed:
+        return f"These fields are not allowed through MCP: {', '.join(disallowed)}"
+    try:
+        return _json(await _request("PATCH", f"/{_tenant_id()}", json=updates))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_list_dnc() -> str:
+    """List tenant DNC entries."""
+    try:
+        return _json(await _request("GET", f"/{_tenant_id()}/dnc"))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_add_dnc(phone: str, reason: str) -> str:
+    """Add an AU E.164 phone number to tenant DNC."""
+    try:
+        return _json(await _request("POST", f"/{_tenant_id()}/dnc", json={"phone": phone, "reason": reason}))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_call_history(limit: int = 50, kind: str | None = None) -> str:
+    """Return recent call outcomes."""
+    try:
+        return _json(await _request("GET", f"/{_tenant_id()}/call-history", params={"limit": limit, "kind": kind}))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_after_hours_captures(limit: int = 20) -> str:
+    """Return recent reception captures."""
+    try:
+        return _json(await _request("GET", f"/{_tenant_id()}/captures", params={"limit": limit, "kind": "inbound"}))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_send_digest_now() -> str:
+    """Trigger an immediate digest email send."""
+    try:
+        return _json(await _request("POST", f"/{_tenant_id()}/digest/send-now"))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_create_script_draft(prompt: str) -> str:
+    """Start a Script Author draft."""
+    try:
+        data = await _request("POST", f"/{_tenant_id()}/scripts/draft")
+        if prompt.strip():
+            data = await _request("POST", f"/{_tenant_id()}/scripts/draft/{data['draft_id']}/message", json={"message": prompt})
+        return _json(data)
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_chat_script_draft(draft_id: int, message: str) -> str:
+    """Send a message to an active Script Author draft."""
+    try:
+        return _json(await _request("POST", f"/{_tenant_id()}/scripts/draft/{draft_id}/message", json={"message": message}))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_upload_contacts(csv_content: str) -> str:
+    """Upload CSV contacts for outbound Email Hunter."""
+    try:
+        files = {"file": ("contacts.csv", csv_content.encode("utf-8"), "text/csv")}
+        return _json(await _request("POST", f"/{_tenant_id()}/contacts/upload", files=files))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_list_outbound_captures(limit: int = 50) -> str:
+    """List captures from outbound Email Hunter calls."""
+    try:
+        return _json(await _request("GET", f"/{_tenant_id()}/captures", params={"limit": limit, "kind": "outbound"}))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def kvc_place_test_call(target_phone: str) -> str:
+    """Place a test outbound roleplay call."""
+    try:
+        return _json(await _request("POST", f"/{_tenant_id()}/test-call", json={"target_phone": target_phone}))
+    except Exception as exc:
+        return _format_error(exc)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the Krystal Voice Caller MCP server.")
+    parser.parse_args()
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

kvc_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+from pathlib import Path
+
+import httpx
+import pytest
+
+PACKAGE_SRC = Path(__file__).resolve().parents[1] / "src"
+if str(PACKAGE_SRC) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_SRC))
+
+
+def _reload_server(monkeypatch):
+    monkeypatch.setenv("KVC_API_TOKEN", "kvc_token_ABCDEFGHIJKLMNOPQRSTUVWXYZ234567")
+    monkeypatch.setenv("KVC_BASE_URL", "https://krystalunity.com/api/admin/kvc")
+    sys.modules.pop("kvc_mcp.server", None)
+    return importlib.import_module("kvc_mcp.server")
+
+
+@pytest.mark.asyncio
+async def test_mcp_tool_calls_send_bearer_header(monkeypatch):
+    server = _reload_server(monkeypatch)
+    seen: dict[str, object] = {}
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        seen["authorization"] = request.headers.get("authorization")
+        seen["url"] = str(request.url)
+        return httpx.Response(200, json={"tenant_id": "tenant-a", "company_name": "Acme"})
+
+    monkeypatch.setattr(server, "_tenant_id", lambda: "tenant-a")
+    monkeypatch.setattr(server, "_client", lambda: httpx.AsyncClient(transport=httpx.MockTransport(handler)))
+
+    payload = await server.kvc_get_tenant()
+
+    assert seen["authorization"] == "Bearer kvc_token_ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+    assert seen["url"] == "https://krystalunity.com/api/admin/kvc/tenant-a"
+    assert json.loads(payload)["tenant_id"] == "tenant-a"
+
+
+def test_mcp_tool_403_returns_human_readable_capability_message(monkeypatch):
+    server = _reload_server(monkeypatch)
+    request = httpx.Request("GET", "https://example.test")
+    response = httpx.Response(
+        403,
+        request=request,
+        json={"detail": {"code": "product_required", "product": "email_hunter"}},
+    )
+
+    message = server._format_error(httpx.HTTPStatusError("forbidden", request=request, response=response))
+
+    assert "requires the email_hunter product" in message
+    assert "upgrade" in message.lower()
+    assert "https://krystalunity.com/voice/krystal-caller/dashboard/billing" in message
+
+
+def test_registered_tools_include_all_stream_l_tools(monkeypatch):
+    server = _reload_server(monkeypatch)
+
+    tool_names = {tool.name for tool in server.mcp._tool_manager.list_tools()}
+
+    assert {
+        "kvc_get_tenant",
+        "kvc_update_tenant",
+        "kvc_list_dnc",
+        "kvc_add_dnc",
+        "kvc_call_history",
+        "kvc_after_hours_captures",
+        "kvc_send_digest_now",
+        "kvc_create_script_draft",
+        "kvc_chat_script_draft",
+        "kvc_upload_contacts",
+        "kvc_list_outbound_captures",
+        "kvc_place_test_call",
+    }.issubset(tool_names)
+
+
+@pytest.mark.asyncio
+async def test_kvc_update_tenant_rejects_non_whitelisted_fields(monkeypatch):
+    server = _reload_server(monkeypatch)
+
+    result = await server.kvc_update_tenant({"agent_name": "Sam", "enabled_products": {"email_hunter": False}})
+
+    assert "not allowed" in result
+    assert "enabled_products" in result