profound-mcp 0.2.1

package/src/server.ts

@@ -0,0 +1,207 @@
+// 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 'profoundai';
+import Profound from 'profoundai';
+import {
+  applyCompatibilityTransformations,
+  ClientCapabilities,
+  defaultClientCapabilities,
+  knownClients,
+  parseEmbeddedJSON,
+} from './compat';
+import { dynamicTools } from './dynamic-tools';
+import { codeTool } from './code-tool';
+import docsSearchTool from './docs-search-tool';
+import { McpOptions } from './options';
+
+export { McpOptions } from './options';
+export { ClientType } from './compat';
+export { Filter } from './tools';
+export { ClientOptions } from 'profoundai';
+export { endpoints } from './tools';
+
+export const newMcpServer = () =>
+  new McpServer(
+    {
+      name: 'profoundai_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 Profound({
+    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.slice();
+
+  if (includedTools.length > 0) {
+    if (options?.includeDynamicTools) {
+      includedTools = dynamicTools(includedTools);
+    }
+  } else {
+    if (options?.includeAllTools) {
+      includedTools = endpoints.slice();
+    } else if (options?.includeDynamicTools) {
+      includedTools = dynamicTools(endpoints);
+    } else if (options?.includeCodeTools) {
+      includedTools = [await codeTool()];
+    } else {
+      includedTools = endpoints.slice();
+    }
+  }
+  if (options?.includeDocsTools ?? true) {
+    includedTools.push(docsSearchTool);
+  }
+  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: Profound,
+  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/index.ts

@@ -0,0 +1,95 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, Endpoint, HandlerFunction } from './types';
+
+export { Metadata, Endpoint, HandlerFunction };
+
+import domains_organizations from './organizations/domains-organizations';
+import models_organizations from './organizations/models-organizations';
+import regions_organizations from './organizations/regions-organizations';
+import list_organizations_categories from './organizations/categories/list-organizations-categories';
+import prompts_organizations_categories from './organizations/categories/prompts-organizations-categories';
+import tags_organizations_categories from './organizations/categories/tags-organizations-categories';
+import topics_organizations_categories from './organizations/categories/topics-organizations-categories';
+import answers_prompts from './prompts/answers-prompts';
+import citations_reports from './reports/citations-reports';
+import sentiment_reports from './reports/sentiment-reports';
+import visibility_reports from './reports/visibility-reports';
+import bots_logs_raw from './logs/raw/bots-logs-raw';
+import logs_logs_raw from './logs/raw/logs-logs-raw';
+
+export const endpoints: Endpoint[] = [];
+
+function addEndpoint(endpoint: Endpoint) {
+  endpoints.push(endpoint);
+}
+
+addEndpoint(domains_organizations);
+addEndpoint(models_organizations);
+addEndpoint(regions_organizations);
+addEndpoint(list_organizations_categories);
+addEndpoint(prompts_organizations_categories);
+addEndpoint(tags_organizations_categories);
+addEndpoint(topics_organizations_categories);
+addEndpoint(answers_prompts);
+addEndpoint(citations_reports);
+addEndpoint(sentiment_reports);
+addEndpoint(visibility_reports);
+addEndpoint(bots_logs_raw);
+addEndpoint(logs_logs_raw);
+
+export type Filter = {
+  type: 'resource' | 'operation' | 'tag' | 'tool';
+  op: 'include' | 'exclude';
+  value: string;
+};
+
+export function query(filters: Filter[], endpoints: Endpoint[]): Endpoint[] {
+  const allExcludes = filters.length > 0 && filters.every((filter) => filter.op === 'exclude');
+  const unmatchedFilters = new Set(filters);
+
+  const filtered = endpoints.filter((endpoint: Endpoint) => {
+    let included = false || allExcludes;
+
+    for (const filter of filters) {
+      if (match(filter, endpoint)) {
+        unmatchedFilters.delete(filter);
+        included = filter.op === 'include';
+      }
+    }
+
+    return included;
+  });
+
+  // Check if any filters didn't match
+  const unmatched = Array.from(unmatchedFilters).filter((f) => f.type === 'tool' || f.type === 'resource');
+  if (unmatched.length > 0) {
+    throw new Error(
+      `The following filters did not match any endpoints: ${unmatched
+        .map((f) => `${f.type}=${f.value}`)
+        .join(', ')}`,
+    );
+  }
+
+  return filtered;
+}
+
+function match({ type, value }: Filter, endpoint: Endpoint): boolean {
+  switch (type) {
+    case 'resource': {
+      const regexStr = '^' + normalizeResource(value).replace(/\*/g, '.*') + '$';
+      const regex = new RegExp(regexStr);
+      return regex.test(normalizeResource(endpoint.metadata.resource));
+    }
+    case 'operation':
+      return endpoint.metadata.operation === value;
+    case 'tag':
+      return endpoint.metadata.tags.includes(value);
+    case 'tool':
+      return endpoint.tool.name === value;
+  }
+}
+
+function normalizeResource(resource: string): string {
+  return resource.toLowerCase().replace(/[^a-z.*\-_]*/g, '');
+}

package/src/tools/logs/raw/bots-logs-raw.ts

@@ -0,0 +1,196 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from 'profound-mcp/filtering';
+import { Metadata, asTextContentResult } from 'profound-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Profound from 'profoundai';
+
+export const metadata: Metadata = {
+  resource: 'logs.raw',
+  operation: 'write',
+  tags: [],
+  httpMethod: 'post',
+  httpPath: '/v1/logs/raw/bots',
+  operationId: 'get_bots_v1_logs_raw_bots_post',
+};
+
+export const tool: Tool = {
+  name: 'bots_logs_raw',
+  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\nGet identified bot logs with filters\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/raw_bots_response',\n  $defs: {\n    raw_bots_response: {\n      anyOf: [        {\n          type: 'array',\n          title: 'LogVisitBotList',\n          items: {\n            type: 'object',\n            title: 'LogVisitBot',\n            description: 'DB Model for a bot visit.',\n            properties: {\n              bot_name: {\n                type: 'string',\n                title: 'Bot Name'\n              },\n              bot_provider: {\n                type: 'string',\n                title: 'Bot Provider'\n              },\n              bot_types: {\n                type: 'array',\n                title: 'Bot Types',\n                items: {\n                  type: 'string',\n                  enum: [                    'ai_assistant',\n                    'ai_training',\n                    'index'\n                  ]\n                }\n              },\n              host: {\n                type: 'string',\n                title: 'Host'\n              },\n              ip: {\n                type: 'string',\n                title: 'Ip'\n              },\n              method: {\n                type: 'string',\n                title: 'Method'\n              },\n              org_id: {\n                type: 'string',\n                title: 'Org Id'\n              },\n              path: {\n                type: 'string',\n                title: 'Path'\n              },\n              status_code: {\n                type: 'integer',\n                title: 'Status Code'\n              },\n              timestamp: {\n                type: 'string',\n                title: 'Timestamp',\n                format: 'date-time'\n              },\n              user_agent: {\n                type: 'string',\n                title: 'User Agent'\n              },\n              bytes_sent: {\n                type: 'integer',\n                title: 'Bytes Sent'\n              },\n              duration_ms: {\n                type: 'integer',\n                title: 'Duration Ms'\n              },\n              query_params: {\n                type: 'object',\n                title: 'Query Params',\n                additionalProperties: true\n              },\n              referer: {\n                type: 'string',\n                title: 'Referer'\n              }\n            },\n            required: [              'bot_name',\n              'bot_provider',\n              'bot_types',\n              'host',\n              'ip',\n              'method',\n              'org_id',\n              'path',\n              'status_code',\n              'timestamp',\n              'user_agent'\n            ]\n          }\n        },\n        {\n          $ref: '#/$defs/report_response'\n        }\n      ],\n      title: 'Response Get Bots V1 Logs Raw Bots Post',\n      description: 'Base response model for reports.'\n    },\n    report_response: {\n      type: 'object',\n      title: 'Response',\n      description: 'Base response model for reports.',\n      properties: {\n        data: {\n          type: 'array',\n          title: 'Data',\n          items: {\n            $ref: '#/$defs/report_result'\n          }\n        },\n        info: {\n          $ref: '#/$defs/report_info'\n        }\n      },\n      required: [        'data',\n        'info'\n      ]\n    },\n    report_result: {\n      type: 'object',\n      title: 'Result',\n      description: 'Base model for report results.',\n      properties: {\n        dimensions: {\n          type: 'array',\n          title: 'Dimensions',\n          items: {\n            type: 'string'\n          }\n        },\n        metrics: {\n          type: 'array',\n          title: 'Metrics',\n          items: {\n            type: 'number'\n          }\n        }\n      },\n      required: [        'dimensions',\n        'metrics'\n      ]\n    },\n    report_info: {\n      type: 'object',\n      title: 'Info',\n      description: 'Base model for report information.',\n      properties: {\n        total_rows: {\n          type: 'integer',\n          title: 'Total Rows'\n        },\n        query: {\n          type: 'object',\n          title: 'Query',\n          additionalProperties: true\n        }\n      },\n      required: [        'total_rows'\n      ]\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      domain: {
+        type: 'string',
+        title: 'Domain',
+        description: 'Domain to query logs for.',
+      },
+      metrics: {
+        type: 'array',
+        title: 'Metrics',
+        items: {
+          type: 'string',
+          enum: ['count'],
+        },
+      },
+      start_date: {
+        type: 'string',
+        title: 'Start Date',
+        description:
+          'Start date for logs. Accepts: YYYY-MM-DD, YYYY-MM-DD HH:MM, YYYY-MM-DD HH:MM:SS, or full ISO timestamp.',
+        format: 'date-time',
+      },
+      date_interval: {
+        type: 'string',
+        title: 'Date Interval',
+        description: 'Date interval for the report. (only used with date dimension)',
+        enum: ['day', 'week', 'month', 'year'],
+      },
+      dimensions: {
+        type: 'array',
+        title: 'Dimensions',
+        description: 'Dimensions to group the report by.',
+        items: {
+          type: 'string',
+          enum: [
+            'method',
+            'path',
+            'status_code',
+            'ip',
+            'user_agent',
+            'referer',
+            'query_params',
+            'bot_name',
+            'bot_provider',
+            'bot_types',
+          ],
+        },
+      },
+      end_date: {
+        type: 'string',
+        title: 'End Date',
+        description: 'End date for logs. Accepts same formats as start_date. Defaults to now if omitted.',
+        format: 'date-time',
+      },
+      filters: {
+        type: 'array',
+        title: 'Filters',
+        description: 'List of filters to apply to the report. Each filter has an operator, field, and value.',
+        items: {
+          type: 'object',
+          title:
+            "Filter[Literal['method', 'path', 'status_code', 'ip', 'user_agent', 'referer', 'query_params', 'bot_name', 'bot_provider', 'bot_types']]",
+          properties: {
+            field: {
+              type: 'string',
+              title: 'Field',
+              enum: [
+                'method',
+                'path',
+                'status_code',
+                'ip',
+                'user_agent',
+                'referer',
+                'query_params',
+                'bot_name',
+                'bot_provider',
+                'bot_types',
+              ],
+            },
+            operator: {
+              type: 'string',
+              title: 'Operator',
+              enum: [
+                'is',
+                'not_is',
+                'in',
+                'not_in',
+                'contains',
+                'not_contains',
+                'contains_case_insensitive',
+                'not_contains_case_insensitive',
+                'matches',
+              ],
+            },
+            value: {
+              anyOf: [
+                {
+                  type: 'string',
+                  title: 'FilterStringValue',
+                },
+                {
+                  type: 'array',
+                  title: 'FilterStringListValue',
+                  items: {
+                    type: 'string',
+                  },
+                },
+                {
+                  type: 'integer',
+                  title: 'FilterIntegerValue',
+                },
+                {
+                  type: 'array',
+                  title: 'FilterIntegerListValue',
+                  items: {
+                    type: 'integer',
+                  },
+                },
+              ],
+              title: 'Value',
+              description:
+                'Value for the filter. Can be a single value or a list of depending on the operator.',
+            },
+          },
+          required: ['field', 'operator', 'value'],
+        },
+      },
+      order_by: {
+        type: 'object',
+        title: 'Order By',
+        description:
+          "\nCustom ordering of the report results.\n\nThe order is a record of key-value pairs where:\n- key is the field to order by, which can be a metric or dimension\n- value is the direction of the order, either 'asc' for ascending or 'desc' for descending.\n\nWhen not specified, the default order is the first metric in the query descending.\n        ",
+        additionalProperties: true,
+      },
+      pagination: {
+        $ref: '#/$defs/pagination',
+      },
+      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: ['domain', 'metrics', 'start_date'],
+    $defs: {
+      pagination: {
+        type: 'object',
+        title: 'Pagination',
+        description: 'Report pagination model.',
+        properties: {
+          limit: {
+            type: 'integer',
+            title: 'Limit',
+            description: 'Maximum number of results to return. Default is 10,000, maximum is 50,000.',
+          },
+          offset: {
+            type: 'integer',
+            title: 'Offset',
+            description: 'Offset for the results. Used for pagination.',
+          },
+        },
+      },
+    },
+  },
+  annotations: {},
+};
+
+export const handler = async (client: Profound, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  return asTextContentResult(await maybeFilter(jq_filter, await client.logs.raw.bots(body)));
+};
+
+export default { metadata, tool, handler };