outrank-cli 0.9.0 → 0.10.0

package/README.md

@@ -115,6 +115,10 @@ outrank-cli auth logout --profile globex                          # clears only
 
 Requirements: Node.js 18+ (check with `node --version`), an Outrank API key from <https://www.outrank.so/dashboard/settings/api-keys>, and an organization on the current Outrank app version. The same guide is on the web at <https://www.outrank.so/docs/mcp>.
 
+### Remote server
+
+Outrank also hosts the same tools at `https://www.outrank.so/api/mcp` (Streamable HTTP), for clients that connect to a URL instead of starting a command, such as Claude, ChatGPT or Cursor. Sign in with OAuth when the client asks, or send an API key as `Authorization: Bearer outr_live_...`. The hosted server always uses the `auto` toolsets, has no read-only switch and takes images as base64 only: it never reads a file. It is built from `createRemoteMcpServer` in `src/adapters/mcp/remote.js`, which takes the key, the Outrank origin and, optionally, the organization's `auth whoami` envelope so it does not ask for it again.
+
 ### Claude Code
 
 Run this in the project folder (macOS, Linux, WSL, or the Windows Command Prompt):

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "outrank-cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
+  "mcpName": "so.outrank/outrank",
   "description": "Agent-first CLI and MCP server for the Outrank agent API",
   "type": "module",
   "files": [

package/src/adapters/mcp/descriptions.js

@@ -80,7 +80,15 @@ export const describeField = (spec, name, field) => {
   return `${text}${defaultNote(field)}`;
 };
 
+const TITLE_WORD_SEPARATOR = /[.-]/;
+
+export const toolTitle = (spec) => {
+  const text = spec.id.split(TITLE_WORD_SEPARATOR).join(' ');
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+};
+
 export const toolAnnotations = (spec) => ({
+  title: toolTitle(spec),
   readOnlyHint: spec.kind === CommandKind.READ || spec.kind === CommandKind.LOCAL,
   destructiveHint: spec.kind === CommandKind.DESTRUCTIVE || spec.kind === CommandKind.MONEY,
   idempotentHint: spec.kind === CommandKind.READ || spec.kind === CommandKind.LOCAL,

package/src/adapters/mcp/input.js

@@ -17,6 +17,7 @@ const SCHEMA_DIALECT_KEY = '$schema';
 const BROAD_UPLOAD_DIR_GUIDANCE =
   'Ask the human to restart the server with --upload-dir <a directory that holds only the images to upload>, or ' +
   'pass the image as base64 with a file name instead.';
+const REMOTE_UPLOAD_GUIDANCE = 'Pass the image as base64 with a file name instead.';
 const UPLOAD_DIR_GUIDANCE =
   'Ask the human to create the upload directory or to restart the server with --upload-dir <existing directory>.';
 
@@ -39,7 +40,9 @@ const describeFilePath = (names, uploads) =>
 const imageShape = (z, name, uploads) => {
   const names = imageArgumentNames(name);
   return {
-    [names.filePath]: z.string().min(1).describe(describeFilePath(names, uploads)).optional(),
+    ...(uploads.dir === null
+      ? {}
+      : { [names.filePath]: z.string().min(1).describe(describeFilePath(names, uploads)).optional() }),
     [names.base64]: z
       .string()
       .min(1)
@@ -129,6 +132,9 @@ export const parseToolArguments = (toolInput, args) => {
 };
 
 const readImageFromPath = async (filePath, uploads) => {
+  if (uploads.dir === null) {
+    throw usageError('Uploads from a file path are not available on the remote server.', REMOTE_UPLOAD_GUIDANCE);
+  }
   if (uploads.problem) {
     throw usageError(
       `Uploads from a file path are disabled because the upload directory is too broad (${uploads.problem}).`,

package/src/adapters/mcp/instructions.js

@@ -33,6 +33,7 @@ const WORKFLOW_RULES =
 const SETUP_TOOLS_NOTE = ' Setup tools of every area stay listed.';
 const REFRESH_NOTE = ' The tool list refreshes on its own once the organization lookup succeeds.';
 const ENABLE_HINT = ' The human can change this with --toolsets <names|all> and a restart.';
+const REMOTE_ENABLE_HINT = ' A toolset the organization gets later shows up after the client reconnects.';
 const READ_ONLY_NOTE = ' The server runs read-only: only read tools are listed.';
 const CONFIGURATION_REASON = 'left out by the server configuration';
 const ENTITLEMENT_REASON = 'not available to this organization yet';
@@ -59,7 +60,7 @@ const FLOW_HINTS = Object.freeze({
   marketplace_seller: () => `marketplace selling (${toolName('marketplace.seller.status')})`,
 });
 
-const describeOrganization = (session) => {
+const describeOrganization = (session, remote) => {
   const organization = session.organization();
   const failure = session.failure();
   if (failure) return `Context at startup: unavailable. ${failure.error.message}`;
@@ -67,8 +68,9 @@ const describeOrganization = (session) => {
     session.identity().status === IdentityStatus.OK
       ? `organization ${organization.id ?? 'unknown'} (${organization.user_email ?? 'unknown user'})`
       : 'organization not resolved yet';
+  const where = remote ? `remote server ${organization.base_url}` : `profile ${organization.profile}, base URL ${organization.base_url}`;
   return (
-    `Context at startup: ${who}, profile ${organization.profile}, base URL ${organization.base_url}. This server ` +
+    `Context at startup: ${who}, ${where}. This server ` +
     'works on one organization only; every result carries the current one under `organization`.'
   );
 };
@@ -84,15 +86,17 @@ const offReason = (session, selection) => {
   return FALLBACK_TEXT[session.fallbackReason()] ?? FALLBACK_TEXT[FallbackReason.LOOKUP_PENDING];
 };
 
-const fallbackNote = (session, selection) => {
+const fallbackNote = (session, selection, remote) => {
   if (selection.source !== SelectionSource.FALLBACK) {
     const narrowed = selection.disabledToolsets.length > 0 || toolsetsIn(selection, EntitlementMode.READ).length > 0;
-    return narrowed ? ENABLE_HINT : '';
+    if (!narrowed) return '';
+    return remote ? REMOTE_ENABLE_HINT : ENABLE_HINT;
   }
+  if (remote) return REFRESH_NOTE;
   return FALLBACK_NOTES[session.fallbackReason()] ?? REFRESH_NOTE;
 };
 
-const describeToolsets = (session) => {
+const describeToolsets = (session, remote) => {
   const selection = session.selection();
   const full = toolsetsIn(selection, EntitlementMode.FULL);
   const read = toolsetsIn(selection, EntitlementMode.READ);
@@ -103,7 +107,7 @@ const describeToolsets = (session) => {
     read.length > 0 ? ` Read only: ${read.join(LIST_SEPARATOR)}.` : '',
     off.length > 0 ? ` Off (${offReason(session, selection)}): ${off.join(LIST_SEPARATOR)}.` : '',
     off.length > 0 && automatic ? SETUP_TOOLS_NOTE : '',
-    fallbackNote(session, selection),
+    fallbackNote(session, selection, remote),
     selection.readOnly ? READ_ONLY_NOTE : '',
   ].join('');
 };
@@ -123,15 +127,15 @@ const clip = (text) =>
     ? text
     : `${text.slice(0, MAX_INSTRUCTIONS_CHARS - TRUNCATION_MARK.length)}${TRUNCATION_MARK}`;
 
-export const buildInstructions = ({ session, version }) =>
+export const buildInstructions = ({ session, version, remote = false }) =>
   clip(
     [
       `Outrank MCP server (outrank-cli ${version}) for the Outrank SEO platform.`,
       RESULT_RULES,
       SAFETY_RULES,
       WORKFLOW_RULES,
-      describeOrganization(session),
-      describeToolsets(session),
+      describeOrganization(session, remote),
+      describeToolsets(session, remote),
       describeFlows(session),
     ]
       .filter(Boolean)

package/src/adapters/mcp/remote.js

@@ -0,0 +1,40 @@
+import { registry } from '../../commands/index.js';
+import { ContextSource } from '../../core/context.js';
+import { createLogger } from './logger.js';
+import { createMcpServer } from './server.js';
+import { parseToolsetOverride } from './toolsets.js';
+
+export const REMOTE_PROFILE_NAME = 'remote';
+
+const remoteOptions = () => ({
+  profile: undefined,
+  override: parseToolsetOverride(),
+  readOnly: false,
+  uploadDir: null,
+  uploadDirProblem: null,
+  startupError: null,
+});
+
+const remoteContext = ({ apiKey, baseUrl }) => ({
+  apiKey,
+  baseUrl: new URL(baseUrl).origin,
+  storedBaseUrl: undefined,
+  profile: { name: REMOTE_PROFILE_NAME, source: ContextSource.FLAG, explicit: true, known: true },
+  source: { apiKey: ContextSource.FLAG, baseUrl: ContextSource.FLAG, envIgnored: false, baseUrlEnvIgnored: false },
+});
+
+export const createRemoteMcpServer = async ({ apiKey, baseUrl, version, whoami, timeouts, logger = createLogger() }) => {
+  if (typeof apiKey !== 'string' || apiKey === '') throw new TypeError('createRemoteMcpServer needs an apiKey.');
+  return createMcpServer({
+    registry,
+    version,
+    options: remoteOptions(),
+    env: {},
+    readConfig: async () => ({}),
+    context: remoteContext({ apiKey, baseUrl }),
+    whoami,
+    remote: true,
+    timeouts,
+    logger,
+  });
+};

package/src/adapters/mcp/server.js

@@ -23,7 +23,7 @@ import {
   PROGRESS_NOTIFICATION_METHOD,
   WHOAMI_COMMAND_ID,
 } from './constants.js';
-import { describeField, describeTool, toolAnnotations } from './descriptions.js';
+import { describeField, describeTool, toolAnnotations, toolTitle } from './descriptions.js';
 import { createGuidanceRewriter } from './guidance.js';
 import { MCP_LABELS, buildToolInput, parseToolArguments, toRawInput } from './input.js';
 import { buildInstructions } from './instructions.js';
@@ -58,6 +58,7 @@ export const buildToolDefinition = (spec, uploads) => {
     input,
     tool: {
       name: toolName(spec.id),
+      title: toolTitle(spec),
       description: describeTool(spec),
       inputSchema: input.inputSchema,
       annotations: toolAnnotations(spec),
@@ -71,13 +72,18 @@ export const createMcpServer = async ({
   options,
   env,
   readConfig,
+  context,
+  whoami,
+  remote = false,
   timeouts = {},
   logger = createLogger(),
   throttle,
 }) => {
   const progressIntervalMs = timeouts.progressIntervalMs ?? MCP_PROGRESS_INTERVAL_MS;
   const definitions = new Map();
-  const uploads = { dir: options.uploadDir, problem: options.uploadDirProblem ?? null };
+  const uploads = remote
+    ? { dir: null, problem: null }
+    : { dir: options.uploadDir, problem: options.uploadDirProblem ?? null };
   let server = null;
 
   const definitionFor = (spec) => {
@@ -104,6 +110,8 @@ export const createMcpServer = async ({
     options,
     env,
     readConfig,
+    context,
+    whoami,
     timeouts,
     onToolsChanged: notifyToolsChanged,
     ...(throttle ? { throttle } : {}),
@@ -199,7 +207,7 @@ export const createMcpServer = async ({
     { name: MCP_SERVER_NAME, version },
     {
       capabilities: { tools: { listChanged: true }, prompts: { listChanged: true }, resources: {} },
-      instructions: buildInstructions({ session, version }),
+      instructions: buildInstructions({ session, version, remote }),
     },
   );
   server.onerror = (error) => {

package/src/adapters/mcp/session.js

@@ -80,6 +80,8 @@ export const createSession = ({
   options,
   env = process.env,
   readConfig = loadConfig,
+  context: fixedContext = null,
+  whoami: initialWhoami = null,
   timeouts = {},
   now = Date.now,
   onToolsChanged = () => {},
@@ -127,13 +129,15 @@ export const createSession = ({
   const resolve = async () => {
     const previousKey = state.resolved?.apiKey;
     try {
-      state.resolved = resolveContext({
-        flags: { profile: options.profile },
-        env,
-        config: await readConfig(),
-        customBaseUrlFromStoredProfileOnly: true,
-        revealLocalDetails: false,
-      });
+      state.resolved =
+        fixedContext ??
+        resolveContext({
+          flags: { profile: options.profile },
+          env,
+          config: await readConfig(),
+          customBaseUrlFromStoredProfileOnly: true,
+          revealLocalDetails: false,
+        });
       state.contextError = null;
     } catch (error) {
       state.resolved = null;
@@ -249,7 +253,10 @@ export const createSession = ({
   const start = async () => {
     if (!options.startupError) await resolve();
     refreshSelection();
-    if (canIdentify()) await withBudget(requestIdentity(), startupBudgetMs);
+    if (initialWhoami && canIdentify()) applyWhoami(initialWhoami);
+    if (canIdentify() && state.identity.status !== IdentityStatus.OK) {
+      await withBudget(requestIdentity(), startupBudgetMs);
+    }
   };
 
   const ensureReady = async () => {

package/src/core/redact.js

@@ -3,7 +3,7 @@ import { SENSITIVE_BODY_FIELDS } from './constants.js';
 export const REDACTED = '<redacted>';
 const TOO_DEEP = '<nested too deeply>';
 const DEFAULT_MAX_DEPTH = 32;
-const API_KEY_PATTERN = /outr_(?:live|test)_[A-Za-z0-9_]+/g;
+const API_KEY_PATTERN = /outr_(?:live|test|oat|ort)_[A-Za-z0-9_-]+/g;
 const BEARER_PATTERN = /Bearer\s+[A-Za-z0-9._~+/=-]+/g;
 const SENSITIVE_FIELD_SET = new Set(SENSITIVE_BODY_FIELDS.map((name) => name.toLowerCase()));
 const SENSITIVE_KEY_PATTERN = /token|secret|password|passwd|api[_-]?key|authorization|credential|private[_-]?key/i;