@kiyeonjeon21/datacontext 0.2.0 → 0.3.1

package/src/mcp/tools.ts

@@ -263,6 +263,98 @@ export function getMcpTools(): Tool[] {
         required: ['name', 'description', 'tables'],
       },
     },
+    // === Glossary Tools ===
+    {
+      name: 'generate_glossary',
+      description: 'Generate business glossary/terms from user input using AI. Takes natural language term definitions and creates structured SQL-ready glossary entries. Requires ANTHROPIC_API_KEY to be set.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          terms: {
+            type: 'string',
+            description: 'Raw term definitions in natural language. Can be comma-separated, one per line, or structured (YAML-like). Example: "활성 사용자 = status가 1인 사용자\\n최근 주문 = 30일 이내 주문\\nVIP = 주문 10건 이상"',
+          },
+        },
+        required: ['terms'],
+      },
+    },
+    {
+      name: 'add_term',
+      description: 'Add a single business term to the glossary manually.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          term: {
+            type: 'string',
+            description: 'The business term (e.g., "활성 사용자", "active user").',
+          },
+          definition: {
+            type: 'string',
+            description: 'Human-readable definition of the term.',
+          },
+          sql: {
+            type: 'string',
+            description: 'SQL expression for this term (e.g., "status = 1").',
+          },
+          synonyms: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Alternative names for this term.',
+          },
+          tables: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Tables this term applies to.',
+          },
+        },
+        required: ['term', 'definition'],
+      },
+    },
+    {
+      name: 'list_terms',
+      description: 'List all business terms in the glossary.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          category: {
+            type: 'string',
+            description: 'Filter by category (status, time, money, entity, metric, filter, custom).',
+          },
+          table: {
+            type: 'string',
+            description: 'Filter by table name.',
+          },
+        },
+      },
+    },
+    {
+      name: 'search_terms',
+      description: 'Search for business terms that match a query. Useful for finding relevant terms before generating SQL.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Search query to match against term names and synonyms.',
+          },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'enhance_query',
+      description: 'Enhance a natural language query by matching it against the business glossary. Returns suggested SQL conditions based on matched terms. Requires ANTHROPIC_API_KEY.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Natural language query to enhance (e.g., "활성 사용자 중 최근 주문한 VIP 고객")',
+          },
+        },
+        required: ['query'],
+      },
+    },
   ];
 }
 
@@ -298,6 +390,17 @@ export async function handleToolCall(
       return handleAddQueryExample(args, context);
     case 'add_business_rule':
       return handleAddBusinessRule(args, context);
+    // === Glossary Tools ===
+    case 'generate_glossary':
+      return handleGenerateGlossary(args, context);
+    case 'add_term':
+      return handleAddTerm(args, context);
+    case 'list_terms':
+      return handleListTerms(args, context);
+    case 'search_terms':
+      return handleSearchTerms(args, context);
+    case 'enhance_query':
+      return handleEnhanceQuery(args, context);
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
@@ -820,6 +923,318 @@ async function handleAddBusinessRule(
   };
 }
 
+// ============================================================
+// Glossary Tool Handlers
+// ============================================================
+
+/**
+ * Handle generate_glossary tool - AI-powered glossary generation
+ */
+async function handleGenerateGlossary(
+  args: Record<string, unknown>,
+  context: ToolContext
+): Promise<unknown> {
+  const terms = args.terms as string;
+
+  if (!terms) {
+    throw new Error('terms is required');
+  }
+
+  // Check if LLM is available
+  const { isLLMAvailable, createLLMService } = await import('../core/llm-service.js');
+  
+  if (!isLLMAvailable()) {
+    return {
+      success: false,
+      error: 'ANTHROPIC_API_KEY not configured. Set the environment variable to use AI-powered glossary generation.',
+      tip: 'You can still add terms manually using the add_term tool.',
+    };
+  }
+
+  try {
+    // Get schema context
+    const schemaInfo = await context.adapter.getSchema();
+    const schemaContext = {
+      tables: schemaInfo.tables.slice(0, 20).map(table => ({
+        name: table.name,
+        columns: table.columns.map(c => ({
+          name: c.name,
+          type: c.dataType,
+          nullable: c.isNullable,
+        })),
+      })),
+      existingTerms: context.knowledge.getBusinessTerms(),
+    };
+
+    const llm = createLLMService();
+    const generatedTerms = await llm.generateGlossary(
+      terms,
+      schemaContext,
+      context.knowledge.getSchemaHash()
+    );
+
+    // Add to knowledge store
+    const added = await context.knowledge.addBusinessTerms(generatedTerms);
+
+    return {
+      success: true,
+      generated: added.length,
+      terms: added.map(t => ({
+        term: t.term,
+        definition: t.definition,
+        sql: t.sqlExpression,
+        category: t.category,
+        tables: t.appliesTo?.tables,
+      })),
+      message: `Generated and added ${added.length} business term(s) to glossary.`,
+      tip: 'These terms will now be used to enhance query understanding.',
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      tip: 'Check your API key and try again with simpler term definitions.',
+    };
+  }
+}
+
+/**
+ * Handle add_term tool - manual term addition
+ */
+async function handleAddTerm(
+  args: Record<string, unknown>,
+  context: ToolContext
+): Promise<unknown> {
+  const term = args.term as string;
+  const definition = args.definition as string;
+  const sql = args.sql as string | undefined;
+  const synonyms = args.synonyms as string[] | undefined;
+  const tables = args.tables as string[] | undefined;
+
+  if (!term) throw new Error('term is required');
+  if (!definition) throw new Error('definition is required');
+
+  const added = await context.knowledge.addBusinessTerm(term, definition, {
+    sqlExpression: sql,
+    synonyms,
+    appliesTo: tables ? { tables } : undefined,
+  });
+
+  return {
+    success: true,
+    term: added.term,
+    definition: added.definition,
+    sql: added.sqlExpression,
+    synonyms: added.synonyms,
+    tables: added.appliesTo?.tables,
+    message: `Added term "${term}" to glossary.`,
+    tip: 'This term will be used in query context when relevant.',
+  };
+}
+
+/**
+ * Handle list_terms tool
+ */
+async function handleListTerms(
+  args: Record<string, unknown>,
+  context: ToolContext
+): Promise<unknown> {
+  const category = args.category as string | undefined;
+  const table = args.table as string | undefined;
+
+  let terms = context.knowledge.getActiveTerms();
+
+  // Apply filters
+  if (category) {
+    terms = terms.filter(t => t.category === category);
+  }
+  if (table) {
+    terms = terms.filter(t => t.appliesTo?.tables?.includes(table));
+  }
+
+  if (terms.length === 0) {
+    return {
+      count: 0,
+      terms: [],
+      message: 'No business terms found.',
+      tip: 'Add terms using add_term or generate_glossary.',
+    };
+  }
+
+  return {
+    count: terms.length,
+    terms: terms.map(t => ({
+      id: t.id,
+      term: t.term,
+      synonyms: t.synonyms,
+      definition: t.definition,
+      sql: t.sqlExpression,
+      category: t.category,
+      tables: t.appliesTo?.tables,
+      isActive: t.isActive,
+    })),
+    categories: [...new Set(terms.map(t => t.category).filter(Boolean))],
+  };
+}
+
+/**
+ * Handle search_terms tool
+ */
+async function handleSearchTerms(
+  args: Record<string, unknown>,
+  context: ToolContext
+): Promise<unknown> {
+  const query = args.query as string;
+
+  if (!query) {
+    throw new Error('query is required');
+  }
+
+  const terms = context.knowledge.findMatchingTerms(query);
+
+  if (terms.length === 0) {
+    return {
+      count: 0,
+      terms: [],
+      message: `No terms found matching "${query}".`,
+      tip: 'Try a broader search or check available terms with list_terms.',
+    };
+  }
+
+  return {
+    query,
+    count: terms.length,
+    terms: terms.map(t => ({
+      term: t.term,
+      synonyms: t.synonyms,
+      definition: t.definition,
+      sql: t.sqlExpression,
+      category: t.category,
+      relevance: calculateTermRelevance(query, t),
+    })),
+    suggestedConditions: terms
+      .filter(t => t.sqlExpression)
+      .map(t => t.sqlExpression as string),
+    message: `Found ${terms.length} term(s) matching "${query}".`,
+  };
+}
+
+/**
+ * Handle enhance_query tool - AI-powered query enhancement
+ */
+async function handleEnhanceQuery(
+  args: Record<string, unknown>,
+  context: ToolContext
+): Promise<unknown> {
+  const query = args.query as string;
+
+  if (!query) {
+    throw new Error('query is required');
+  }
+
+  // First try local matching (no LLM)
+  const localMatches = context.knowledge.findMatchingTerms(query);
+  
+  if (localMatches.length > 0) {
+    const suggestedConditions = localMatches
+      .filter(t => t.sqlExpression)
+      .map(t => t.sqlExpression as string);
+
+    return {
+      success: true,
+      method: 'local',
+      query,
+      enhancedQuery: query,
+      usedTerms: localMatches.map(t => t.term),
+      suggestedConditions,
+      terms: localMatches.map(t => ({
+        term: t.term,
+        sql: t.sqlExpression,
+        category: t.category,
+      })),
+      tip: 'Use these SQL conditions in your WHERE clause.',
+    };
+  }
+
+  // Try LLM enhancement if available
+  const { isLLMAvailable, createLLMService } = await import('../core/llm-service.js');
+  
+  if (!isLLMAvailable()) {
+    return {
+      success: true,
+      method: 'local',
+      query,
+      enhancedQuery: query,
+      usedTerms: [],
+      suggestedConditions: [],
+      message: 'No matching terms found locally. Configure ANTHROPIC_API_KEY for AI-powered enhancement.',
+    };
+  }
+
+  try {
+    const terms = context.knowledge.getActiveTerms();
+    
+    if (terms.length === 0) {
+      return {
+        success: true,
+        method: 'local',
+        query,
+        enhancedQuery: query,
+        usedTerms: [],
+        suggestedConditions: [],
+        message: 'No terms in glossary. Add terms using add_term or generate_glossary.',
+      };
+    }
+
+    const llm = createLLMService();
+    const result = await llm.enhanceQueryWithGlossary(query, terms);
+
+    return {
+      success: true,
+      method: 'ai',
+      query,
+      enhancedQuery: result.enhancedQuery,
+      usedTerms: result.usedTerms,
+      suggestedConditions: result.suggestedConditions,
+      message: result.usedTerms.length > 0 
+        ? `Found ${result.usedTerms.length} matching term(s): ${result.usedTerms.join(', ')}`
+        : 'No matching terms found.',
+      tip: 'Apply suggestedConditions to your SQL WHERE clause.',
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      tip: 'Fallback to local term matching.',
+    };
+  }
+}
+
+/**
+ * Calculate term relevance score
+ */
+function calculateTermRelevance(query: string, term: { term: string; synonyms: string[] }): number {
+  const lowerQuery = query.toLowerCase();
+  const lowerTerm = term.term.toLowerCase();
+  
+  // Exact match = 1.0
+  if (lowerTerm === lowerQuery) return 1.0;
+  
+  // Term contains query = 0.8
+  if (lowerTerm.includes(lowerQuery)) return 0.8;
+  
+  // Query contains term = 0.7
+  if (lowerQuery.includes(lowerTerm)) return 0.7;
+  
+  // Synonym match
+  for (const syn of term.synonyms) {
+    if (syn.toLowerCase() === lowerQuery) return 0.9;
+    if (syn.toLowerCase().includes(lowerQuery)) return 0.6;
+  }
+  
+  return 0.5;
+}
+
 // ============================================================
 // Utility Functions
 // ============================================================

package/test-glossary.yaml

@@ -0,0 +1,55 @@
+version: 1.0.0
+exportedAt: "2025-12-31T19:42:09.637Z"
+terms:
+  -
+    term: 최근 주문
+    definition: 30일 이내에 발생한 주문
+    sql: order_date >= CURRENT_DATE - INTERVAL '30 days'
+    synonyms: ["recent orders", "30일 이내 주문", "30일내 주문", "최근 30일 주문"]
+    tables: ["orders"]
+    columns: ["order_date"]
+    category: time
+    examples: ["최근 주문 목록을 보여줘", "30일 이내 주문한 고객들", "recent orders analysis"]
+  -
+    term: VIP 고객
+    definition: 총 주문 건수가 10건 이상인 고객
+    sql: COUNT(order_id) >= 10
+    synonyms: ["VIP customer", "VIP customers", "우수 고객", "10건 이상 주문 고객"]
+    tables: ["customers", "orders"]
+    columns: ["customer_id"]
+    category: custom
+    examples: ["VIP 고객 리스트", "주문 10건 이상인 고객들", "VIP customers with high order volume"]
+  -
+    term: 신규 가입자
+    definition: 7일 이내에 가입한 사용자
+    sql: created_at >= DATE_SUB(CURRENT_DATE, INTERVAL 7 DAY)
+    synonyms: ["새로운 사용자", "신규 회원", "new users", "recent signups"]
+    tables: ["users"]
+    columns: ["created_at"]
+    category: filter
+    examples: ["신규 가입자 목록을 보여주세요", "지난 주에 가입한 신규 가입자는 몇 명인가요?", "신규 가입자들의 평균 나이는?", "Show me new users this week"]
+  -
+    term: 활성 사용자
+    definition: status가 1인 사용자
+    sql: status = 1
+    synonyms: ["active user", "활성화된 사용자"]
+    tables: ["users"]
+    category: status
+  -
+    term: 프리미엄 회원
+    definition: 월 구독료가 10,000원 이상인 회원
+    sql: subscription_fee >= 10000
+    synonyms: ["premium member", "premium user", "프리미엄 사용자", "유료 회원"]
+    tables: ["users", "subscriptions"]
+    columns: ["subscription_fee", "monthly_fee"]
+    category: filter
+    examples: ["프리미엄 회원들의 평균 사용량은?", "프리미엄 회원 중에서 활성 사용자는 몇 명인가요?", "이번 달 프리미엄 회원 가입자 수는?"]
+  -
+    term: 휴면 계정
+    definition: 마지막 로그인으로부터 90일 이상 지난 계정
+    sql: last_login_date < DATE_SUB(NOW(), INTERVAL 90 DAY)
+    synonyms: ["dormant account", "inactive user", "비활성 계정", "장기 미접속자"]
+    tables: ["users"]
+    columns: ["last_login_date", "last_access_date"]
+    category: status
+    examples: ["휴면 계정은 총 몇 개인가요?", "휴면 계정 중에서 VIP 고객은?", "휴면 계정을 활성화시키려면?"]