lark-billing-mcp 0.7.0

package/src/code-tool.ts

@@ -0,0 +1,96 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { McpTool, Metadata, ToolCallResult, asErrorResult, asTextContentResult } from './types';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { readEnv, readEnvOrError } from './server';
+import { WorkerInput, WorkerOutput } from './code-tool-types';
+
+const prompt = `Runs JavaScript code to interact with the Lark API.
+
+You are a skilled programmer writing code to interface with the service.
+Define an async function named "run" that takes a single parameter of an initialized SDK client and it will be run.
+For example:
+
+\`\`\`
+async function run(client) {
+  const subject = await client.subjects.create({
+    email: 'john.doe@example.com',
+    external_id: 'user_1234567890',
+    name: 'John Doe',
+  });
+
+  console.log(subject.id);
+}
+\`\`\`
+
+You will be returned anything that your function returns, plus the results of any console.log statements.
+Do not add try-catch blocks for single API calls. The tool will handle errors for you.
+Do not add comments unless necessary for generating better code.
+Code will run in a container, and cannot interact with the network outside of the given SDK client.
+Variables will not persist between calls, so make sure to return or log any data you might need later.`;
+
+/**
+ * A tool that runs code against a copy of the SDK.
+ *
+ * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once,
+ * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
+ * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
+ *
+ * @param endpoints - The endpoints to include in the list.
+ */
+export function codeTool(): McpTool {
+  const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
+  const tool: Tool = {
+    name: 'execute',
+    description: prompt,
+    inputSchema: { type: 'object', properties: { code: { type: 'string' } } },
+  };
+  const handler = async (_: unknown, args: any): Promise<ToolCallResult> => {
+    const code = args.code as string;
+
+    // this is not required, but passing a Stainless API key for the matching project_name
+    // will allow you to run code-mode queries against non-published versions of your SDK.
+    const stainlessAPIKey = readEnv('STAINLESS_API_KEY');
+    const codeModeEndpoint =
+      readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
+
+    const res = await fetch(codeModeEndpoint, {
+      method: 'POST',
+      headers: {
+        ...(stainlessAPIKey && { Authorization: stainlessAPIKey }),
+        'Content-Type': 'application/json',
+        client_envs: JSON.stringify({
+          LARK_API_KEY: readEnvOrError('LARK_API_KEY'),
+          LARK_BASE_URL: readEnv('LARK_BASE_URL'),
+        }),
+      },
+      body: JSON.stringify({
+        project_name: 'lark',
+        code,
+        client_opts: {},
+      } satisfies WorkerInput),
+    });
+
+    if (!res.ok) {
+      throw new Error(
+        `${res.status}: ${
+          res.statusText
+        } error when trying to contact Code Tool server. Details: ${await res.text()}`,
+      );
+    }
+
+    const { is_error, result, log_lines, err_lines } = (await res.json()) as WorkerOutput;
+    const hasLogs = log_lines.length > 0 || err_lines.length > 0;
+    const output = {
+      result,
+      ...(log_lines.length > 0 && { log_lines }),
+      ...(err_lines.length > 0 && { err_lines }),
+    };
+    if (is_error) {
+      return asErrorResult(typeof result === 'string' && !hasLogs ? result : JSON.stringify(output, null, 2));
+    }
+    return asTextContentResult(output);
+  };
+
+  return { metadata, tool, handler };
+}

package/src/docs-search-tool.ts

@@ -0,0 +1,59 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from './types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const metadata: Metadata = {
+  resource: 'all',
+  operation: 'read',
+  tags: [],
+  httpMethod: 'get',
+};
+
+export const tool: Tool = {
+  name: 'search_docs',
+  description: 'Search for documentation for how to use the client to interact with the API.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The query to search for.',
+      },
+      language: {
+        type: 'string',
+        description: 'The language for the SDK to search for.',
+        enum: ['http', 'python', 'go', 'typescript', 'javascript', 'terraform', 'ruby', 'java', 'kotlin'],
+      },
+      detail: {
+        type: 'string',
+        description: 'The amount of detail to return.',
+        enum: ['default', 'verbose'],
+      },
+    },
+    required: ['query', 'language'],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+const docsSearchURL =
+  process.env['DOCS_SEARCH_URL'] || 'https://api.stainless.com/api/projects/lark/docs/search';
+
+export const handler = async (_: unknown, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  const query = new URLSearchParams(body).toString();
+  const result = await fetch(`${docsSearchURL}?${query}`);
+
+  if (!result.ok) {
+    throw new Error(
+      `${result.status}: ${result.statusText} when using doc search tool. Details: ${await result.text()}`,
+    );
+  }
+
+  return asTextContentResult(await result.json());
+};
+
+export default { metadata, tool, handler };

package/src/headers.ts

@@ -0,0 +1,10 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { IncomingMessage } from 'node:http';
+import { ClientOptions } from 'lark-billing';
+
+export const parseAuthHeaders = (req: IncomingMessage): Partial<ClientOptions> => {
+  const apiKey =
+    Array.isArray(req.headers['x-api-key']) ? req.headers['x-api-key'][0] : req.headers['x-api-key'];
+  return { apiKey };
+};

package/src/http.ts

@@ -0,0 +1,109 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+import express from 'express';
+import { McpOptions } from './options';
+import { ClientOptions, initMcpServer, newMcpServer } from './server';
+import { parseAuthHeaders } from './headers';
+
+const newServer = ({
+  clientOptions,
+  req,
+  res,
+}: {
+  clientOptions: ClientOptions;
+  req: express.Request;
+  res: express.Response;
+}): McpServer | null => {
+  const server = newMcpServer();
+
+  try {
+    const authOptions = parseAuthHeaders(req);
+    initMcpServer({
+      server: server,
+      clientOptions: {
+        ...clientOptions,
+        ...authOptions,
+      },
+    });
+  } catch (error) {
+    res.status(401).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: `Unauthorized: ${error instanceof Error ? error.message : error}`,
+      },
+    });
+    return null;
+  }
+
+  return server;
+};
+
+const post =
+  (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) =>
+  async (req: express.Request, res: express.Response) => {
+    const server = newServer({ ...options, req, res });
+    // If we return null, we already set the authorization error.
+    if (server === null) return;
+    const transport = new StreamableHTTPServerTransport({
+      // Stateless server
+      sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  };
+
+const get = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+const del = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+export const streamableHTTPApp = ({
+  clientOptions = {},
+  mcpOptions = {},
+}: {
+  clientOptions?: ClientOptions;
+  mcpOptions?: McpOptions;
+}): express.Express => {
+  const app = express();
+  app.set('query parser', 'extended');
+  app.use(express.json());
+
+  app.get('/', get);
+  app.post('/', post({ clientOptions, mcpOptions }));
+  app.delete('/', del);
+
+  return app;
+};
+
+export const launchStreamableHTTPServer = async (options: McpOptions, port: number | string | undefined) => {
+  const app = streamableHTTPApp({ mcpOptions: options });
+  const server = app.listen(port);
+  const address = server.address();
+
+  if (typeof address === 'string') {
+    console.error(`MCP Server running on streamable HTTP at ${address}`);
+  } else if (address !== null) {
+    console.error(`MCP Server running on streamable HTTP on port ${address.port}`);
+  } else {
+    console.error(`MCP Server running on streamable HTTP on port ${port}`);
+  }
+};

package/src/index.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { selectTools } from './server';
+import { McpOptions, parseCLIOptions } from './options';
+import { launchStdioServer } from './stdio';
+import { launchStreamableHTTPServer } from './http';
+import type { McpTool } from './types';
+
+async function main() {
+  const options = parseOptionsOrError();
+
+  const selectedTools = await selectToolsOrError(options);
+
+  console.error(
+    `MCP Server starting with ${selectedTools.length} tools:`,
+    selectedTools.map((e) => e.tool.name),
+  );
+
+  switch (options.transport) {
+    case 'stdio':
+      await launchStdioServer();
+      break;
+    case 'http':
+      await launchStreamableHTTPServer(options, options.port ?? options.socket);
+      break;
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+  });
+}
+
+function parseOptionsOrError() {
+  try {
+    return parseCLIOptions();
+  } catch (error) {
+    console.error('Error parsing options:', error);
+    process.exit(1);
+  }
+}
+
+async function selectToolsOrError(options: McpOptions): Promise<McpTool[]> {
+  try {
+    const includedTools = selectTools(options);
+    if (includedTools.length === 0) {
+      console.error('No tools match the provided filters.');
+      process.exit(1);
+    }
+    return includedTools;
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Error filtering tools:', error.message);
+    } else {
+      console.error('Error filtering tools:', error);
+    }
+    process.exit(1);
+  }
+}

package/src/options.ts

@@ -0,0 +1,92 @@
+import qs from 'qs';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import z from 'zod';
+
+export type CLIOptions = McpOptions & {
+  transport: 'stdio' | 'http';
+  port: number | undefined;
+  socket: string | undefined;
+};
+
+export type McpOptions = {
+  includeDocsTools?: boolean | undefined;
+};
+
+export function parseCLIOptions(): CLIOptions {
+  const opts = yargs(hideBin(process.argv))
+    .option('tools', {
+      type: 'string',
+      array: true,
+      choices: ['code', 'docs'],
+      description: 'Use dynamic tools or all tools',
+    })
+    .option('no-tools', {
+      type: 'string',
+      array: true,
+      choices: ['code', 'docs'],
+      description: 'Do not use any dynamic or all tools',
+    })
+    .option('transport', {
+      type: 'string',
+      choices: ['stdio', 'http'],
+      default: 'stdio',
+      description: 'What transport to use; stdio for local servers or http for remote servers',
+    })
+    .option('port', {
+      type: 'number',
+      description: 'Port to serve on if using http transport',
+    })
+    .option('socket', {
+      type: 'string',
+      description: 'Unix socket to serve on if using http transport',
+    })
+    .help();
+
+  const argv = opts.parseSync();
+
+  const shouldIncludeToolType = (toolType: 'code' | 'docs') =>
+    argv.noTools?.includes(toolType) ? false
+    : argv.tools?.includes(toolType) ? true
+    : undefined;
+
+  const includeDocsTools = shouldIncludeToolType('docs');
+
+  const transport = argv.transport as 'stdio' | 'http';
+
+  return {
+    ...(includeDocsTools !== undefined && { includeDocsTools }),
+    transport,
+    port: argv.port,
+    socket: argv.socket,
+  };
+}
+
+const coerceArray = <T extends z.ZodTypeAny>(zodType: T) =>
+  z.preprocess(
+    (val) =>
+      Array.isArray(val) ? val
+      : val ? [val]
+      : val,
+    z.array(zodType).optional(),
+  );
+
+const QueryOptions = z.object({
+  tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to use'),
+  no_tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to not use.'),
+  tool: coerceArray(z.string()).describe('Include tools matching the specified names'),
+});
+
+export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): McpOptions {
+  const queryObject = typeof query === 'string' ? qs.parse(query) : query;
+  const queryOptions = QueryOptions.parse(queryObject);
+
+  let docsTools: boolean | undefined =
+    queryOptions.no_tools && queryOptions.no_tools?.includes('docs') ? false
+    : queryOptions.tools?.includes('docs') ? true
+    : defaultOptions.includeDocsTools;
+
+  return {
+    ...(docsTools !== undefined && { includeDocsTools: docsTools }),
+  };
+}

package/src/server.ts

@@ -0,0 +1,147 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  SetLevelRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { ClientOptions } from 'lark-billing';
+import Lark from 'lark-billing';
+import { codeTool } from './code-tool';
+import docsSearchTool from './docs-search-tool';
+import { McpOptions } from './options';
+import { HandlerFunction, McpTool } from './types';
+
+export { McpOptions } from './options';
+export { ClientOptions } from 'lark-billing';
+
+export const newMcpServer = () =>
+  new McpServer(
+    {
+      name: 'lark_billing_api',
+      version: '0.7.0',
+    },
+    { capabilities: { tools: {}, logging: {} } },
+  );
+
+// Create server instance
+export const server = newMcpServer();
+
+/**
+ * Initializes the provided MCP Server with the given tools and handlers.
+ * If not provided, the default client, tools and handlers will be used.
+ */
+export function initMcpServer(params: {
+  server: Server | McpServer;
+  clientOptions?: ClientOptions;
+  mcpOptions?: McpOptions;
+}) {
+  const server = params.server instanceof McpServer ? params.server.server : params.server;
+
+  const logAtLevel =
+    (level: 'debug' | 'info' | 'warning' | 'error') =>
+    (message: string, ...rest: unknown[]) => {
+      void server.sendLoggingMessage({
+        level,
+        data: { message, rest },
+      });
+    };
+  const logger = {
+    debug: logAtLevel('debug'),
+    info: logAtLevel('info'),
+    warn: logAtLevel('warning'),
+    error: logAtLevel('error'),
+  };
+
+  let client = new Lark({
+    logger,
+    ...params.clientOptions,
+    defaultHeaders: {
+      ...params.clientOptions?.defaultHeaders,
+      'X-Stainless-MCP': 'true',
+    },
+  });
+
+  const providedTools = selectTools(params.mcpOptions);
+  const toolMap = Object.fromEntries(providedTools.map((mcpTool) => [mcpTool.tool.name, mcpTool]));
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: providedTools.map((mcpTool) => mcpTool.tool),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const mcpTool = toolMap[name];
+    if (!mcpTool) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return executeHandler(mcpTool.handler, client, args);
+  });
+
+  server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+    const { level } = request.params;
+    switch (level) {
+      case 'debug':
+        client = client.withOptions({ logLevel: 'debug' });
+        break;
+      case 'info':
+        client = client.withOptions({ logLevel: 'info' });
+        break;
+      case 'notice':
+      case 'warning':
+        client = client.withOptions({ logLevel: 'warn' });
+        break;
+      case 'error':
+        client = client.withOptions({ logLevel: 'error' });
+        break;
+      default:
+        client = client.withOptions({ logLevel: 'off' });
+        break;
+    }
+    return {};
+  });
+}
+
+/**
+ * Selects the tools to include in the MCP Server based on the provided options.
+ */
+export function selectTools(options?: McpOptions): McpTool[] {
+  const includedTools = [codeTool()];
+  if (options?.includeDocsTools ?? true) {
+    includedTools.push(docsSearchTool);
+  }
+  return includedTools;
+}
+
+/**
+ * Runs the provided handler with the given client and arguments.
+ */
+export async function executeHandler(
+  handler: HandlerFunction,
+  client: Lark,
+  args: Record<string, unknown> | undefined,
+) {
+  return await handler(client, args || {});
+}
+
+export const readEnv = (env: string): string | undefined => {
+  if (typeof (globalThis as any).process !== 'undefined') {
+    return (globalThis as any).process.env?.[env]?.trim();
+  } else if (typeof (globalThis as any).Deno !== 'undefined') {
+    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+  }
+  return;
+};
+
+export const readEnvOrError = (env: string): string => {
+  let envValue = readEnv(env);
+  if (envValue === undefined) {
+    throw new Error(`Environment variable ${env} is not set`);
+  }
+  return envValue;
+};

package/src/stdio.ts

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { initMcpServer, newMcpServer } from './server';
+
+export const launchStdioServer = async () => {
+  const server = newMcpServer();
+
+  initMcpServer({ server });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP Server running on stdio');
+};

package/src/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  // this config is included in the published src directory to prevent TS errors
+  // from appearing when users go to source, and VSCode opens the source .ts file
+  // via declaration maps
+  "include": ["index.ts"],
+  "compilerOptions": {
+    "target": "es2015",
+    "lib": ["DOM"],
+    "moduleResolution": "node"
+  }
+}