multify-mcp 0.1.2

package/README.md

@@ -0,0 +1,253 @@
+# multify-mcp
+
+`multify-mcp` is the hosted, first-party MCP for Multify.
+
+It is one MCP server with the full Multify account surface behind it. Contacts, lists, membership actions, and future workspace capabilities all live behind the same server and the same workspace key.
+
+## How Multify MCP works
+
+There is only one hosted Multify MCP server. It lives behind the Multify API host and uses a workspace-scoped MCP key generated inside the app.
+
+This is not Claude-specific. Any client, agent runtime, or connector platform that supports remote MCP over HTTP should use the same hosted endpoint and the same workspace key model.
+
+The fixed hosted endpoint is:
+
+```text
+https://api.multifyco.com/mcp
+```
+
+For normal usage, the user should only need one secret:
+
+1. create a workspace MCP key inside Multify
+2. paste that key into the MCP client
+
+The base URL is fixed by Multify. It should not be something the user has to discover.
+
+## Quick start
+
+### 1. Generate a workspace key
+
+Inside Multify:
+
+1. open `Settings`
+2. open the `MCP` section
+3. create a workspace-scoped key
+4. copy it once
+
+The key belongs to the workspace, not to an individual contact/list tool.
+
+### 2. Connection details for any MCP client
+
+Use this connection contract:
+
+```text
+Name: multify-mcp
+Transport: http
+URL: https://api.multifyco.com/mcp
+Authorization: Bearer YOUR_MULTIFY_MCP_KEY
+```
+
+If your client uses a config file instead of a CLI, the shape is usually equivalent to:
+
+```json
+{
+  "mcpServers": {
+    "multify-mcp": {
+      "transport": "http",
+      "url": "https://api.multifyco.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_MULTIFY_MCP_KEY"
+      }
+    }
+  }
+}
+```
+
+Field names vary between clients, but the invariants do not:
+
+- use the fixed URL `https://api.multifyco.com/mcp`
+- use remote HTTP MCP transport
+- send `Authorization: Bearer ...`
+
+### 3. Claude Code token-only helper
+
+```bash
+npx multify-mcp claude add --token YOUR_MULTIFY_MCP_KEY
+```
+
+That helper wraps the fixed hosted URL for you and runs the Claude Code command. It is a convenience layer, not the primary product model.
+
+Raw Claude Code command:
+
+```bash
+claude mcp add --transport http multify-mcp https://api.multifyco.com/mcp \
+  --header "Authorization: Bearer YOUR_MULTIFY_MCP_KEY"
+```
+
+Claude Code expects auth for remote HTTP MCP servers through `--header`, so the token is carried in the standard `Authorization: Bearer ...` header. The only secret is still the workspace MCP key.
+
+### 4. Connect from custom connectors
+
+Endpoint:
+
+```text
+https://api.multifyco.com/mcp
+```
+
+Header:
+
+```text
+Authorization: Bearer YOUR_MULTIFY_MCP_KEY
+```
+
+### 5. Connect from any remote MCP client
+
+Any client that supports remote MCP over Streamable HTTP can use the same hosted endpoint and the same Bearer token pattern.
+
+There is no extra base URL the user needs to discover or configure manually. The hosted Multify MCP endpoint is fixed on the API host.
+
+## What this MCP exposes
+
+`multify-mcp` is one server with one workspace boundary. It currently exposes Multify workspace operations such as:
+
+- contacts
+- lists
+- list membership actions
+- bulk create/update flows
+
+It does not ask the user to wire Gmail, HubSpot, or other third-party accounts through the MCP itself. Those connections stay inside the Multify app.
+
+## Security model
+
+- keys are workspace-scoped
+- keys are created by workspace owners/admins in the app
+- scopes control what the MCP can do
+- all operations are still enforced by Multify as the source of truth
+- the MCP is an interface over Multify, not a parallel database or permissions system
+
+## Python package
+
+The user-facing Python package is:
+
+```bash
+pip install multify-mcp
+```
+
+Local runtime command:
+
+```bash
+multify-mcp
+```
+
+This repo intentionally treats the Python runtime as one package: `multify-mcp`.
+
+Python helper example:
+
+```python
+from multify_mcp import build_remote_mcp_connection
+
+connection = build_remote_mcp_connection("YOUR_MULTIFY_MCP_KEY")
+
+print(connection.url)
+print(connection.headers["Authorization"])
+print(connection.as_dict())
+```
+
+That helper is generic. It is not tied to Claude or any single MCP client.
+
+## npm package
+
+The public npm package is also `multify-mcp`.
+
+```bash
+npm install multify-mcp
+```
+
+CLI helper:
+
+```bash
+npx multify-mcp claude add --token YOUR_MULTIFY_MCP_KEY
+```
+
+Example:
+
+```ts
+import {
+  buildAuthorizationHeaders,
+  buildRemoteMcpConnection,
+  buildClaudeCodeAddArgs,
+  buildClaudeCodeAddCommand,
+  contactCreateInputSchema,
+  DEFAULT_MULTIFY_MCP_URL,
+} from "multify-mcp";
+
+const headers = buildAuthorizationHeaders(process.env.MULTIFY_MCP_KEY ?? "");
+const connection = buildRemoteMcpConnection(process.env.MULTIFY_MCP_KEY ?? "");
+const args = buildClaudeCodeAddArgs(process.env.MULTIFY_MCP_KEY ?? "");
+const command = buildClaudeCodeAddCommand(process.env.MULTIFY_MCP_KEY ?? "");
+
+const payload = contactCreateInputSchema.parse({
+  list_id: "list_123",
+  full_name: "Ada Lovelace",
+  email: "ada@example.com",
+});
+
+console.log(DEFAULT_MULTIFY_MCP_URL);
+console.log(headers.Authorization);
+console.log(connection);
+console.log(args);
+console.log(command);
+console.log(payload);
+```
+
+The npm side is now one package too. There are no separate public npm packages for contracts and SDK anymore. The generic helper is `buildRemoteMcpConnection`; the Claude helper is optional.
+
+## Local development
+
+Requirements:
+
+- Node 22+
+- pnpm 11+
+- Python 3.12+
+- uv
+
+Bootstrapping:
+
+```bash
+pnpm install
+pnpm build
+pnpm check
+UV_CACHE_DIR=/tmp/uv-cache uv run --group dev ruff check .
+UV_CACHE_DIR=/tmp/uv-cache uv run --group dev pytest tests/py -q
+```
+
+## Release flow
+
+Full release gate:
+
+```bash
+pnpm install
+npm run release:verify
+```
+
+Publish Python:
+
+```bash
+export UV_PUBLISH_TOKEN=...
+npm run release:publish:py
+```
+
+Publish npm helpers:
+
+```bash
+export NPM_TOKEN=...
+npm run release:publish:npm
+```
+
+More detail lives in `docs/publishing.md`.
+
+## Repo structure
+
+- `servers/remote-mcp-py`: hosted Python runtime for `multify-mcp`
+- `src`: TypeScript schemas and helpers shipped in the public npm package `multify-mcp`
+- `tests/py`: auth, HTTP, and tool-service coverage

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+import { buildClaudeCodeAddArgs, buildClaudeCodeAddCommand } from "./index.js";
+function printHelp() {
+    process.stdout.write(`multify-mcp
+
+Usage:
+  multify-mcp claude add --token <workspace-mcp-key> [options]
+
+Options:
+  --token <value>        Workspace MCP key from Multify
+  --scope <value>        Claude config scope: local, user, or project
+  --server-name <value>  Claude MCP server name (default: multify-mcp)
+  --url <value>          Override hosted MCP URL (default: https://api.multifyco.com/mcp)
+  --print                Print the underlying claude command instead of executing it
+  -h, --help             Show help
+
+Examples:
+  multify-mcp claude add --token sk_live_xxx
+  multify-mcp claude add --scope user --token sk_live_xxx
+  multify-mcp claude add --token sk_live_xxx --print
+`);
+}
+function fail(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+function parseClaudeAddArgs(argv) {
+    const parsed = { printOnly: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const current = argv[index];
+        switch (current) {
+            case "--token":
+                parsed.token = argv[index + 1];
+                index += 1;
+                break;
+            case "--scope":
+                parsed.scope = argv[index + 1];
+                index += 1;
+                break;
+            case "--server-name":
+                parsed.serverName = argv[index + 1];
+                index += 1;
+                break;
+            case "--url":
+                parsed.url = argv[index + 1];
+                index += 1;
+                break;
+            case "--print":
+                parsed.printOnly = true;
+                break;
+            case "-h":
+            case "--help":
+                printHelp();
+                process.exit(0);
+            default:
+                fail(`Unknown argument: ${current}`);
+        }
+    }
+    if (!parsed.token?.trim()) {
+        fail("Missing required --token value");
+    }
+    return parsed;
+}
+function run() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+        printHelp();
+        return;
+    }
+    if (args[0] !== "claude" || args[1] !== "add") {
+        fail("Only `multify-mcp claude add` is supported");
+    }
+    const parsed = parseClaudeAddArgs(args.slice(2));
+    const command = buildClaudeCodeAddCommand(parsed.token ?? "", {
+        scope: parsed.scope,
+        serverName: parsed.serverName,
+        url: parsed.url,
+    });
+    if (parsed.printOnly) {
+        process.stdout.write(`${command}\n`);
+        return;
+    }
+    const result = spawnSync("claude", buildClaudeCodeAddArgs(parsed.token ?? "", {
+        scope: parsed.scope,
+        serverName: parsed.serverName,
+        url: parsed.url,
+    }), { stdio: "inherit" });
+    if (result.error) {
+        fail(result.error.message);
+    }
+    process.exit(result.status ?? 0);
+}
+run();