porkbun-mcp 0.1.1__tar.gz

porkbun_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: porkbun-mcp
+Version: 0.1.1
+Summary: MCP server for Porkbun DNS API
+Keywords: mcp,porkbun,dns,model-context-protocol
+Author: Major Hayden
+Author-email: Major Hayden <major@mhtx.net>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Typing :: Typed
+Requires-Dist: fastmcp>=2.14.3
+Requires-Dist: oinker>=0.1.1
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/major/porkbun-mcp
+Project-URL: Repository, https://github.com/major/porkbun-mcp
+Description-Content-Type: text/markdown
+
+# porkbun-mcp
+
+MCP server for the [Porkbun](https://porkbun.com/) DNS API.
+
+Manage DNS records, domains, DNSSEC, SSL certificates, and more via the Model Context Protocol.
+
+[![CI](https://github.com/major/porkbun-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/major/porkbun-mcp/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/major/porkbun-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/major/porkbun-mcp)
+[![PyPI version](https://badge.fury.io/py/porkbun-mcp.svg)](https://pypi.org/project/porkbun-mcp/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Configuration
+
+Set your Porkbun API credentials as environment variables:
+
+```bash
+export PORKBUN_API_KEY="pk1_..."
+export PORKBUN_SECRET_KEY="sk1_..."
+```
+
+Get your API keys from the [Porkbun API Access page](https://porkbun.com/account/api).
+
+## Usage
+
+Run directly with [uvx](https://docs.astral.sh/uv/) (no installation required):
+
+```bash
+uvx porkbun-mcp
+```
+
+### SSE transport
+
+```bash
+uvx porkbun-mcp --transport sse
+```
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "porkbun": {
+      "command": "uvx",
+      "args": ["porkbun-mcp"],
+      "env": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code / Codex
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "porkbun": {
+      "command": "uvx",
+      "args": ["porkbun-mcp"],
+      "env": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to `.vscode/mcp.json` in your workspace (or use `MCP: Add Server` command):
+
+```json
+{
+  "servers": {
+    "porkbun": {
+      "command": "uvx",
+      "args": ["porkbun-mcp"],
+      "env": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to your `opencode.json` configuration:
+
+```json
+{
+  "mcp": {
+    "porkbun": {
+      "type": "local",
+      "command": ["uvx", "porkbun-mcp"],
+      "environment": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### DNS
+
+- `dns_list` - List all DNS records for a domain
+- `dns_get` - Get a specific DNS record by ID
+- `dns_get_by_name_type` - Get DNS records by subdomain and type
+- `dns_create` - Create a new DNS record
+- `dns_edit` - Edit a DNS record by ID
+- `dns_edit_by_name_type` - Edit DNS records by subdomain and type
+- `dns_delete` - Delete a DNS record by ID
+- `dns_delete_by_name_type` - Delete DNS records by subdomain and type
+
+### Domains
+
+- `domains_list` - List all domains in your account
+- `domains_get_nameservers` - Get nameservers for a domain
+- `domains_update_nameservers` - Update nameservers for a domain
+- `domains_get_url_forwards` - Get URL forwarding rules
+- `domains_add_url_forward` - Add a URL forwarding rule
+- `domains_delete_url_forward` - Delete a URL forwarding rule
+- `domains_check_availability` - Check domain availability and pricing
+- `domains_get_glue_records` - Get glue records for a domain
+
+### DNSSEC
+
+- `dnssec_list` - List DNSSEC records for a domain
+- `dnssec_create` - Create a DNSSEC record
+- `dnssec_delete` - Delete a DNSSEC record
+
+### SSL
+
+- `ssl_retrieve` - Retrieve the SSL certificate bundle for a domain
+
+### Pricing
+
+- `pricing_get` - Get pricing for all available TLDs
+
+### Utility
+
+- `ping` - Test API connectivity and get your public IP
+
+## Resources
+
+Browse data via MCP resources:
+
+- `porkbun://domains` - List all domains
+- `porkbun://dns/{domain}` - DNS records for a domain
+- `porkbun://ssl/{domain}` - SSL certificate bundle for a domain
+- `porkbun://pricing` - TLD pricing information
+
+## Prompts
+
+Pre-defined workflows to guide common DNS operations:
+
+- `dns_setup` - Set up basic DNS for a new server (root A + www records)
+- `dns_audit` - Audit DNS configuration for issues (duplicates, missing email records, low TTLs)
+- `email_dns_setup` - Configure email DNS (MX, SPF, DKIM, DMARC)
+- `update_server_ip` - Update DNS records when migrating to a new server IP
+- `subdomain_setup` - Create A/CNAME records for a new subdomain
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run all checks
+make check
+
+# Individual commands
+make lint       # ruff check
+make format     # ruff format
+make typecheck  # ty check
+make test       # pytest with coverage
+```
+
+## License
+
+MIT
+
+<!-- mcp-name: io.github.major/porkbun -->

porkbun_mcp-0.1.1/README.md

@@ -0,0 +1,197 @@
+# porkbun-mcp
+
+MCP server for the [Porkbun](https://porkbun.com/) DNS API.
+
+Manage DNS records, domains, DNSSEC, SSL certificates, and more via the Model Context Protocol.
+
+[![CI](https://github.com/major/porkbun-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/major/porkbun-mcp/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/major/porkbun-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/major/porkbun-mcp)
+[![PyPI version](https://badge.fury.io/py/porkbun-mcp.svg)](https://pypi.org/project/porkbun-mcp/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Configuration
+
+Set your Porkbun API credentials as environment variables:
+
+```bash
+export PORKBUN_API_KEY="pk1_..."
+export PORKBUN_SECRET_KEY="sk1_..."
+```
+
+Get your API keys from the [Porkbun API Access page](https://porkbun.com/account/api).
+
+## Usage
+
+Run directly with [uvx](https://docs.astral.sh/uv/) (no installation required):
+
+```bash
+uvx porkbun-mcp
+```
+
+### SSE transport
+
+```bash
+uvx porkbun-mcp --transport sse
+```
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "porkbun": {
+      "command": "uvx",
+      "args": ["porkbun-mcp"],
+      "env": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code / Codex
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "porkbun": {
+      "command": "uvx",
+      "args": ["porkbun-mcp"],
+      "env": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to `.vscode/mcp.json` in your workspace (or use `MCP: Add Server` command):
+
+```json
+{
+  "servers": {
+    "porkbun": {
+      "command": "uvx",
+      "args": ["porkbun-mcp"],
+      "env": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to your `opencode.json` configuration:
+
+```json
+{
+  "mcp": {
+    "porkbun": {
+      "type": "local",
+      "command": ["uvx", "porkbun-mcp"],
+      "environment": {
+        "PORKBUN_API_KEY": "pk1_...",
+        "PORKBUN_SECRET_KEY": "sk1_..."
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### DNS
+
+- `dns_list` - List all DNS records for a domain
+- `dns_get` - Get a specific DNS record by ID
+- `dns_get_by_name_type` - Get DNS records by subdomain and type
+- `dns_create` - Create a new DNS record
+- `dns_edit` - Edit a DNS record by ID
+- `dns_edit_by_name_type` - Edit DNS records by subdomain and type
+- `dns_delete` - Delete a DNS record by ID
+- `dns_delete_by_name_type` - Delete DNS records by subdomain and type
+
+### Domains
+
+- `domains_list` - List all domains in your account
+- `domains_get_nameservers` - Get nameservers for a domain
+- `domains_update_nameservers` - Update nameservers for a domain
+- `domains_get_url_forwards` - Get URL forwarding rules
+- `domains_add_url_forward` - Add a URL forwarding rule
+- `domains_delete_url_forward` - Delete a URL forwarding rule
+- `domains_check_availability` - Check domain availability and pricing
+- `domains_get_glue_records` - Get glue records for a domain
+
+### DNSSEC
+
+- `dnssec_list` - List DNSSEC records for a domain
+- `dnssec_create` - Create a DNSSEC record
+- `dnssec_delete` - Delete a DNSSEC record
+
+### SSL
+
+- `ssl_retrieve` - Retrieve the SSL certificate bundle for a domain
+
+### Pricing
+
+- `pricing_get` - Get pricing for all available TLDs
+
+### Utility
+
+- `ping` - Test API connectivity and get your public IP
+
+## Resources
+
+Browse data via MCP resources:
+
+- `porkbun://domains` - List all domains
+- `porkbun://dns/{domain}` - DNS records for a domain
+- `porkbun://ssl/{domain}` - SSL certificate bundle for a domain
+- `porkbun://pricing` - TLD pricing information
+
+## Prompts
+
+Pre-defined workflows to guide common DNS operations:
+
+- `dns_setup` - Set up basic DNS for a new server (root A + www records)
+- `dns_audit` - Audit DNS configuration for issues (duplicates, missing email records, low TTLs)
+- `email_dns_setup` - Configure email DNS (MX, SPF, DKIM, DMARC)
+- `update_server_ip` - Update DNS records when migrating to a new server IP
+- `subdomain_setup` - Create A/CNAME records for a new subdomain
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run all checks
+make check
+
+# Individual commands
+make lint       # ruff check
+make format     # ruff format
+make typecheck  # ty check
+make test       # pytest with coverage
+```
+
+## License
+
+MIT
+
+<!-- mcp-name: io.github.major/porkbun -->

porkbun_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "porkbun-mcp"
+version = "0.1.1"
+description = "MCP server for Porkbun DNS API"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Major Hayden", email = "major@mhtx.net" }]
+requires-python = ">=3.13"
+keywords = ["mcp", "porkbun", "dns", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: Name Service (DNS)",
+    "Typing :: Typed",
+]
+dependencies = ["fastmcp>=2.14.3", "oinker>=0.1.1", "pydantic-settings>=2.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/major/porkbun-mcp"
+Repository = "https://github.com/major/porkbun-mcp"
+
+[project.scripts]
+porkbun-mcp = "porkbun_mcp:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=6",
+    "pytest-asyncio>=0.25",
+    "respx>=0.22",
+    "ty>=0.0.12",
+    "ruff>=0.9",
+    "radon>=6",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9",
+    "mkdocstrings[python]>=0.29",
+    "pytest-randomly>=4.0.1",
+    "commitizen>=4.0",
+]
+
+[tool.uv.build-backend]
+module-name = "porkbun_mcp"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ASYNC", "D"]
+ignore = [
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+    "D105", # Missing docstring in magic method
+    "D107", # Missing docstring in __init__
+    "UP037", # Quoted type annotations - needed for FastMCP/Pydantic compatibility
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "--cov=porkbun_mcp --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["src/porkbun_mcp"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.ty.environment]
+python-version = "3.14"
+python-platform = "linux"
+extra-paths = ["src"]
+
+[tool.pyright]
+pythonVersion = "3.14"
+pythonPlatform = "Linux"
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "standard"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+tag_format = "v$version"
+update_changelog_on_bump = true
+changelog_file = "CHANGELOG.md"
+changelog_incremental = true
+bump_message = "bump: version $current_version -> $new_version"

porkbun_mcp-0.1.1/src/porkbun_mcp/__init__.py

@@ -0,0 +1,37 @@
+"""Porkbun MCP Server - DNS management via Model Context Protocol."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    """Run the Porkbun MCP server."""
+    parser = argparse.ArgumentParser(
+        description="Porkbun DNS MCP Server",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Environment Variables:
+  PORKBUN_API_KEY       Porkbun API key (required)
+  PORKBUN_SECRET_KEY    Porkbun secret key (required)
+
+Examples:
+  porkbun-mcp
+  porkbun-mcp --transport sse
+""",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="Transport protocol (default: stdio)",
+    )
+    args = parser.parse_args()
+
+    from porkbun_mcp.server import create_server
+
+    server = create_server()
+    server.run(transport=args.transport)
+
+
+__all__ = ["main"]

porkbun_mcp-0.1.1/src/porkbun_mcp/config.py

@@ -0,0 +1,24 @@
+"""Configuration for the Porkbun MCP server."""
+
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class PorkbunMCPSettings(BaseSettings):
+    """Configuration for the Porkbun MCP server.
+
+    Attributes:
+        api_key: Porkbun API key (pk1_...).
+        secret_key: Porkbun secret API key (sk1_...).
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="PORKBUN_",
+        extra="ignore",
+    )
+
+    api_key: str = Field(default="", description="Porkbun API key")
+    secret_key: str = Field(default="", description="Porkbun secret key")

porkbun_mcp-0.1.1/src/porkbun_mcp/context.py

@@ -0,0 +1,20 @@
+"""Context helpers for safe lifespan context access."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastmcp import Context
+from fastmcp.exceptions import ToolError
+
+if TYPE_CHECKING:
+    from oinker import AsyncPiglet
+
+    from porkbun_mcp.server import AppContext
+
+
+def get_piglet(ctx: Context[object, AppContext]) -> AsyncPiglet:
+    """Get AsyncPiglet from context."""
+    if ctx.request_context is None or ctx.request_context.lifespan_context is None:
+        raise ToolError("Server context not available")
+    return ctx.request_context.lifespan_context.piglet

porkbun_mcp-0.1.1/src/porkbun_mcp/errors.py

@@ -0,0 +1,45 @@
+"""Error mapping from oinker to MCP ToolErrors."""
+
+from __future__ import annotations
+
+from fastmcp.exceptions import ToolError
+from oinker import (
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+
+def handle_oinker_error(e: Exception, operation: str) -> ToolError:
+    """Convert oinker exceptions to MCP ToolErrors.
+
+    Args:
+        e: The exception to convert.
+        operation: Description of the operation that failed.
+
+    Returns:
+        A ToolError with an appropriate message.
+    """
+    match e:
+        case AuthenticationError():
+            return ToolError(
+                "Authentication failed. Check PORKBUN_API_KEY and PORKBUN_SECRET_KEY.",
+            )
+        case AuthorizationError():
+            return ToolError(
+                f"Not authorized to {operation}. Ensure API access is enabled for this domain.",
+            )
+        case NotFoundError():
+            return ToolError(f"Not found: {e}")
+        case RateLimitError() as rle:
+            retry_msg = f" Retry in {rle.retry_after}s." if rle.retry_after else ""
+            return ToolError(f"Rate limited.{retry_msg}")
+        case ValidationError():
+            return ToolError(f"Validation error: {e}")
+        case APIError() as ae:
+            return ToolError(f"Porkbun API error: {ae.message}")
+        case _:
+            return ToolError(f"Error during {operation}: {e}")