@getsales/outreach-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GetSales
+
+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,85 @@
-# Temporary Holding Version
+# GetSales: Outreach MCP Server
 
-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.
+`@getsales/outreach-mcp` connects an MCP client that can only start a command (Claude Desktop, Cursor, an agent runtime) to the hosted GetSales server at `https://mcp2.getsales.io/mcp/public`. It starts [mcp-remote](https://github.com/punkpeye/mcp-remote) and nothing else: the tools run on the server, which keeps each call inside your workspace.
+
+GetSales is LinkedIn and email outreach for agencies and GTM teams, in one app. Describe who you sell to, and GetSales finds the people and their work emails, scores them and writes the first lines, and every reply comes back to a team inbox.
+
+Through the server an AI agent works with the tables of people and companies, the enrichment columns, the workflows, the inbox with the AI SDR's drafts, the tasks, the website signals and the webhooks of a GetSales workspace. It sees four meta-tools: `search_tools` finds a tool by what it does, `describe_tool` returns the definition, `call_tool` runs the tool, and `list_toolsets` maps the catalog. A tool the server marks dangerous, such as a delete, a cancel or a subscription change, answers a preview and a `commit_token` first, and runs only when the same call comes back with that token as the confirm.
+
+## Start it from your client
+
+Claude Desktop, in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "getsales": {
+      "command": "npx",
+      "args": ["-y", "@getsales/outreach-mcp"]
+    }
+  }
+}
+```
+
+Claude Code:
+
+```
+claude mcp add getsales -- npx -y @getsales/outreach-mcp
+```
+
+The first start opens the GetSales consent page in a browser. With no account yet, [sign up](https://getsales.io/signup/) before that step or from the page itself. A client that speaks streamable HTTP needs no launcher: give it `https://mcp2.getsales.io/mcp/public`, and it runs the same sign-in on its own.
+
+## Sign in with OAuth or with a key
+
+The launcher picks one way per start and never mixes them.
+
+- **OAuth, when `GETSALES_API_KEY` is not set.** mcp-remote gets a 401 with a `WWW-Authenticate` challenge, reads the authorization server from the protected-resource document (`https://mcp2.getsales.io/.well-known/oauth-protected-resource`), registers itself there and runs the consent in your browser with PKCE. The tokens stay in `~/.mcp-auth`: treat that folder like a password store.
+- **A key, when `GETSALES_API_KEY` is set.** Make the key in the app under Settings, API keys. The launcher tests it with one `initialize` request, then hands mcp-remote a header that names the variable, `Authorization: Bearer ${GETSALES_API_KEY}`, and mcp-remote fills the value in from its environment. So the key sits on no command line and in no log line, and no browser opens. A key the server turns down (401: wrong, revoked or expired) or a workspace whose subscription is on hold (402) stops the launcher at once, with the reason on stderr. When the test cannot reach the server, the launcher says so and starts anyway.
+
+Why never both: a fixed bearer and OAuth on one connection work against each other. mcp-remote would answer a refused key by starting OAuth, and the fixed header would then replace each token that flow got.
+
+```json
+{
+  "mcpServers": {
+    "getsales": {
+      "command": "npx",
+      "args": ["-y", "@getsales/outreach-mcp"],
+      "env": { "GETSALES_API_KEY": "gs_live_..." }
+    }
+  }
+}
+```
+
+## Settings
+
+- `GETSALES_API_KEY`: the key for the key mode. Leave it unset for OAuth, except in the Docker image, which needs it.
+- `GETSALES_MCP_URL`: another endpoint. The default is `https://mcp2.getsales.io/mcp/public`.
+- Arguments after the command go to mcp-remote: `--debug` writes a detailed log to `~/.mcp-auth`, `--host` sets the callback hostname, and `--allow-http` accepts a plain-http endpoint.
+
+## The Docker image
+
+`getsalesio/outreach-mcp` runs this launcher in a container, for a host without Node.js, and signs in with a key only. Pass `-e` with the bare variable name and docker copies the value from the client's `env` block, so the key stays off the docker command line:
+
+```json
+{
+  "mcpServers": {
+    "getsales": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "GETSALES_API_KEY", "getsalesio/outreach-mcp"],
+      "env": { "GETSALES_API_KEY": "gs_live_..." }
+    }
+  }
+}
+```
+
+From a shell, export the key first, then run `docker run -i --rm -e GETSALES_API_KEY getsalesio/outreach-mcp`.
+
+OAuth cannot finish in a container. After the consent page your browser comes back to `localhost`, which is your machine, while mcp-remote waits for that answer on the container's own loopback. So without a key the container stops at once and says why. For OAuth, run the launcher with npx or give the client the URL.
+
+## Where to read more
+
+- Keys and OAuth: [docs.getsales.io/authentication](https://docs.getsales.io/authentication)
+- The API reference: [docs.getsales.io](https://docs.getsales.io)
+- The product: [getsales.io/ai-sales-assistant](https://getsales.io/ai-sales-assistant/)
+
+GetSales is an independent product and is not affiliated with, endorsed by, or sponsored by LinkedIn Corporation. LinkedIn and the LinkedIn logo are trademarks of LinkedIn Corporation. Use of GetSales is at your own risk and subject to the applicable third-party platform terms.

package/bin/cli.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+'use strict';
+
+// getsales-outreach-mcp
+//
+// For an MCP client that can only start a command: it reaches the hosted
+// GetSales workspace server through mcp-remote, the one dependency pinned in
+// package.json. The tools run on the server, never here. The image built from
+// the repository's Dockerfile starts this same file.
+//
+// How it signs in:
+//
+//   GETSALES_API_KEY unset   mcp-remote does OAuth. It follows the server's
+//                            401 challenge to the GetSales consent page and
+//                            keeps the tokens in ~/.mcp-auth.
+//   GETSALES_API_KEY set     the key is the bearer, and no browser opens. One
+//                            initialize request tests the key first, so a dead
+//                            key stops here with a plain line on stderr. Left
+//                            to mcp-remote, a refused bearer would start the
+//                            OAuth flow, and the fixed header would then
+//                            replace every token that flow obtained.
+//
+// Where the key travels: into the test request this process sends, and into
+// the environment of mcp-remote. The command line of mcp-remote carries the
+// literal text ${GETSALES_API_KEY}, which mcp-remote fills in from its own
+// environment after it has logged its arguments. A process list and the
+// client's log of this server's stderr show the variable's name, never its
+// value. Nothing this file prints quotes the key, or the text of an error that
+// could quote it.
+//
+// Test seam: with GETSALES_MCP_DRY_RUN=1 the file prints what it would start,
+// as one JSON line on stdout, after the key test and instead of the bridge.
+// tests/launcher-kit.test.mjs in the repository drives it.
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const manifest = require('../package.json');
+
+const DEFAULT_ENDPOINT = 'https://mcp2.getsales.io/mcp/public';
+const KEY_HEADER = 'Authorization: Bearer ${GETSALES_API_KEY}';
+const RELAYED = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+const CHECK_SECONDS = 10;
+
+const REFUSED = {
+  401: [
+    'the server turned GETSALES_API_KEY down (HTTP 401): the key is wrong, revoked or past its expiry date.',
+    'Make a new key in the app under Settings, API keys, or remove GETSALES_API_KEY to sign in through the browser.',
+  ],
+  402: [
+    'GETSALES_API_KEY is a working key, but the subscription of its workspace is on hold (HTTP 402).',
+    'Bring the subscription back in the app, then start this again.',
+  ],
+};
+
+const binName = Object.keys(manifest.bin)[0];
+const say = (line) => process.stderr.write(`${binName}: ${line}\n`);
+
+// A short reason for a failure, built only from fixed names and codes: the
+// message of a network error can repeat the request it failed on.
+function reasonOf(error) {
+  if (!error) return 'unknown error';
+  if (error.name === 'TimeoutError' || error.name === 'AbortError') return `no answer within ${CHECK_SECONDS} seconds`;
+  for (const code of [error.code, error.cause && error.cause.code]) {
+    if (typeof code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(code)) return code;
+  }
+  return typeof error.name === 'string' ? error.name : 'unknown error';
+}
+
+function isUrl(text) {
+  try {
+    new URL(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function initializeBody() {
+  return JSON.stringify({
+    jsonrpc: '2.0',
+    id: 'key-check',
+    method: 'initialize',
+    params: {
+      protocolVersion: '2025-03-26',
+      capabilities: {},
+      clientInfo: { name: manifest.name, version: manifest.version },
+    },
+  });
+}
+
+// true: start the bridge. false: the server refused the key, and the reason
+// is on stderr already.
+async function keyAccepted(endpoint, key) {
+  let response;
+  try {
+    response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${key}`,
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+      },
+      body: initializeBody(),
+      signal: AbortSignal.timeout(CHECK_SECONDS * 1000),
+    });
+  } catch (error) {
+    say(`could not test GETSALES_API_KEY on ${new URL(endpoint).host} (${reasonOf(error)}). Starting anyway: the first call will tell.`);
+    return true;
+  }
+  // Only the status counts. The body is dropped unread, so an answer that
+  // streams cannot hold the start back.
+  if (response.body) await response.body.cancel().catch(() => undefined);
+  const lines = REFUSED[response.status];
+  if (lines) lines.forEach(say);
+  return !lines;
+}
+
+// The file that mcp-remote's package.json names as its command.
+function bridgeEntry() {
+  const packageFile = require.resolve('mcp-remote/package.json');
+  return path.join(path.dirname(packageFile), require(packageFile).bin['mcp-remote']);
+}
+
+function startBridge(args, env) {
+  const bridge = spawn(process.execPath, args, { stdio: 'inherit', env });
+  const relay = (signal) => bridge.kill(signal);
+  RELAYED.forEach((signal) => process.on(signal, relay));
+  bridge.once('error', (error) => {
+    say(`mcp-remote did not start (${reasonOf(error)}).`);
+    process.exitCode = 1;
+  });
+  bridge.once('exit', (code, signal) => {
+    RELAYED.forEach((name) => process.removeListener(name, relay));
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code === null ? 0 : code;
+  });
+}
+
+async function main() {
+  const endpoint = process.env.GETSALES_MCP_URL || DEFAULT_ENDPOINT;
+  if (!isUrl(endpoint)) {
+    say('GETSALES_MCP_URL is not a URL.');
+    return 1;
+  }
+
+  const env = { ...process.env };
+  const key = (env.GETSALES_API_KEY || '').trim();
+  if (key) {
+    if (!/^[\x21-\x7e]+$/.test(key)) {
+      say('GETSALES_API_KEY holds a space, a line break or another character a header cannot carry. Copy the key again from the app (Settings, API keys).');
+      return 1;
+    }
+    env.GETSALES_API_KEY = key;
+    if (!(await keyAccepted(endpoint, key))) return 1;
+  } else {
+    delete env.GETSALES_API_KEY;
+  }
+
+  let entry;
+  try {
+    entry = bridgeEntry();
+  } catch (error) {
+    say(`the mcp-remote package is missing (${reasonOf(error)}). Install ${manifest.name} again.`);
+    return 1;
+  }
+
+  const args = [entry, endpoint, '--transport', 'http-only', ...(key ? ['--header', KEY_HEADER] : []), ...process.argv.slice(2)];
+  if (process.env.GETSALES_MCP_DRY_RUN === '1') {
+    process.stdout.write(`${JSON.stringify({ command: process.execPath, args })}\n`);
+    return 0;
+  }
+  startBridge(args, env);
+  return undefined;
+}
+
+// An exit code is set, never process.exit(), so the lines written to a pipe
+// above reach it whole before the process ends. An unexpected failure is
+// reported by its name alone, for the reason reasonOf gives.
+main().then(
+  (code) => {
+    if (code !== undefined) process.exitCode = code;
+  },
+  (error) => {
+    say(`stopped (${reasonOf(error)}).`);
+    process.exitCode = 1;
+  },
+);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@getsales/outreach-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Connects a stdio MCP client to the hosted GetSales outreach MCP server. An AI agent works a GetSales workspace through it: tables of people and companies, enrichment, workflows, the inbox, tasks and signals, behind four MCP tools, and the tools the server marks dangerous preview before they run.",
+  "author": "GetSales (https://getsales.io/)",
+  "mcpName": "io.getsales/outreach-mcp",
+  "bin": {
+    "getsales-outreach-mcp": "bin/cli.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getsales-io/outreach-mcp.git",
+    "directory": "npm"
+  },
+  "homepage": "https://getsales.io/ai-sales-assistant/",
+  "bugs": {
+    "url": "https://github.com/getsales-io/outreach-mcp/issues"
+  },
+  "keywords": [
+    "outreach",
+    "cold-email",
+    "sales-engagement",
+    "ai-sdr",
+    "enrichment",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "mcp-remote": "0.1.38"
+  }
+}