@codeqr/ts-mcp 0.2.1

package/src/server.ts

@@ -0,0 +1,204 @@
+// 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 { Endpoint, endpoints, HandlerFunction, query } from './tools';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  SetLevelRequestSchema,
+  Implementation,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { ClientOptions } from '@codeqr/ts';
+import Codeqr from '@codeqr/ts';
+import {
+  applyCompatibilityTransformations,
+  ClientCapabilities,
+  defaultClientCapabilities,
+  knownClients,
+  parseEmbeddedJSON,
+} from './compat';
+import { dynamicTools } from './dynamic-tools';
+import { codeTool } from './code-tool';
+import { McpOptions } from './options';
+
+export { McpOptions } from './options';
+export { ClientType } from './compat';
+export { Filter } from './tools';
+export { ClientOptions } from '@codeqr/ts';
+export { endpoints } from './tools';
+
+export const newMcpServer = () =>
+  new McpServer(
+    {
+      name: 'codeqr_ts_api',
+      version: '0.2.1',
+    },
+    { 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 mcpOptions = params.mcpOptions ?? {};
+
+  let providedEndpoints: Endpoint[] | null = null;
+  let endpointMap: Record<string, Endpoint> | null = null;
+
+  const initTools = async (implementation?: Implementation) => {
+    if (implementation && (!mcpOptions.client || mcpOptions.client === 'infer')) {
+      mcpOptions.client =
+        implementation.name.toLowerCase().includes('claude') ? 'claude'
+        : implementation.name.toLowerCase().includes('cursor') ? 'cursor'
+        : undefined;
+      mcpOptions.capabilities = {
+        ...(mcpOptions.client && knownClients[mcpOptions.client]),
+        ...mcpOptions.capabilities,
+      };
+    }
+    providedEndpoints ??= await selectTools(endpoints, mcpOptions);
+    endpointMap ??= Object.fromEntries(providedEndpoints.map((endpoint) => [endpoint.tool.name, endpoint]));
+  };
+
+  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 Codeqr({
+    logger,
+    ...params.clientOptions,
+    defaultHeaders: {
+      ...params.clientOptions?.defaultHeaders,
+      'X-Stainless-MCP': 'true',
+    },
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    if (providedEndpoints === null) {
+      await initTools(server.getClientVersion());
+    }
+    return {
+      tools: providedEndpoints!.map((endpoint) => endpoint.tool),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (endpointMap === null) {
+      await initTools(server.getClientVersion());
+    }
+    const { name, arguments: args } = request.params;
+    const endpoint = endpointMap![name];
+    if (!endpoint) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return executeHandler(endpoint.tool, endpoint.handler, client, args, mcpOptions.capabilities);
+  });
+
+  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 async function selectTools(endpoints: Endpoint[], options?: McpOptions): Promise<Endpoint[]> {
+  const filteredEndpoints = query(options?.filters ?? [], endpoints);
+
+  let includedTools = filteredEndpoints;
+
+  if (includedTools.length > 0) {
+    if (options?.includeDynamicTools) {
+      includedTools = dynamicTools(includedTools);
+    }
+  } else {
+    if (options?.includeAllTools) {
+      includedTools = endpoints;
+    } else if (options?.includeDynamicTools) {
+      includedTools = dynamicTools(endpoints);
+    } else if (options?.includeCodeTools) {
+      includedTools = [await codeTool()];
+    } else {
+      includedTools = endpoints;
+    }
+  }
+
+  const capabilities = { ...defaultClientCapabilities, ...options?.capabilities };
+  return applyCompatibilityTransformations(includedTools, capabilities);
+}
+
+/**
+ * Runs the provided handler with the given client and arguments.
+ */
+export async function executeHandler(
+  tool: Tool,
+  handler: HandlerFunction,
+  client: Codeqr,
+  args: Record<string, unknown> | undefined,
+  compatibilityOptions?: Partial<ClientCapabilities>,
+) {
+  const options = { ...defaultClientCapabilities, ...compatibilityOptions };
+  if (!options.validJson && args) {
+    args = parseEmbeddedJSON(args, tool.inputSchema);
+  }
+  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,13 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { initMcpServer, newMcpServer } from './server';
+import { McpOptions } from './options';
+
+export const launchStdioServer = async (options: McpOptions) => {
+  const server = newMcpServer();
+
+  initMcpServer({ server, mcpOptions: options });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP Server running on stdio');
+};

package/src/tools/analytics/retrieve-analytics.ts

@@ -0,0 +1,434 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@codeqr/ts-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Codeqr from '@codeqr/ts';
+
+export const metadata: Metadata = {
+  resource: 'analytics',
+  operation: 'read',
+  tags: [],
+  httpMethod: 'get',
+  httpPath: '/analytics',
+  operationId: 'retrieveAnalytics',
+};
+
+export const tool: Tool = {
+  name: 'retrieve_analytics',
+  description:
+    'Retrieve analytics for a link, a domain, or the authenticated workspace. The response type depends on the `event` and `type` query parameters.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      browser: {
+        type: 'string',
+        description: 'The browser to retrieve analytics for.',
+      },
+      city: {
+        type: 'string',
+        description: 'The city to retrieve analytics for.',
+      },
+      continent: {
+        $ref: '#/$defs/continent_code',
+      },
+      country: {
+        $ref: '#/$defs/country_code',
+      },
+      device: {
+        type: 'string',
+        description: 'The device to retrieve analytics for.',
+      },
+      domain: {
+        type: 'string',
+        description: 'The domain of the short link.',
+      },
+      end: {
+        type: 'string',
+        description:
+          'The end date and time when to retrieve analytics from. If not provided, defaults to the current date.',
+      },
+      event: {
+        type: 'string',
+        description: "The type of event to retrieve analytics for. Defaults to 'analytics'.",
+        enum: ['clicks', 'leads', 'sales', 'scans', 'views', 'composite'],
+      },
+      excludeRoot: {
+        type: 'boolean',
+        description: 'Whether to exclude the root link from the response.',
+      },
+      externalId: {
+        type: 'string',
+        description:
+          "This is the ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.",
+      },
+      groupBy: {
+        type: 'string',
+        description: "The parameter to group the analytics data points by. Defaults to 'count' if undefined.",
+        enum: [
+          'timeseries',
+          'clicks',
+          'count',
+          'totals',
+          'top_urls',
+          'top_links',
+          'top_qrcodes',
+          'top_pages',
+          'top_events',
+          'scans',
+          'views',
+          'country',
+          'city',
+          'region',
+          'devices',
+          'browsers',
+          'os',
+          'referers',
+          'referer_urls',
+          'trend_live',
+          'kpis',
+          'analytics',
+          'continents',
+          'countries',
+          'cities',
+          'leads',
+          'sales',
+          'composite',
+        ],
+      },
+      interval: {
+        type: 'string',
+        description: 'The interval to retrieve analytics for. Takes precedence over start and end.',
+        enum: ['1h', '24h', '7d', '30d', '90d', 'ytd', '1y', 'all', 'all_unfiltered'],
+      },
+      key: {
+        type: 'string',
+        description: 'The short link slug.',
+      },
+      linkId: {
+        type: 'string',
+        description: 'The unique ID of the short link on CodeQR.',
+      },
+      os: {
+        type: 'string',
+        description: 'The OS to retrieve analytics for.',
+      },
+      pageId: {
+        type: 'string',
+        description: 'The unique ID of the page on CodeQR.',
+      },
+      qrcodeId: {
+        type: 'string',
+        description: 'The unique ID of the QR code on CodeQR.',
+      },
+      referer: {
+        type: 'string',
+        description: 'The referer to retrieve analytics for.',
+      },
+      root: {
+        type: 'boolean',
+        description:
+          'Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.',
+      },
+      start: {
+        type: 'string',
+        description: 'The start date and time when to retrieve analytics from.',
+      },
+      tagId: {
+        type: 'string',
+        description: 'The tag ID to retrieve analytics for.',
+      },
+      timezone: {
+        type: 'string',
+        description:
+          'The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.',
+      },
+      type: {
+        type: 'string',
+        description: 'The type of analytics to retrieve.',
+      },
+      types: {
+        type: 'string',
+        description: 'The types of analytics to retrieve.',
+      },
+      url: {
+        type: 'string',
+        description: 'The URL to retrieve analytics for.',
+      },
+    },
+    required: [],
+    $defs: {
+      continent_code: {
+        type: 'string',
+        description: 'The continent to retrieve analytics for.',
+        enum: ['AF', 'AN', 'AS', 'EU', 'NA', 'OC', 'SA'],
+      },
+      country_code: {
+        type: 'string',
+        description: 'The country to retrieve analytics for.',
+        enum: [
+          'AF',
+          'AL',
+          'DZ',
+          'AS',
+          'AD',
+          'AO',
+          'AI',
+          'AQ',
+          'AG',
+          'AR',
+          'AM',
+          'AW',
+          'AU',
+          'AT',
+          'AZ',
+          'BS',
+          'BH',
+          'BD',
+          'BB',
+          'BY',
+          'BE',
+          'BZ',
+          'BJ',
+          'BM',
+          'BT',
+          'BO',
+          'BA',
+          'BW',
+          'BV',
+          'BR',
+          'IO',
+          'BN',
+          'BG',
+          'BF',
+          'BI',
+          'KH',
+          'CM',
+          'CA',
+          'CV',
+          'KY',
+          'CF',
+          'TD',
+          'CL',
+          'CN',
+          'CX',
+          'CC',
+          'CO',
+          'KM',
+          'CG',
+          'CD',
+          'CK',
+          'CR',
+          'CI',
+          'HR',
+          'CU',
+          'CY',
+          'CZ',
+          'DK',
+          'DJ',
+          'DM',
+          'DO',
+          'EC',
+          'EG',
+          'SV',
+          'GQ',
+          'ER',
+          'EE',
+          'ET',
+          'FK',
+          'FO',
+          'FJ',
+          'FI',
+          'FR',
+          'GF',
+          'PF',
+          'TF',
+          'GA',
+          'GM',
+          'GE',
+          'DE',
+          'GH',
+          'GI',
+          'GR',
+          'GL',
+          'GD',
+          'GP',
+          'GU',
+          'GT',
+          'GN',
+          'GW',
+          'GY',
+          'HT',
+          'HM',
+          'VA',
+          'HN',
+          'HK',
+          'HU',
+          'IS',
+          'IN',
+          'ID',
+          'IR',
+          'IQ',
+          'IE',
+          'IL',
+          'IT',
+          'JM',
+          'JP',
+          'JO',
+          'KZ',
+          'KE',
+          'KI',
+          'KP',
+          'KR',
+          'KW',
+          'KG',
+          'LA',
+          'LV',
+          'LB',
+          'LS',
+          'LR',
+          'LY',
+          'LI',
+          'LT',
+          'LU',
+          'MO',
+          'MG',
+          'MW',
+          'MY',
+          'MV',
+          'ML',
+          'MT',
+          'MH',
+          'MQ',
+          'MR',
+          'MU',
+          'YT',
+          'MX',
+          'FM',
+          'MD',
+          'MC',
+          'MN',
+          'MS',
+          'MA',
+          'MZ',
+          'MM',
+          'NA',
+          'NR',
+          'NP',
+          'NL',
+          'NC',
+          'NZ',
+          'NI',
+          'NE',
+          'NG',
+          'NU',
+          'NF',
+          'MK',
+          'MP',
+          'NO',
+          'OM',
+          'PK',
+          'PW',
+          'PS',
+          'PA',
+          'PG',
+          'PY',
+          'PE',
+          'PH',
+          'PN',
+          'PL',
+          'PT',
+          'PR',
+          'QA',
+          'RE',
+          'RO',
+          'RU',
+          'RW',
+          'SH',
+          'KN',
+          'LC',
+          'PM',
+          'VC',
+          'WS',
+          'SM',
+          'ST',
+          'SA',
+          'SN',
+          'SC',
+          'SL',
+          'SG',
+          'SK',
+          'SI',
+          'SB',
+          'SO',
+          'ZA',
+          'GS',
+          'ES',
+          'LK',
+          'SD',
+          'SR',
+          'SJ',
+          'SZ',
+          'SE',
+          'CH',
+          'SY',
+          'TW',
+          'TJ',
+          'TZ',
+          'TH',
+          'TL',
+          'TG',
+          'TK',
+          'TO',
+          'TT',
+          'TN',
+          'TR',
+          'TM',
+          'TC',
+          'TV',
+          'UG',
+          'UA',
+          'AE',
+          'GB',
+          'US',
+          'UM',
+          'UY',
+          'UZ',
+          'VU',
+          'VE',
+          'VN',
+          'VG',
+          'VI',
+          'WF',
+          'EH',
+          'YE',
+          'ZM',
+          'ZW',
+          'AX',
+          'BQ',
+          'CW',
+          'GG',
+          'IM',
+          'JE',
+          'ME',
+          'BL',
+          'MF',
+          'RS',
+          'SX',
+          'SS',
+          'XK',
+        ],
+      },
+    },
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+export const handler = async (client: Codeqr, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  return asTextContentResult(await client.analytics.retrieve(body));
+};
+
+export default { metadata, tool, handler };

package/src/tools/domains/create-domains.ts

@@ -0,0 +1,59 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from '@codeqr/ts-mcp/filtering';
+import { Metadata, asTextContentResult } from '@codeqr/ts-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Codeqr from '@codeqr/ts';
+
+export const metadata: Metadata = {
+  resource: 'domains',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'post',
+  httpPath: '/domains',
+  operationId: 'createDomain',
+};
+
+export const tool: Tool = {
+  name: 'create_domains',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nCreate a domain for the authenticated workspace.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/domain',\n  $defs: {\n    domain: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'The unique identifier of the domain.'\n        },\n        archived: {\n          type: 'boolean',\n          description: 'Whether the domain is archived.'\n        },\n        createdAt: {\n          type: 'string',\n          description: 'The date the domain was created.'\n        },\n        expiredUrl: {\n          type: 'string',\n          description: 'The URL to redirect to when a link under this domain has expired.'\n        },\n        placeholder: {\n          type: 'string',\n          description: 'Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened.'\n        },\n        primary: {\n          type: 'boolean',\n          description: 'Whether the domain is the primary domain for the project.'\n        },\n        slug: {\n          type: 'string',\n          description: 'The domain name.'\n        },\n        updatedAt: {\n          type: 'string',\n          description: 'The date the domain was last updated.'\n        },\n        verified: {\n          type: 'boolean',\n          description: 'Whether the domain is verified.'\n        }\n      },\n      required: [        'id',\n        'archived',\n        'createdAt',\n        'expiredUrl',\n        'placeholder',\n        'primary',\n        'slug',\n        'updatedAt',\n        'verified'\n      ]\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      slug: {
+        type: 'string',
+        description: 'Name of the domain.',
+      },
+      archived: {
+        type: 'boolean',
+        description: 'Whether to archive this domain. `false` will unarchive a previously archived domain.',
+      },
+      expiredUrl: {
+        type: 'string',
+        description: 'Redirect users to a specific URL when any link under this domain has expired.',
+      },
+      placeholder: {
+        type: 'string',
+        description:
+          'Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened.',
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: ['slug'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: Codeqr, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  return asTextContentResult(await maybeFilter(jq_filter, await client.domains.create(body)));
+};
+
+export default { metadata, tool, handler };