voipbin-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv venv --python ${{ matrix.python-version }}
+      - run: uv pip install -e ".[dev]"
+      - run: uv run pytest tests/ -v

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

@@ -0,0 +1,16 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

voipbin_mcp-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+CLAUDE.md
+*.pem
+*.key
+*.p12
+id_rsa
+.DS_Store
+.idea/
+.vscode/

voipbin_mcp-0.1.0/LICENSE

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

voipbin_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: voipbin-mcp
+Version: 0.1.0
+Summary: MCP server for the VoIPbin CPaaS platform
+Project-URL: Homepage, https://voipbin.net
+Project-URL: Repository, https://github.com/voipbin/mcp
+Project-URL: Bug Tracker, https://github.com/voipbin/mcp/issues
+Author-email: VoIPbin <support@voipbin.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cpaas,mcp,model-context-protocol,telephony,voip,voipbin
+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.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# VoIPbin MCP Server
+
+An MCP (Model Context Protocol) server that enables AI assistants to interact with the VoIPbin CPaaS platform. It exposes VoIPbin's communication APIs -- calls, flows, messaging, conferencing, AI, and more -- as tools that any MCP-compatible client can use to manage and automate cloud communications.
+
+## Installation
+
+```bash
+pip install voipbin-mcp
+```
+
+Or run directly without installing:
+
+```bash
+uvx voipbin-mcp
+```
+
+## Configuration
+
+### Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "voipbin": {
+      "command": "uvx",
+      "args": ["voipbin-mcp"],
+      "env": {
+        "VOIPBIN_API_KEY": "your-access-key"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project directory:
+
+```json
+{
+  "mcpServers": {
+    "voipbin": {
+      "command": "uvx",
+      "args": ["voipbin-mcp"],
+      "env": {
+        "VOIPBIN_API_KEY": "your-access-key"
+      }
+    }
+  }
+}
+```
+
+### Generic MCP Client
+
+Any MCP-compatible client can connect by running the `voipbin-mcp` command with the `VOIPBIN_API_KEY` environment variable set:
+
+```bash
+VOIPBIN_API_KEY=your-access-key voipbin-mcp
+```
+
+## Available Tools
+
+| Resource | Tools |
+|---|---|
+| Calls | `list_calls`, `get_call`, `create_call`, `hangup_call` |
+| Flows | `list_flows`, `get_flow`, `create_flow`, `update_flow`, `delete_flow` |
+| Active Flows | `list_activeflows`, `get_activeflow`, `stop_activeflow` |
+| Agents | `list_agents`, `get_agent` |
+| Numbers | `list_numbers`, `get_number` |
+| Contacts | `list_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact` |
+| Messages | `list_messages`, `get_message`, `send_message` |
+| Emails | `list_emails`, `get_email`, `send_email` |
+| Conversations | `list_conversations`, `get_conversation` |
+| Conferences | `list_conferences`, `get_conference`, `create_conference`, `delete_conference` |
+| Campaigns | `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `delete_campaign` |
+| Queues | `list_queues`, `get_queue` |
+| Routes | `list_routes`, `get_route` |
+| Billings | `list_billings`, `get_billing` |
+| AIs | `list_ais`, `get_ai`, `create_ai` |
+| Customer | `get_customer` |
+| Tags | `list_tags`, `get_tag` |
+| Extensions | `list_extensions`, `get_extension` |
+
+## Example Usage
+
+Once configured, you can ask your AI assistant to interact with VoIPbin directly:
+
+**List active calls:**
+> "Show me all my active calls"
+
+The AI uses `list_calls` to fetch and display your current calls.
+
+**Create a flow:**
+> "Create a flow that answers and plays a greeting"
+
+The AI uses `create_flow` to build a call flow with answer and play actions.
+
+**Check billing:**
+> "What are my recent billing charges?"
+
+The AI uses `list_billings` to retrieve your billing history.
+
+**Manage contacts:**
+> "Add a new contact named John with phone number +1234567890"
+
+The AI uses `create_contact` to create the contact in your account.
+
+## Security Note
+
+Your VoIPbin API key is sent as a URL query parameter (`accesskey=`) on every request. The connection uses HTTPS, so the key is encrypted in transit. However, be aware that URL parameters may be recorded in server access logs and proxy logs. Avoid sharing unredacted debug output, and rotate your key if you suspect it has been exposed.
+
+## Getting an API Key
+
+Sign up at [voipbin.net](https://voipbin.net) and create an access key through the API or the admin console at [admin.voipbin.net](https://admin.voipbin.net).
+
+## Development
+
+```bash
+git clone https://github.com/voipbin/mcp.git
+cd mcp
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest tests/ -v
+```
+
+## License
+
+MIT

voipbin_mcp-0.1.0/README.md

@@ -0,0 +1,130 @@
+# VoIPbin MCP Server
+
+An MCP (Model Context Protocol) server that enables AI assistants to interact with the VoIPbin CPaaS platform. It exposes VoIPbin's communication APIs -- calls, flows, messaging, conferencing, AI, and more -- as tools that any MCP-compatible client can use to manage and automate cloud communications.
+
+## Installation
+
+```bash
+pip install voipbin-mcp
+```
+
+Or run directly without installing:
+
+```bash
+uvx voipbin-mcp
+```
+
+## Configuration
+
+### Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "voipbin": {
+      "command": "uvx",
+      "args": ["voipbin-mcp"],
+      "env": {
+        "VOIPBIN_API_KEY": "your-access-key"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project directory:
+
+```json
+{
+  "mcpServers": {
+    "voipbin": {
+      "command": "uvx",
+      "args": ["voipbin-mcp"],
+      "env": {
+        "VOIPBIN_API_KEY": "your-access-key"
+      }
+    }
+  }
+}
+```
+
+### Generic MCP Client
+
+Any MCP-compatible client can connect by running the `voipbin-mcp` command with the `VOIPBIN_API_KEY` environment variable set:
+
+```bash
+VOIPBIN_API_KEY=your-access-key voipbin-mcp
+```
+
+## Available Tools
+
+| Resource | Tools |
+|---|---|
+| Calls | `list_calls`, `get_call`, `create_call`, `hangup_call` |
+| Flows | `list_flows`, `get_flow`, `create_flow`, `update_flow`, `delete_flow` |
+| Active Flows | `list_activeflows`, `get_activeflow`, `stop_activeflow` |
+| Agents | `list_agents`, `get_agent` |
+| Numbers | `list_numbers`, `get_number` |
+| Contacts | `list_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact` |
+| Messages | `list_messages`, `get_message`, `send_message` |
+| Emails | `list_emails`, `get_email`, `send_email` |
+| Conversations | `list_conversations`, `get_conversation` |
+| Conferences | `list_conferences`, `get_conference`, `create_conference`, `delete_conference` |
+| Campaigns | `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `delete_campaign` |
+| Queues | `list_queues`, `get_queue` |
+| Routes | `list_routes`, `get_route` |
+| Billings | `list_billings`, `get_billing` |
+| AIs | `list_ais`, `get_ai`, `create_ai` |
+| Customer | `get_customer` |
+| Tags | `list_tags`, `get_tag` |
+| Extensions | `list_extensions`, `get_extension` |
+
+## Example Usage
+
+Once configured, you can ask your AI assistant to interact with VoIPbin directly:
+
+**List active calls:**
+> "Show me all my active calls"
+
+The AI uses `list_calls` to fetch and display your current calls.
+
+**Create a flow:**
+> "Create a flow that answers and plays a greeting"
+
+The AI uses `create_flow` to build a call flow with answer and play actions.
+
+**Check billing:**
+> "What are my recent billing charges?"
+
+The AI uses `list_billings` to retrieve your billing history.
+
+**Manage contacts:**
+> "Add a new contact named John with phone number +1234567890"
+
+The AI uses `create_contact` to create the contact in your account.
+
+## Security Note
+
+Your VoIPbin API key is sent as a URL query parameter (`accesskey=`) on every request. The connection uses HTTPS, so the key is encrypted in transit. However, be aware that URL parameters may be recorded in server access logs and proxy logs. Avoid sharing unredacted debug output, and rotate your key if you suspect it has been exposed.
+
+## Getting an API Key
+
+Sign up at [voipbin.net](https://voipbin.net) and create an access key through the API or the admin console at [admin.voipbin.net](https://admin.voipbin.net).
+
+## Development
+
+```bash
+git clone https://github.com/voipbin/mcp.git
+cd mcp
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest tests/ -v
+```
+
+## License
+
+MIT

voipbin_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "voipbin-mcp"
+version = "0.1.0"
+description = "MCP server for the VoIPbin CPaaS platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "VoIPbin", email = "support@voipbin.net"},
+]
+keywords = ["mcp", "voipbin", "cpaas", "voip", "telephony", "ai", "model-context-protocol"]
+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 = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://voipbin.net"
+Repository = "https://github.com/voipbin/mcp"
+"Bug Tracker" = "https://github.com/voipbin/mcp/issues"
+
+[project.scripts]
+voipbin-mcp = "voipbin_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voipbin_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]

voipbin_mcp-0.1.0/src/voipbin_mcp/__init__.py

@@ -0,0 +1 @@
+"""VoIPbin MCP Server - MCP tools for the VoIPbin CPaaS platform."""

voipbin_mcp-0.1.0/src/voipbin_mcp/client.py

@@ -0,0 +1,106 @@
+"""HTTP client for the VoIPbin REST API."""
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+BASE_URL = "https://api.voipbin.net/v1.0"
+
+
+class VoIPbinAPIError(Exception):
+    """Raised when a VoIPbin API call fails."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(message)
+
+
+class VoIPbinClient:
+    """Async HTTP client for the VoIPbin REST API."""
+
+    def __init__(self):
+        self.api_key = os.environ.get("VOIPBIN_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "VOIPBIN_API_KEY environment variable is required. "
+                "Set it to your VoIPbin access key."
+            )
+        self.base_url = BASE_URL
+        self._client = httpx.AsyncClient(timeout=30.0)
+
+    def __repr__(self) -> str:
+        base_url = getattr(self, "base_url", "<not initialised>")
+        return f"VoIPbinClient(base_url={base_url!r})"
+
+    def _params_with_auth(self, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Add accesskey to query parameters."""
+        result = dict(params) if params else {}
+        result["accesskey"] = self.api_key
+        return result
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Raise descriptive errors for non-2xx responses."""
+        if response.is_success:
+            return
+
+        try:
+            body = response.json()
+            detail = body.get("message", "")
+        except Exception:
+            detail = response.text
+
+        error_map = {
+            401: "Invalid or expired API key",
+            402: "Insufficient credits",
+            403: "Permission denied",
+            404: f"Resource not found: {detail}",
+            409: f"Conflict: {detail}",
+        }
+
+        message = error_map.get(response.status_code, f"API error {response.status_code}: {detail}")
+        raise VoIPbinAPIError(response.status_code, message)
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        """Send a GET request."""
+        response = await self._client.get(
+            f"{self.base_url}{path}",
+            params=self._params_with_auth(params),
+        )
+        self._handle_error(response)
+        return response.json()
+
+    async def post(self, path: str, json: dict[str, Any] | None = None) -> dict:
+        """Send a POST request."""
+        response = await self._client.post(
+            f"{self.base_url}{path}",
+            params=self._params_with_auth(),
+            json=json,
+        )
+        self._handle_error(response)
+        return response.json()
+
+    async def put(self, path: str, json: dict[str, Any] | None = None) -> dict:
+        """Send a PUT request."""
+        response = await self._client.put(
+            f"{self.base_url}{path}",
+            params=self._params_with_auth(),
+            json=json,
+        )
+        self._handle_error(response)
+        return response.json()
+
+    async def delete(self, path: str) -> dict:
+        """Send a DELETE request."""
+        response = await self._client.delete(
+            f"{self.base_url}{path}",
+            params=self._params_with_auth(),
+        )
+        self._handle_error(response)
+        return response.json()
+
+    async def close(self):
+        """Close the underlying HTTP client."""
+        await self._client.aclose()

voipbin_mcp-0.1.0/src/voipbin_mcp/server.py

@@ -0,0 +1,47 @@
+"""VoIPbin MCP server entry point."""
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from voipbin_mcp.client import VoIPbinClient
+
+mcp = FastMCP("voipbin")
+
+# Lazy-initialized client (created on first tool call)
+_client: VoIPbinClient | None = None
+
+
+def get_client() -> VoIPbinClient:
+    """Get or create the VoIPbin HTTP client."""
+    global _client
+    if _client is None:
+        _client = VoIPbinClient()
+    return _client
+
+
+def format_response(data: dict) -> str:
+    """Format API response as readable JSON string."""
+    return json.dumps(data, indent=2, default=str)
+
+
+def validate_page_size(page_size: int) -> int:
+    """Clamp page_size to a safe integer range (1–100)."""
+    try:
+        page_size = int(page_size)
+    except (TypeError, ValueError):
+        page_size = 10
+    return max(1, min(page_size, 100))
+
+
+# Import tools to register them on the mcp instance
+import voipbin_mcp.tools  # noqa: E402, F401
+
+
+def main():
+    """Run the VoIPbin MCP server over stdio."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

voipbin_mcp-0.1.0/src/voipbin_mcp/tools/__init__.py

@@ -0,0 +1,20 @@
+"""VoIPbin MCP tools — importing registers them on the server."""
+
+from voipbin_mcp.tools import calls  # noqa: F401
+from voipbin_mcp.tools import flows  # noqa: F401
+from voipbin_mcp.tools import activeflows  # noqa: F401
+from voipbin_mcp.tools import agents  # noqa: F401
+from voipbin_mcp.tools import numbers  # noqa: F401
+from voipbin_mcp.tools import contacts  # noqa: F401
+from voipbin_mcp.tools import messages  # noqa: F401
+from voipbin_mcp.tools import emails  # noqa: F401
+from voipbin_mcp.tools import conversations  # noqa: F401
+from voipbin_mcp.tools import conferences  # noqa: F401
+from voipbin_mcp.tools import campaigns  # noqa: F401
+from voipbin_mcp.tools import queues  # noqa: F401
+from voipbin_mcp.tools import routes  # noqa: F401
+from voipbin_mcp.tools import billings  # noqa: F401
+from voipbin_mcp.tools import ais  # noqa: F401
+from voipbin_mcp.tools import customer  # noqa: F401
+from voipbin_mcp.tools import tags  # noqa: F401
+from voipbin_mcp.tools import extensions  # noqa: F401

voipbin_mcp-0.1.0/src/voipbin_mcp/tools/activeflows.py

@@ -0,0 +1,45 @@
+"""Active flow tools."""
+
+from voipbin_mcp.server import mcp, get_client, format_response, validate_page_size
+
+
+@mcp.tool()
+async def list_activeflows(page_size: int = 10, page_token: str = "") -> str:
+    """List all currently running active flows.
+
+    Active flows are flow instances currently executing on calls.
+
+    Args:
+        page_size: Number of results per page (default 10).
+        page_token: Pagination cursor from a previous response.
+    """
+    client = get_client()
+    params = {"page_size": validate_page_size(page_size)}
+    if page_token:
+        params["page_token"] = page_token
+    result = await client.get("/activeflows", params=params)
+    return format_response(result)
+
+
+@mcp.tool()
+async def get_activeflow(activeflow_id: str) -> str:
+    """Get details of a running active flow.
+
+    Args:
+        activeflow_id: The UUID of the active flow.
+    """
+    client = get_client()
+    result = await client.get(f"/activeflows/{activeflow_id}")
+    return format_response(result)
+
+
+@mcp.tool()
+async def stop_activeflow(activeflow_id: str) -> str:
+    """Stop a running active flow.
+
+    Args:
+        activeflow_id: The UUID of the active flow to stop.
+    """
+    client = get_client()
+    result = await client.post(f"/activeflows/{activeflow_id}/stop")
+    return format_response(result)

voipbin_mcp-0.1.0/src/voipbin_mcp/tools/agents.py

@@ -0,0 +1,33 @@
+"""Agent tools."""
+
+from voipbin_mcp.server import mcp, get_client, format_response, validate_page_size
+
+
+@mcp.tool()
+async def list_agents(page_size: int = 10, page_token: str = "") -> str:
+    """List all agents in your VoIPbin account.
+
+    Agents are users who can handle calls, messages, and other interactions.
+
+    Args:
+        page_size: Number of results per page (default 10).
+        page_token: Pagination cursor from a previous response.
+    """
+    client = get_client()
+    params = {"page_size": validate_page_size(page_size)}
+    if page_token:
+        params["page_token"] = page_token
+    result = await client.get("/agents", params=params)
+    return format_response(result)
+
+
+@mcp.tool()
+async def get_agent(agent_id: str) -> str:
+    """Get details of a specific agent.
+
+    Args:
+        agent_id: The UUID of the agent.
+    """
+    client = get_client()
+    result = await client.get(f"/agents/{agent_id}")
+    return format_response(result)