graphql-agent-toolkit 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,260 @@
+import { IntrospectionQuery } from 'graphql';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+interface SchemaField {
+    name: string;
+    description: string | null;
+    type: TypeRef;
+    args: SchemaArgument[];
+    isDeprecated: boolean;
+}
+interface SchemaArgument {
+    name: string;
+    description: string | null;
+    type: TypeRef;
+    defaultValue: string | null;
+}
+interface TypeRef {
+    kind: 'SCALAR' | 'OBJECT' | 'INTERFACE' | 'UNION' | 'ENUM' | 'INPUT_OBJECT' | 'LIST' | 'NON_NULL';
+    name: string | null;
+    ofType: TypeRef | null;
+}
+interface SchemaType {
+    name: string;
+    kind: TypeRef['kind'];
+    description: string | null;
+    fields: SchemaField[];
+    inputFields: SchemaArgument[];
+    enumValues: {
+        name: string;
+        description: string | null;
+    }[];
+    interfaces: string[];
+    possibleTypes: string[];
+}
+interface ParsedSchema {
+    queryType: string;
+    mutationType: string | null;
+    subscriptionType: string | null;
+    types: Map<string, SchemaType>;
+}
+interface AgentToolkitConfig {
+    endpoint: string;
+    headers?: Record<string, string>;
+    operationDepth?: number;
+    includeDeprecated?: boolean;
+}
+
+interface FetchSchemaOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+}
+declare function fetchSchema(options: FetchSchemaOptions): Promise<IntrospectionQuery>;
+
+declare function parseSchema(introspectionResult: IntrospectionQuery): ParsedSchema;
+
+interface VariableDefinition {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+interface GeneratedOperation {
+    operation: string;
+    operationName: string;
+    variables: VariableDefinition[];
+    operationType: 'query' | 'mutation';
+}
+interface BuildOperationOptions {
+    maxDepth?: number;
+    includeDeprecated?: boolean;
+}
+declare function buildOperation(schema: ParsedSchema, rootFieldName: string, options?: BuildOperationOptions): GeneratedOperation;
+
+interface AgentToolkitServerOptions {
+    serverName?: string;
+    serverVersion?: string;
+}
+/**
+ * Creates a fully configured MCP server from a GraphQL endpoint configuration.
+ */
+declare function createAgentToolkitServer(config: AgentToolkitConfig, options?: AgentToolkitServerOptions): Promise<McpServer>;
+
+declare class GraphQLExecutor {
+    private client;
+    constructor(endpoint: string, headers?: Record<string, string>);
+    execute(operation: string, variables?: Record<string, unknown>, additionalHeaders?: Record<string, string>): Promise<string>;
+}
+
+interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType>;
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+interface CreateToolsOptions {
+    maxDepth?: number;
+    includeDeprecated?: boolean;
+}
+/**
+ * Creates MCP tool definitions from a parsed GraphQL schema.
+ */
+declare function createToolsFromSchema(schema: ParsedSchema, executor: GraphQLExecutor, options?: CreateToolsOptions): McpToolDefinition[];
+
+interface SearchResult {
+    typeName: string;
+    score: number;
+    kind: string;
+    description: string | null;
+}
+/**
+ * SchemaNavigator provides semantic search over a GraphQL schema
+ * using TF-IDF and cosine similarity.
+ */
+declare class SchemaNavigator {
+    private schema;
+    private documents;
+    private idf;
+    /**
+     * Index a parsed schema for semantic search.
+     */
+    index(schema: ParsedSchema): void;
+    /**
+     * Search the schema for types matching the query.
+     */
+    search(query: string, limit?: number): SearchResult[];
+    /**
+     * Get formatted context for a specific type.
+     */
+    getTypeContext(typeName: string): string | null;
+    private computeIdf;
+    private computeTfidf;
+    private cosineSimilarity;
+}
+
+interface PaginationConfig {
+    style: 'relay' | 'offset' | 'auto';
+    pageSize: number;
+    maxPages?: number;
+}
+interface PaginatedResult<T = unknown> {
+    items: T[];
+    totalFetched: number;
+    hasMore: boolean;
+    cursors?: {
+        start: string;
+        end: string;
+    };
+}
+/**
+ * Auto-detect pagination style from a type's fields.
+ *
+ * Relay: The type has an `edges` field whose unwrapped type has a `node` field,
+ *        AND a `pageInfo` field whose type has `hasNextPage` and `endCursor`.
+ *
+ * Offset: The type (or its parent query field) has `limit`/`offset` or `skip`/`take` args.
+ *         We detect this by looking for fields on the Query type that return this typeName
+ *         and have offset-style arguments.
+ */
+declare function detectPaginationStyle(schema: ParsedSchema, typeName: string): 'relay' | 'offset' | 'none';
+/**
+ * Execute a paginated query, collecting all pages.
+ */
+declare function executePaginated(executor: GraphQLExecutor, operation: string, variables: Record<string, unknown>, config?: PaginationConfig): Promise<PaginatedResult>;
+
+interface SummaryConfig {
+    maxItems: number;
+    maxDepth: number;
+    maxStringLength: number;
+    includeMetadata: boolean;
+}
+interface SummaryMetadata {
+    totalItems: number;
+    truncated: boolean;
+    originalSize: number;
+}
+/**
+ * Summarize a GraphQL response by truncating arrays, limiting depth,
+ * and shortening long strings.
+ */
+declare function summarizeResponse(data: unknown, config?: Partial<SummaryConfig>): {
+    summary: unknown;
+    metadata: SummaryMetadata;
+};
+/**
+ * Format data as clean markdown suitable for LLM context.
+ */
+declare function formatForLLM(data: unknown, config?: Partial<SummaryConfig>): string;
+
+interface LangChainToolConfig {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    func: (input: string) => Promise<string>;
+}
+interface StructuredToolConfig {
+    name: string;
+    description: string;
+    schema: z.ZodObject<Record<string, z.ZodType>>;
+    func: (input: Record<string, unknown>) => Promise<string>;
+}
+interface AdapterOptions$2 {
+    maxDepth?: number;
+}
+/**
+ * Create tools compatible with LangChain's Tool pattern.
+ * Each tool's func accepts a JSON string input and returns a JSON string.
+ */
+declare function createLangChainTools(schema: ParsedSchema, executor: GraphQLExecutor, options?: AdapterOptions$2): LangChainToolConfig[];
+/**
+ * Create tools compatible with LangChain's StructuredTool pattern.
+ * Each tool's func accepts a typed object and returns a JSON string.
+ */
+declare function createStructuredTools(schema: ParsedSchema, executor: GraphQLExecutor, options?: AdapterOptions$2): StructuredToolConfig[];
+
+interface CrewAIToolConfig {
+    name: string;
+    description: string;
+    args_schema: Record<string, unknown>;
+    func: (args: Record<string, unknown>) => Promise<string>;
+}
+interface AdapterOptions$1 {
+    maxDepth?: number;
+}
+/**
+ * Create tools compatible with CrewAI's tool interface.
+ * CrewAI uses args_schema (JSON Schema) and func takes a dict.
+ */
+declare function createCrewAITools(schema: ParsedSchema, executor: GraphQLExecutor, options?: AdapterOptions$1): CrewAIToolConfig[];
+
+interface VercelAIToolConfig {
+    description: string;
+    parameters: z.ZodObject<Record<string, z.ZodType>>;
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+interface AdapterOptions {
+    maxDepth?: number;
+}
+/**
+ * Create tools compatible with Vercel AI SDK's tool() shape.
+ * Returns Record<toolName, { description, parameters: ZodSchema, execute }>.
+ */
+declare function createVercelAITools(schema: ParsedSchema, executor: GraphQLExecutor, options?: AdapterOptions): Record<string, VercelAIToolConfig>;
+
+interface MockConfig {
+    seed?: number;
+    arrayLength?: number;
+    maxDepth?: number;
+}
+/**
+ * Generate mock data for a specific type in the schema.
+ */
+declare function generateMockData(schema: ParsedSchema, typeName: string, config?: MockConfig): Record<string, unknown>;
+/**
+ * Create a mock executor that returns generated data instead of HTTP calls.
+ * Implements the same interface as GraphQLExecutor.
+ */
+declare function createMockExecutor(schema: ParsedSchema, config?: MockConfig): GraphQLExecutor;
+
+export { type AgentToolkitConfig, type CrewAIToolConfig, type GeneratedOperation, GraphQLExecutor, type LangChainToolConfig, type MockConfig, type PaginatedResult, type PaginationConfig, type ParsedSchema, type SchemaArgument, type SchemaField, SchemaNavigator, type SchemaType, type SearchResult, type StructuredToolConfig, type SummaryConfig, type SummaryMetadata, type TypeRef, type VariableDefinition, type VercelAIToolConfig, buildOperation, createAgentToolkitServer, createCrewAITools, createLangChainTools, createMockExecutor, createStructuredTools, createToolsFromSchema, createVercelAITools, detectPaginationStyle, executePaginated, fetchSchema, formatForLLM, generateMockData, parseSchema, summarizeResponse };