@postbye/mcp 0.0.0-stage → 1.0.0

package/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.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+Postbye (postbye.com) cancels subscriptions for you by mailing a formal cancellation letter, tracked until it is delivered.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @postbye/mcp
+
+A small stdio proxy that connects local MCP clients (Claude Desktop, Cursor, VS Code and others) to Postbye's public, read-only MCP server at <https://postbye.com/mcp>. No API key and no account are needed.
+
+The server exposes four tools:
+
+| Tool | What it does |
+| --- | --- |
+| `search_companies` | Find a company by name among the subscriptions and memberships Postbye has a cancellation guide for. Returns the slug, category and how the company takes cancellations. |
+| `get_cancellation_guide` | How one company takes cancellations: notice period, traps to check first, billing-partner notes, sources, verification date and mailing address(es). |
+| `get_cancellation_letter` | A plain-text cancellation letter for one company plus where to send it. Nothing is stored. |
+| `list_categories` | The guide categories (streaming, gyms, phone and internet, insurance and more) with guide counts. |
+
+More details: <https://postbye.com/mcp-server>
+
+## Install
+
+Run it without installing anything:
+
+```bash
+npx -y @postbye/mcp
+```
+
+Or install it globally:
+
+```bash
+npm install -g @postbye/mcp
+postbye-mcp
+```
+
+Requires Node.js 18 or newer.
+
+## Claude Desktop
+
+Add this to `claude_desktop_config.json` (Settings, Developer, Edit Config), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "postbye": {
+      "command": "npx",
+      "args": ["-y", "@postbye/mcp"]
+    }
+  }
+}
+```
+
+## Cursor
+
+Add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "postbye": {
+      "command": "npx",
+      "args": ["-y", "@postbye/mcp"]
+    }
+  }
+}
+```
+
+## VS Code
+
+Add this to `.vscode/mcp.json` in your workspace (or run "MCP: Open User Configuration"):
+
+```json
+{
+  "servers": {
+    "postbye": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@postbye/mcp"]
+    }
+  }
+}
+```
+
+## Remote clients
+
+Clients that speak Streamable HTTP can skip this package and connect straight to `https://postbye.com/mcp`.
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `POSTBYE_MCP_URL` | `https://postbye.com/mcp` | Override the upstream MCP endpoint. |
+
+## Development
+
+```bash
+npm install
+npm test   # live smoke test: 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.

package/bin/postbye-mcp.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createProxy, VERSION } from "../src/proxy.js";
+
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  console.log(VERSION);
+  process.exit(0);
+}
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(
+    "postbye-mcp: stdio MCP proxy for https://postbye.com/mcp (set POSTBYE_MCP_URL to override).\nDocs: https://postbye.com/mcp-server",
+  );
+  process.exit(0);
+}
+
+try {
+  const { server, client } = await createProxy();
+  await server.connect(new StdioServerTransport());
+  const shutdown = async () => {
+    await Promise.allSettled([server.close(), client.close()]);
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  process.stdin.on("close", shutdown);
+} catch (err) {
+  console.error(`postbye-mcp: could not reach the Postbye MCP server: ${err?.message ?? err}`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@postbye/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Stdio MCP proxy for the Postbye cancellation-guide server: search companies, get cancellation guides and ready-to-send cancellation letters from Claude Desktop, Cursor or VS Code.",
+  "keywords": ["mcp", "model-context-protocol", "postbye", "cancel-subscription", "cancellation-letter", "claude", "cursor"],
+  "homepage": "https://postbye.com/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/postbye-team/postbye-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/postbye-team/postbye-mcp/issues",
+    "email": "support@postbye.com"
+  },
+  "license": "MIT",
+  "author": "Postbye Team <support@postbye.com>",
+  "type": "module",
+  "bin": {
+    "postbye-mcp": "bin/postbye-mcp.js"
+  },
+  "main": "src/proxy.js",
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "test": "node --test test/smoke.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2"
+  }
+}

package/src/proxy.js

@@ -0,0 +1,40 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+export const DEFAULT_URL = "https://postbye.com/mcp";
+export const VERSION = "1.0.0";
+
+/**
+ * Connect to the remote Postbye MCP server and return a stdio-ready Server that
+ * forwards tools/list and tools/call to it.
+ */
+export async function createProxy(url = process.env.POSTBYE_MCP_URL || DEFAULT_URL) {
+  const client = new Client({ name: "postbye-mcp", version: VERSION });
+  try {
+    await client.connect(new StreamableHTTPClientTransport(new URL(url)));
+  } catch {
+    // one retry for a transient network error
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    await client.connect(new StreamableHTTPClientTransport(new URL(url)));
+  }
+
+  const server = new Server(
+    { name: "postbye", version: VERSION },
+    {
+      capabilities: { tools: {} },
+      instructions: client.getInstructions(),
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => client.listTools());
+  server.setRequestHandler(CallToolRequestSchema, async (request) =>
+    client.callTool(request.params),
+  );
+
+  return { server, client };
+}