@roarkanalytics/sdk-mcp 4.42.0 → 4.43.0

package/src/docs-search-tool.ts

@@ -14,8 +14,9 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'search_docs',
+  title: 'Search Roark docs',
   description:
-    'Search SDK documentation to find methods, parameters, and usage examples for interacting with the API. Use this before writing code when you need to discover the right approach.',
+    'Searches Roark SDK documentation for methods, parameters, and response shapes. Returns the matching documentation for the query and language.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -37,7 +38,9 @@ export const tool: Tool = {
     required: ['query', 'language'],
   },
   annotations: {
+    title: 'Search Roark docs',
     readOnlyHint: true,
+    destructiveHint: false,
   },
 };
 

package/src/http.ts

@@ -9,7 +9,7 @@ import pino from 'pino';
 import pinoHttp from 'pino-http';
 import { getStainlessApiKey, parseClientAuthHeaders } from './auth';
 import { getLogger } from './logger';
-import { McpOptions } from './options';
+import { McpOptions, toolSurfaceFor } from './options';
 import {
   Connector,
   ORIGIN_CONNECTOR,
@@ -49,9 +49,9 @@ const newServer = async ({
   // token is a Roark API key and is forwarded to the SDK unchanged. Without oauth
   // config we keep the legacy optional-bearer behavior (local installs).
   //
-  // This runs before the server is built on purpose: `newMcpServer` fetches the
-  // instructions document over the network, and an unauthenticated caller should
-  // not be able to make us do that.
+  // This runs before the server is built on purpose: in code mode `newMcpServer`
+  // fetches the instructions document over the network, and an unauthenticated
+  // caller should not be able to make us do that. Directory mode does not fetch.
   let authOptions: Partial<ClientOptions>;
   if (mcpOptions.oauth) {
     const connector = connectorFrom(req);
@@ -74,7 +74,11 @@ const newServer = async ({
 
   const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
   const customInstructionsPath = mcpOptions.customInstructionsPath;
-  const server = await newMcpServer({ stainlessApiKey, customInstructionsPath });
+  const server = await newMcpServer({
+    stainlessApiKey,
+    customInstructionsPath,
+    toolSurface: toolSurfaceFor(mcpOptions),
+  });
 
   let upstreamClientEnvs: Record<string, string> | undefined;
   const clientEnvsHeader = req.headers['x-stainless-mcp-client-envs'];

package/src/options.ts

@@ -25,6 +25,11 @@ export type McpOptions = {
   codeAllowedMethods?: string[] | undefined;
   codeBlockedMethods?: string[] | undefined;
   codeExecutionMode: McpCodeExecutionMode;
+  /**
+   * Which tool set to expose. Unset means `directory` when `oauth` is set and
+   * `code` otherwise. See `toolSurfaceFor`.
+   */
+  toolSurface?: ToolSurface | undefined;
   customInstructionsPath?: string | undefined;
   /**
    * Remote OAuth resource-server config. When set (http transport), every request
@@ -37,6 +42,23 @@ export type McpOptions = {
 
 export type McpCodeExecutionMode = 'stainless-sandbox' | 'local';
 
+/**
+ * `directory` is the Claude connector surface: one named tool per action, reads
+ * and writes split. `code` is the local install: `execute` plus docs search.
+ */
+export type ToolSurface = 'code' | 'directory';
+
+/**
+ * OAuth is what the hosted directory server runs with, so that process defaults
+ * to the named tools. A local stdio install, and an HTTP server without OAuth,
+ * keep the code tool. An explicit `toolSurface` wins over that default, which
+ * is how a private server can still opt into code execution.
+ */
+export function toolSurfaceFor(options?: Pick<McpOptions, 'toolSurface' | 'oauth'>): ToolSurface {
+  if (options?.toolSurface) return options.toolSurface;
+  return options?.oauth ? 'directory' : 'code';
+}
+
 export function parseCLIOptions(): CLIOptions {
   const opts = yargs(hideBin(process.argv))
     .option('code-allow-http-gets', {
@@ -110,6 +132,12 @@ export function parseCLIOptions(): CLIOptions {
       description:
         'API key for Stainless. Used to authenticate requests to Stainless-hosted tools endpoints.',
     })
+    .option('tool-surface', {
+      type: 'string',
+      choices: ['code', 'directory'],
+      description:
+        "Which tools to expose. 'directory' is a set of separate read and write tools and is the default when OAuth is enabled. 'code' exposes the code execution tool and is the default otherwise.",
+    })
     .option('tools', {
       type: 'string',
       array: true,
@@ -177,6 +205,10 @@ export function parseCLIOptions(): CLIOptions {
     codeAllowedMethods: argv.codeAllowedMethods,
     codeBlockedMethods: argv.codeBlockedMethods,
     codeExecutionMode,
+    toolSurface: toolSurfaceFor({
+      toolSurface: argv.toolSurface as ToolSurface | undefined,
+      ...(oauth && { oauth }),
+    }),
     customInstructionsPath: argv.customInstructionsPath,
     ...(oauth && { oauth }),
     transport,
@@ -235,6 +267,7 @@ export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): M
     ...(codeTool !== undefined && { includeCodeTool: codeTool }),
     ...(docsTools !== undefined && { includeDocsTools: docsTools }),
     codeExecutionMode: defaultOptions.codeExecutionMode,
+    toolSurface: defaultOptions.toolSurface,
     docsSearchMode: defaultOptions.docsSearchMode,
     docsDir: defaultOptions.docsDir,
   };

package/src/server.ts

@@ -10,11 +10,12 @@ import {
 import { ClientOptions } from '@roarkanalytics/sdk';
 import Roark from '@roarkanalytics/sdk';
 import { codeTool } from './code-tool';
+import { DIRECTORY_SERVER_INSTRUCTIONS, directoryTools } from './directory-tools';
 import docsSearchTool from './docs-search-tool';
 import { setLocalSearch } from './docs-search-tool';
 import { LocalDocsSearch } from './local-docs-search';
 import { getInstructions } from './instructions';
-import { McpOptions } from './options';
+import { McpOptions, toolSurfaceFor } from './options';
 import { blockedMethodsForCodeTool } from './methods';
 import { HandlerFunction, McpRequestContext, ToolCallResult, McpTool } from './types';
 import { MCP_CLIENT_HEADERS } from './client-headers';
@@ -22,18 +23,26 @@ import { MCP_CLIENT_HEADERS } from './client-headers';
 export const newMcpServer = async ({
   stainlessApiKey,
   customInstructionsPath,
+  toolSurface,
 }: {
   stainlessApiKey?: string | undefined;
   customInstructionsPath?: string | undefined;
+  toolSurface?: McpOptions['toolSurface'] | undefined;
 }) =>
   new McpServer(
     {
       name: 'roarkanalytics_sdk_api',
       // A literal, not MCP_SERVER_VERSION: publish.yml checks dist/server.js for it.
-      version: '4.42.0', // x-release-please-version
+      version: '4.43.0', // x-release-please-version
     },
     {
-      instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),
+      // Directory mode does not fetch instructions. The hosted document tells a
+      // model how to write SDK snippets for `execute`, which this surface does
+      // not expose, and the directory reviews that kind of instruction.
+      instructions:
+        toolSurface === 'directory' ?
+          DIRECTORY_SERVER_INSTRUCTIONS
+        : await getInstructions({ stainlessApiKey, customInstructionsPath }),
       capabilities: { tools: {}, logging: {} },
     },
   );
@@ -213,8 +222,14 @@ export async function initMcpServer(params: {
  */
 export function selectTools(options?: McpOptions): McpTool[] {
   const includedTools = [];
+  const surface = toolSurfaceFor(options);
 
-  if (options?.includeCodeTool ?? true) {
+  if (surface === 'directory') {
+    // `includeCodeTool` cannot put `execute` back on this surface. The directory
+    // endpoint is the one Claude reviews, and a query or header that re-enabled
+    // arbitrary SDK code would put a mixed read/write tool back in front of it.
+    includedTools.push(...directoryTools());
+  } else if (options?.includeCodeTool ?? true) {
     includedTools.push(
       codeTool({
         blockedMethods: blockedMethodsForCodeTool(options),

package/src/stdio.ts

@@ -1,5 +1,5 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { McpOptions } from './options';
+import { McpOptions, toolSurfaceFor } from './options';
 import { initMcpServer, newMcpServer } from './server';
 import { getLogger } from './logger';
 
@@ -7,6 +7,7 @@ export const launchStdioServer = async (mcpOptions: McpOptions) => {
   const server = await newMcpServer({
     stainlessApiKey: mcpOptions.stainlessApiKey,
     customInstructionsPath: mcpOptions.customInstructionsPath,
+    toolSurface: toolSurfaceFor(mcpOptions),
   });
 
   await initMcpServer({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey });

package/stdio.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.d.mts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,sBAAkB;AAIvC,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAW7D,CAAC"}
+{"version":3,"file":"stdio.d.mts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAkB,sBAAkB;AAIvD,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAY7D,CAAC"}

package/stdio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,qBAAkB;AAIvC,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAW7D,CAAC"}
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAkB,qBAAkB;AAIvD,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAY7D,CAAC"}

package/stdio.js

@@ -2,12 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.launchStdioServer = void 0;
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const options_1 = require("./options.js");
 const server_1 = require("./server.js");
 const logger_1 = require("./logger.js");
 const launchStdioServer = async (mcpOptions) => {
     const server = await (0, server_1.newMcpServer)({
         stainlessApiKey: mcpOptions.stainlessApiKey,
         customInstructionsPath: mcpOptions.customInstructionsPath,
+        toolSurface: (0, options_1.toolSurfaceFor)(mcpOptions),
     });
     await (0, server_1.initMcpServer)({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey });
     const transport = new stdio_js_1.StdioServerTransport();

package/stdio.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.js","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AAEjF,wCAAuD;AACvD,wCAAqC;AAE9B,MAAM,iBAAiB,GAAG,KAAK,EAAE,UAAsB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,IAAA,qBAAY,EAAC;QAChC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,sBAAsB,EAAE,UAAU,CAAC,sBAAsB;KAC1D,CAAC,CAAC;IAEH,MAAM,IAAA,sBAAa,EAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,IAAA,kBAAS,GAAE,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAClD,CAAC,CAAC;AAXW,QAAA,iBAAiB,qBAW5B"}
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AACjF,0CAAuD;AACvD,wCAAuD;AACvD,wCAAqC;AAE9B,MAAM,iBAAiB,GAAG,KAAK,EAAE,UAAsB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,IAAA,qBAAY,EAAC;QAChC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,sBAAsB,EAAE,UAAU,CAAC,sBAAsB;QACzD,WAAW,EAAE,IAAA,wBAAc,EAAC,UAAU,CAAC;KACxC,CAAC,CAAC;IAEH,MAAM,IAAA,sBAAa,EAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,IAAA,kBAAS,GAAE,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAClD,CAAC,CAAC;AAZW,QAAA,iBAAiB,qBAY5B"}

package/stdio.mjs

@@ -1,10 +1,12 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { toolSurfaceFor } from "./options.mjs";
 import { initMcpServer, newMcpServer } from "./server.mjs";
 import { getLogger } from "./logger.mjs";
 export const launchStdioServer = async (mcpOptions) => {
     const server = await newMcpServer({
         stainlessApiKey: mcpOptions.stainlessApiKey,
         customInstructionsPath: mcpOptions.customInstructionsPath,
+        toolSurface: toolSurfaceFor(mcpOptions),
     });
     await initMcpServer({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey });
     const transport = new StdioServerTransport();

package/stdio.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.mjs","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAiB;AACvD,OAAO,EAAE,SAAS,EAAE,qBAAiB;AAErC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,UAAsB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,sBAAsB,EAAE,UAAU,CAAC,sBAAsB;KAC1D,CAAC,CAAC;IAEH,MAAM,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,SAAS,EAAE,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAClD,CAAC,CAAC"}
+{"version":3,"file":"stdio.mjs","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAc,cAAc,EAAE,sBAAkB;AACvD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAiB;AACvD,OAAO,EAAE,SAAS,EAAE,qBAAiB;AAErC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,UAAsB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,sBAAsB,EAAE,UAAU,CAAC,sBAAsB;QACzD,WAAW,EAAE,cAAc,CAAC,UAAU,CAAC;KACxC,CAAC,CAAC;IAEH,MAAM,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,SAAS,EAAE,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAClD,CAAC,CAAC"}