langchain-postbye 1.0.0__tar.gz

langchain_postbye-1.0.0/LICENSE

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

langchain_postbye-1.0.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: langchain-postbye
+Version: 1.0.0
+Summary: LangChain tools for Postbye's public cancellation-guide MCP server: search companies, get cancellation guides and cancellation letters.
+Project-URL: Homepage, https://postbye.com/mcp-server
+Project-URL: Documentation, https://postbye.com/mcp-server
+Project-URL: Repository, https://github.com/postbye-team/postbye-mcp
+Project-URL: Issues, https://github.com/postbye-team/postbye-mcp/issues
+Author-email: Postbye Team <support@postbye.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cancel-subscription,cancellation-letter,langchain,mcp,model-context-protocol,postbye
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: pydantic>=2
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+Postbye (postbye.com) cancels subscriptions for you by mailing a formal cancellation letter, tracked until it is delivered.
+
+# langchain-postbye
+
+LangChain tools for Postbye's public, read-only MCP server at <https://postbye.com/mcp> (Streamable HTTP, no API key, no account). Give your agent the ability to find a company's cancellation rules, mailing address and a ready-to-send cancellation letter.
+
+The package calls the server with plain JSON-RPC over HTTP, so it needs no MCP client library. Tools support both sync and async use.
+
+## Install
+
+```bash
+pip install langchain-postbye
+```
+
+## Quickstart
+
+```python
+from langchain_postbye import PostbyeToolkit
+
+tools = PostbyeToolkit().get_tools()   # or: from langchain_postbye import get_tools
+
+search = next(t for t in tools if t.name == "postbye_search_companies")
+print(search.invoke({"query": "planet fitness", "limit": 3}))
+```
+
+### With a LangGraph agent
+
+```python
+from langchain_postbye import get_tools
+from langgraph.prebuilt import create_react_agent
+
+agent = create_react_agent("anthropic:claude-sonnet-4-5", get_tools())
+result = agent.invoke(
+    {"messages": [("user", "How do I cancel my Planet Fitness membership? Draft the letter.")]}
+)
+print(result["messages"][-1].content)
+```
+
+## Tools
+
+| LangChain tool | MCP tool | What it does |
+| --- | --- | --- |
+| `postbye_search_companies` | `search_companies` | Find a company by name; returns its slug, category and how it takes cancellations. |
+| `postbye_get_cancellation_guide` | `get_cancellation_guide` | Notice period, traps to check, billing-partner notes, sources and mailing address(es) for one company. |
+| `postbye_get_cancellation_letter` | `get_cancellation_letter` | A plain-text cancellation letter plus where to send it. Optional `customer_name` and `account_number`. Nothing is stored. |
+| `postbye_list_categories` | `list_categories` | Guide categories with the number of guides in each. |
+
+## Options
+
+```python
+PostbyeToolkit(url="https://postbye.com/mcp", timeout=30.0).get_tools()
+```
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest   # live smoke tests: tools/list must return the 4 tools
+```
+
+## Links
+
+- Homepage and docs: <https://postbye.com/mcp-server>
+- Repository: <https://github.com/postbye-team/postbye-mcp>
+- Support: support@postbye.com
+
+## License
+
+MIT. Author: Postbye Team.

langchain_postbye-1.0.0/README.md

@@ -0,0 +1,69 @@
+Postbye (postbye.com) cancels subscriptions for you by mailing a formal cancellation letter, tracked until it is delivered.
+
+# langchain-postbye
+
+LangChain tools for Postbye's public, read-only MCP server at <https://postbye.com/mcp> (Streamable HTTP, no API key, no account). Give your agent the ability to find a company's cancellation rules, mailing address and a ready-to-send cancellation letter.
+
+The package calls the server with plain JSON-RPC over HTTP, so it needs no MCP client library. Tools support both sync and async use.
+
+## Install
+
+```bash
+pip install langchain-postbye
+```
+
+## Quickstart
+
+```python
+from langchain_postbye import PostbyeToolkit
+
+tools = PostbyeToolkit().get_tools()   # or: from langchain_postbye import get_tools
+
+search = next(t for t in tools if t.name == "postbye_search_companies")
+print(search.invoke({"query": "planet fitness", "limit": 3}))
+```
+
+### With a LangGraph agent
+
+```python
+from langchain_postbye import get_tools
+from langgraph.prebuilt import create_react_agent
+
+agent = create_react_agent("anthropic:claude-sonnet-4-5", get_tools())
+result = agent.invoke(
+    {"messages": [("user", "How do I cancel my Planet Fitness membership? Draft the letter.")]}
+)
+print(result["messages"][-1].content)
+```
+
+## Tools
+
+| LangChain tool | MCP tool | What it does |
+| --- | --- | --- |
+| `postbye_search_companies` | `search_companies` | Find a company by name; returns its slug, category and how it takes cancellations. |
+| `postbye_get_cancellation_guide` | `get_cancellation_guide` | Notice period, traps to check, billing-partner notes, sources and mailing address(es) for one company. |
+| `postbye_get_cancellation_letter` | `get_cancellation_letter` | A plain-text cancellation letter plus where to send it. Optional `customer_name` and `account_number`. Nothing is stored. |
+| `postbye_list_categories` | `list_categories` | Guide categories with the number of guides in each. |
+
+## Options
+
+```python
+PostbyeToolkit(url="https://postbye.com/mcp", timeout=30.0).get_tools()
+```
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest   # live smoke tests: tools/list must return the 4 tools
+```
+
+## Links
+
+- Homepage and docs: <https://postbye.com/mcp-server>
+- Repository: <https://github.com/postbye-team/postbye-mcp>
+- Support: support@postbye.com
+
+## License
+
+MIT. Author: Postbye Team.

langchain_postbye-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-postbye"
+version = "1.0.0"
+description = "LangChain tools for Postbye's public cancellation-guide MCP server: search companies, get cancellation guides and cancellation letters."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Postbye Team", email = "support@postbye.com" }]
+keywords = ["langchain", "mcp", "model-context-protocol", "postbye", "cancel-subscription", "cancellation-letter", "agents"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "langchain-core>=0.3",
+  "httpx>=0.25",
+  "pydantic>=2",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://postbye.com/mcp-server"
+Documentation = "https://postbye.com/mcp-server"
+Repository = "https://github.com/postbye-team/postbye-mcp"
+Issues = "https://github.com/postbye-team/postbye-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_postbye"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]

langchain_postbye-1.0.0/src/langchain_postbye/__init__.py

@@ -0,0 +1,19 @@
+"""LangChain tools for Postbye's public, read-only cancellation-guide MCP server.
+
+Postbye (postbye.com) cancels subscriptions for you by mailing a formal
+cancellation letter, tracked until it is delivered.
+"""
+
+from langchain_postbye.client import MCP_URL, PostbyeClient, PostbyeError
+from langchain_postbye.toolkit import PostbyeToolkit, get_tools
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "MCP_URL",
+    "PostbyeClient",
+    "PostbyeError",
+    "PostbyeToolkit",
+    "get_tools",
+    "__version__",
+]

langchain_postbye-1.0.0/src/langchain_postbye/client.py

@@ -0,0 +1,95 @@
+"""Minimal JSON-RPC client for the Postbye MCP server (Streamable HTTP, no API key)."""
+
+from __future__ import annotations
+
+import itertools
+import json
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+MCP_URL = "https://postbye.com/mcp"
+PROTOCOL_VERSION = "2025-03-26"
+
+
+class PostbyeError(RuntimeError):
+    """Raised when the Postbye MCP server returns a JSON-RPC error or a tool error."""
+
+
+def _parse_body(response: httpx.Response) -> Dict[str, Any]:
+    """Return the JSON-RPC message from a JSON or a single-event SSE response."""
+    content_type = response.headers.get("content-type", "")
+    if "text/event-stream" in content_type:
+        for line in response.text.splitlines():
+            if line.startswith("data:"):
+                data = line[5:].strip()
+                if data:
+                    return json.loads(data)
+        raise PostbyeError("Empty event stream from the Postbye MCP server")
+    return response.json()
+
+
+def _unwrap(message: Dict[str, Any]) -> Any:
+    if "error" in message:
+        err = message["error"]
+        raise PostbyeError(f"{err.get('message', 'MCP error')} (code {err.get('code')})")
+    return message.get("result")
+
+
+def _tool_text(result: Dict[str, Any]) -> str:
+    text = "\n".join(
+        block.get("text", "") for block in result.get("content", []) if block.get("type") == "text"
+    ).strip()
+    if result.get("isError"):
+        raise PostbyeError(text or "Postbye tool call failed")
+    return text
+
+
+class PostbyeClient:
+    """Calls tools on https://postbye.com/mcp with plain JSON-RPC over HTTP.
+
+    The server is stateless and read-only, so no session or authentication is needed.
+    """
+
+    def __init__(self, url: str = MCP_URL, timeout: float = 30.0) -> None:
+        self.url = url
+        self.timeout = timeout
+        self._ids = itertools.count(1)
+        self._headers = {
+            "content-type": "application/json",
+            "accept": "application/json, text/event-stream",
+            "mcp-protocol-version": PROTOCOL_VERSION,
+            "user-agent": "langchain-postbye/1.0.0",
+        }
+
+    def _payload(self, method: str, params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"jsonrpc": "2.0", "id": next(self._ids), "method": method}
+        if params is not None:
+            payload["params"] = params
+        return payload
+
+    def _request(self, method: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        with httpx.Client(timeout=self.timeout, headers=self._headers) as http:
+            response = http.post(self.url, json=self._payload(method, params))
+            response.raise_for_status()
+            return _unwrap(_parse_body(response))
+
+    async def _arequest(self, method: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        async with httpx.AsyncClient(timeout=self.timeout, headers=self._headers) as http:
+            response = await http.post(self.url, json=self._payload(method, params))
+            response.raise_for_status()
+            return _unwrap(_parse_body(response))
+
+    def list_tools(self) -> List[Dict[str, Any]]:
+        return self._request("tools/list")["tools"]
+
+    async def alist_tools(self) -> List[Dict[str, Any]]:
+        return (await self._arequest("tools/list"))["tools"]
+
+    def call_tool(self, name: str, arguments: Optional[Dict[str, Any]] = None) -> str:
+        return _tool_text(self._request("tools/call", {"name": name, "arguments": arguments or {}}))
+
+    async def acall_tool(self, name: str, arguments: Optional[Dict[str, Any]] = None) -> str:
+        return _tool_text(
+            await self._arequest("tools/call", {"name": name, "arguments": arguments or {}})
+        )

langchain_postbye-1.0.0/src/langchain_postbye/toolkit.py

@@ -0,0 +1,104 @@
+"""LangChain tool definitions for the four Postbye MCP tools."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from langchain_core.tools import BaseTool, BaseToolkit, StructuredTool
+from pydantic import BaseModel, ConfigDict, Field
+
+from langchain_postbye.client import MCP_URL, PostbyeClient
+
+
+class SearchCompaniesInput(BaseModel):
+    query: str = Field(min_length=1, max_length=100, description="Company or service name, or part of it.")
+    limit: int = Field(default=5, ge=1, le=10, description="Maximum number of matches (1 to 10).")
+
+
+class CompanySlugInput(BaseModel):
+    slug: str = Field(min_length=1, max_length=100, description='Company slug from postbye_search_companies, for example "netflix".')
+
+
+class CancellationLetterInput(BaseModel):
+    slug: str = Field(min_length=1, max_length=100, description="Company slug from postbye_search_companies.")
+    customer_name: Optional[str] = Field(default=None, max_length=100, description="Your full name as it appears on the account (optional).")
+    account_number: Optional[str] = Field(default=None, max_length=64, description="Account, membership or reference number (optional).")
+
+
+class NoInput(BaseModel):
+    pass
+
+
+# (langchain tool name, MCP tool name, args schema, description)
+_TOOLS = [
+    (
+        "postbye_search_companies",
+        "search_companies",
+        SearchCompaniesInput,
+        "Find companies by name (for example \"netflix\" or \"planet fitness\") among the subscriptions and "
+        "memberships Postbye has a cancellation guide for. Returns each match's slug, category, how the company "
+        "takes cancellations and the guide URL. Use the slug with postbye_get_cancellation_guide.",
+    ),
+    (
+        "postbye_get_cancellation_guide",
+        "get_cancellation_guide",
+        CompanySlugInput,
+        "How to cancel one company's subscription or membership: how it takes cancellations, the notice period, "
+        "the traps to check first, billing-partner notes, sources, when the facts were verified, the mailing "
+        "address(es) on file and the guide and address page URLs.",
+    ),
+    (
+        "postbye_get_cancellation_letter",
+        "get_cancellation_letter",
+        CancellationLetterInput,
+        "A plain-text cancellation letter for one company, built from the same template as Postbye's free letter "
+        "tool, plus where to send it. Fields not supplied stay as [bracketed placeholders] to fill in. Nothing is stored.",
+    ),
+    (
+        "postbye_list_categories",
+        "list_categories",
+        NoInput,
+        "The category hubs of the Postbye cancellation guides (streaming, gyms, phone and internet, insurance and "
+        "more) with the number of guides in each and the hub URL.",
+    ),
+]
+
+
+def _make_tool(client: PostbyeClient, name: str, mcp_name: str, schema: type, description: str) -> StructuredTool:
+    def _run(**kwargs: object) -> str:
+        return client.call_tool(mcp_name, {k: v for k, v in kwargs.items() if v is not None})
+
+    async def _arun(**kwargs: object) -> str:
+        return await client.acall_tool(mcp_name, {k: v for k, v in kwargs.items() if v is not None})
+
+    return StructuredTool(
+        name=name,
+        description=description,
+        args_schema=schema,
+        func=_run,
+        coroutine=_arun,
+        metadata={"mcp_tool": mcp_name, "source": MCP_URL},
+    )
+
+
+class PostbyeToolkit(BaseToolkit):
+    """Toolkit exposing Postbye's four read-only cancellation tools.
+
+    Example:
+        >>> from langchain_postbye import PostbyeToolkit
+        >>> tools = PostbyeToolkit().get_tools()
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    url: str = MCP_URL
+    timeout: float = 30.0
+
+    def get_tools(self) -> List[BaseTool]:
+        client = PostbyeClient(url=self.url, timeout=self.timeout)
+        return [_make_tool(client, *spec) for spec in _TOOLS]
+
+
+def get_tools(url: str = MCP_URL, timeout: float = 30.0) -> List[BaseTool]:
+    """Return the four Postbye tools as LangChain tools."""
+    return PostbyeToolkit(url=url, timeout=timeout).get_tools()

langchain_postbye-1.0.0/tests/test_smoke.py

@@ -0,0 +1,33 @@
+"""Live smoke tests against https://postbye.com/mcp."""
+
+from langchain_postbye import PostbyeClient, PostbyeToolkit, get_tools
+
+EXPECTED = {
+    "get_cancellation_guide",
+    "get_cancellation_letter",
+    "list_categories",
+    "search_companies",
+}
+
+
+def test_tools_list_returns_four_tools():
+    tools = PostbyeClient().list_tools()
+    assert {t["name"] for t in tools} == EXPECTED
+
+
+def test_langchain_tools_match_server():
+    tools = get_tools()
+    assert len(tools) == 4
+    assert {t.metadata["mcp_tool"] for t in tools} == EXPECTED
+    assert len(PostbyeToolkit().get_tools()) == 4
+
+
+def test_search_tool_invokes_live():
+    search = next(t for t in get_tools() if t.name == "postbye_search_companies")
+    out = search.invoke({"query": "netflix", "limit": 1})
+    assert "netflix" in out.lower()
+
+
+def test_list_categories_invokes_live():
+    cats = next(t for t in get_tools() if t.name == "postbye_list_categories")
+    assert cats.invoke({}).strip()