Asian Financial Filings MCP Server

Instructions

Implementation Reference

• src/index.js:28-198 (schema)

  Registration of ListToolsRequestHandler defining the schema for the 'asia-filings' tool, including all supported methods, parameters, and descriptions.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: 'asia-filings',
          description: 'Unified tool for Asian financial filings: access company filings, financial statements, and XBRL data from Japan (EDINET) and South Korea (DART). Provides comprehensive access to financial reports from 7,700+ Asian companies.',
          inputSchema: {
            type: 'object',
            properties: {
              method: {
                type: 'string',
                enum: [
                  // Japan EDINET methods
                  'search_japan_companies',
                  'get_japan_company_by_code',
                  'get_japan_company_filings',
                  'get_japan_filing_document',
                  'get_japan_documents_by_date',
                  'get_japan_filing_facts',
                  'get_japan_dimensional_facts',
                  // Korea DART methods
                  'search_korea_companies',
                  'get_korea_company_by_code',
                  'get_korea_company_filings',
                  'get_korea_financial_statements',
                  'get_korea_major_shareholders',
                  'get_korea_executive_info',
                  'get_korea_dividend_info',
                  'get_korea_dimensional_facts',
                  // Advanced Analysis Methods (Phase 2)
                  'build_fact_table',
                  'search_facts_by_value',
                  'time_series_analysis',
                  // Utility methods
                  'filter_filings'
                ],
                description: `The operation to perform:
  
  JAPAN (EDINET):
  - search_japan_companies: Search Japanese companies by name
  - get_japan_company_by_code: Get company by EDINET code
  - get_japan_company_filings: Get filing history for Japanese company
  - get_japan_filing_document: Download specific filing document
  - get_japan_documents_by_date: Get all filings for a specific date
  - get_japan_filing_facts: Extract XBRL facts from filing (J-GAAP)
  - get_japan_dimensional_facts: Get dimensional facts with breakdowns
  
  KOREA (DART):
  - search_korea_companies: Search Korean companies by name
  - get_korea_company_by_code: Get company by corporate code
  - get_korea_company_filings: Get filing history for Korean company
  - get_korea_financial_statements: Get financial statements (XBRL)
  - get_korea_major_shareholders: Get major shareholder information
  - get_korea_executive_info: Get executive/officer information
  - get_korea_dividend_info: Get dividend allocation information
  - get_korea_dimensional_facts: Get dimensional facts with breakdowns
  
  ADVANCED ANALYSIS (Phase 2):
  - build_fact_table: Build comprehensive fact table around target value with BI summaries
  - search_facts_by_value: Search for facts within value range (alias for build_fact_table)
  - time_series_analysis: Analyze financial metrics across multiple periods with growth rates
  
  UTILITIES:
  - filter_filings: Filter filing arrays by criteria`,
                examples: ['search_japan_companies', 'get_korea_financial_statements']
              },
              query: {
                type: 'string',
                description: 'For search methods: Company name to search (Japanese, Korean, or English)',
                examples: ['Toyota', 'Samsung', 'ソニー', '삼성전자']
              },
              edinet_code: {
                type: 'string',
                description: 'For Japan methods: EDINET code (E-number)',
                examples: ['E01225', 'E02166', 'E05080']
              },
              corp_code: {
                type: 'string',
                description: 'For Korea methods: Corporate code',
                examples: ['00126380', '00164742']
              },
              document_id: {
                type: 'string',
                description: 'For get_japan_filing_document: Document ID from EDINET',
                examples: ['S100XXXX']
              },
              document_type: {
                type: 'string',
                description: 'For get_japan_filing_document: Document type (1: submission, 2: PDF, 3: attachments, 4: XBRL)',
                examples: ['1', '2', '4']
              },
              date: {
                type: 'string',
                description: 'For get_japan_documents_by_date: Date in YYYY-MM-DD format',
                examples: ['2024-12-01', '2024-11-15']
              },
              start_date: {
                type: 'string',
                description: 'For filing methods: Start date in YYYY-MM-DD format',
                examples: ['2023-01-01', '2024-01-01']
              },
              end_date: {
                type: 'string',
                description: 'For filing methods: End date in YYYY-MM-DD format',
                examples: ['2024-12-31', '2024-06-30']
              },
              business_year: {
                type: 'string',
                description: 'For get_korea_financial_statements, get_korea_dividend_info: Business year (YYYY)',
                examples: ['2023', '2024']
              },
              report_code: {
                type: 'string',
                description: 'For get_korea_financial_statements: Report code (11011: Annual, 11013: Q1, 11012: Q2, 11014: Q3)',
                examples: ['11011', '11013']
              },
              report_type: {
                type: 'string',
                description: 'For get_korea_company_filings: Report type filter',
                examples: ['A', 'Q']
              },
              limit: {
                type: 'integer',
                description: 'Maximum number of results to return',
                examples: [10, 25, 50, 100]
              },
              filings: {
                type: 'array',
                description: 'For filter_filings: Array of filing objects to filter',
                items: { type: 'object' }
              },
              filters: {
                type: 'object',
                description: 'For filter_filings: Filter criteria (startDate, endDate, reportType)'
              },
              search_criteria: {
                type: 'object',
                description: 'For dimensional_facts methods: Search criteria (concept, valueRange, period, hasDimensions)'
              },
              country: {
                type: 'string',
                description: 'For advanced analysis methods: Country code (JP for Japan, KR for Korea)',
                examples: ['JP', 'KR']
              },
              company_id: {
                type: 'string',
                description: 'For advanced analysis methods: EDINET code (JP) or corp code (KR)',
                examples: ['E01225', '00126380']
              },
              target_value: {
                type: 'number',
                description: 'For build_fact_table/search_facts_by_value: Target value to search around',
                examples: [1000000000, 500000000000]
              },
              tolerance: {
                type: 'number',
                description: 'For build_fact_table/search_facts_by_value: Tolerance range (±)',
                examples: [50000000, 100000000]
              },
              options: {
                type: 'object',
                description: 'For advanced analysis methods: Analysis options (maxRows, showDimensions, sortBy, concept, periods, includeGeography, includeSegments, showGrowthRates)'
              }
            },
            required: ['method'],
            additionalProperties: false
          }
        }
      ]
    };
  });

• src/index.js:201-588 (handler)

  Main handler for CallTool requests to 'asia-filings', dispatching based on 'method' parameter to specific API implementations in imported modules.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    if (name !== 'asia-filings') {
      throw new Error(`Unknown tool: ${name}`);
    }
  
    try {
      const { method, ...params } = args;
  
      switch (method) {
        // ============= JAPAN EDINET METHODS =============
  
        case 'search_japan_companies': {
          const { query, limit, date } = params;
          if (!query) {
            throw new Error('query parameter is required for search_japan_companies');
          }
  
          const results = await edinetApi.searchCompanies(query, { limit, date });
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_japan_company_by_code': {
          const { edinet_code } = params;
          if (!edinet_code) {
            throw new Error('edinet_code parameter is required for get_japan_company_by_code');
          }
  
          const result = await edinetApi.getCompanyByEdinetCode(edinet_code);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(result, null, 2)
              }
            ]
          };
        }
  
        case 'get_japan_company_filings': {
          const { edinet_code, start_date, end_date, limit } = params;
          if (!edinet_code) {
            throw new Error('edinet_code parameter is required for get_japan_company_filings');
          }
  
          const results = await edinetApi.getCompanyFilings(edinet_code, {
            startDate: start_date,
            endDate: end_date,
            limit
          });
  
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_japan_filing_document': {
          const { document_id, document_type } = params;
          if (!document_id) {
            throw new Error('document_id parameter is required for get_japan_filing_document');
          }
  
          const result = await edinetApi.getFilingDocument(document_id, document_type || '1');
  
          // For binary data, return metadata only
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  document_id: result.document_id,
                  type: result.type,
                  content_type: result.content_type,
                  note: 'Document downloaded successfully. Binary data not displayed.'
                }, null, 2)
              }
            ]
          };
        }
  
        case 'get_japan_documents_by_date': {
          const { date } = params;
          if (!date) {
            throw new Error('date parameter is required for get_japan_documents_by_date');
          }
  
          const results = await edinetApi.getDocumentsByDate(date);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_japan_filing_facts': {
          const { document_id } = params;
          if (!document_id) {
            throw new Error('document_id parameter is required for get_japan_filing_facts');
          }
  
          const results = await edinetApi.getFilingFacts(document_id);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_japan_dimensional_facts': {
          const { document_id, search_criteria } = params;
          if (!document_id) {
            throw new Error('document_id parameter is required for get_japan_dimensional_facts');
          }
  
          const results = await edinetApi.getDimensionalFacts(document_id, search_criteria || {});
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        // ============= KOREA DART METHODS =============
  
        case 'search_korea_companies': {
          const { query, limit } = params;
          if (!query) {
            throw new Error('query parameter is required for search_korea_companies');
          }
  
          const results = await dartApi.searchCompanies(query, { limit });
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_korea_company_by_code': {
          const { corp_code } = params;
          if (!corp_code) {
            throw new Error('corp_code parameter is required for get_korea_company_by_code');
          }
  
          const result = await dartApi.getCompanyByCorpCode(corp_code);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(result, null, 2)
              }
            ]
          };
        }
  
        case 'get_korea_company_filings': {
          const { corp_code, start_date, end_date, report_type, limit } = params;
          if (!corp_code) {
            throw new Error('corp_code parameter is required for get_korea_company_filings');
          }
  
          const results = await dartApi.getCompanyFilings(corp_code, {
            startDate: start_date,
            endDate: end_date,
            reportType: report_type,
            limit
          });
  
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_korea_financial_statements': {
          const { corp_code, business_year, report_code } = params;
          if (!corp_code || !business_year) {
            throw new Error('corp_code and business_year parameters are required for get_korea_financial_statements');
          }
  
          const results = await dartApi.getFinancialStatements(corp_code, business_year, report_code);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_korea_major_shareholders': {
          const { corp_code } = params;
          if (!corp_code) {
            throw new Error('corp_code parameter is required for get_korea_major_shareholders');
          }
  
          const results = await dartApi.getMajorShareholders(corp_code);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_korea_executive_info': {
          const { corp_code } = params;
          if (!corp_code) {
            throw new Error('corp_code parameter is required for get_korea_executive_info');
          }
  
          const results = await dartApi.getExecutiveInfo(corp_code);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_korea_dividend_info': {
          const { corp_code, business_year } = params;
          if (!corp_code || !business_year) {
            throw new Error('corp_code and business_year parameters are required for get_korea_dividend_info');
          }
  
          const results = await dartApi.getDividendInfo(corp_code, business_year);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'get_korea_dimensional_facts': {
          const { corp_code, business_year, report_code, search_criteria } = params;
          if (!corp_code || !business_year) {
            throw new Error('corp_code and business_year parameters are required for get_korea_dimensional_facts');
          }
  
          const results = await dartApi.getDimensionalFacts(
            corp_code,
            business_year,
            report_code || '11011',
            search_criteria || {}
          );
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        // ============= ADVANCED ANALYSIS METHODS (Phase 2) =============
  
        case 'build_fact_table':
        case 'search_facts_by_value': {
          const { country, company_id, target_value, tolerance, document_id, options } = params;
  
          if (!country || !company_id || target_value === undefined) {
            throw new Error('country, company_id, and target_value parameters are required for build_fact_table/search_facts_by_value');
          }
  
          const results = await factTableBuilder.buildFactTable({
            country,
            companyId: company_id,
            targetValue: target_value,
            tolerance: tolerance || 50000000,
            documentId: document_id,
            options: options || {}
          });
  
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        case 'time_series_analysis': {
          const { country, company_id, options } = params;
  
          if (!country || !company_id) {
            throw new Error('country and company_id parameters are required for time_series_analysis');
          }
  
          const results = await timeSeriesAnalyzer.timeSeriesAnalysis({
            country,
            companyId: company_id,
            options: options || {}
          });
  
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(results, null, 2)
              }
            ]
          };
        }
  
        // ============= UTILITY METHODS =============
  
        case 'filter_filings': {
          const { filings, filters } = params;
          if (!filings || !Array.isArray(filings)) {
            throw new Error('filings array parameter is required for filter_filings');
          }
  
          const results = dartApi.filterFilings(filings, filters || {});
          const response = {
            originalCount: filings.length,
            filteredCount: results.length,
            filters: filters || {},
            filings: results,
            source: 'Asia Filings Filter'
          };
  
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(response, null, 2)
              }
            ]
          };
        }
  
        default:
          throw new Error(`Unknown method: ${method}`);
      }
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: errorMessage }, null, 2)
          }
        ],
        isError: true
      };
    }
  });

• src/edinet-api.js:1-367 (helper)

  Helper module implementing Japan EDINET API calls for company search, filings retrieval, document download, and XBRL fact extraction/parsing.

  import axios from 'axios';
  import * as xbrlParser from './xbrl-parser.js';
  
  const EDINET_API_BASE = 'https://disclosure.edinet-fsa.go.jp/api/v2';
  
  // API key should be set via environment variable or passed to functions
  const EDINET_API_KEY = process.env.EDINET_API_KEY || '';
  
  /**
   * Search for Japanese companies by name
   * @param {string} query - Company name to search (Japanese or English)
   * @param {Object} options - Search options
   * @returns {Promise<Object>} Search results
   */
  export async function searchCompanies(query, options = {}) {
    const { limit = 10, date } = options;
  
    try {
      // Get recent filings and search within them for company name
      const searchDate = date || new Date().toISOString().split('T')[0];
  
      const response = await axios.get(`${EDINET_API_BASE}/documents.json`, {
        params: {
          date: searchDate.replace(/-/g, ''),
          type: 2, // Type 2: Metadata only
        },
        headers: {
          'Subscription-Key': EDINET_API_KEY
        },
        timeout: 15000
      });
  
      if (!response.data || !response.data.results) {
        return {
          query,
          companies: [],
          total_found: 0,
          country: 'JP',
          source: 'EDINET API',
          note: 'No results found for the specified date'
        };
      }
  
      // Filter results by company name
      const queryLower = query.toLowerCase();
      const matchingCompanies = response.data.results
        .filter(doc => {
          const name = (doc.filerName || '').toLowerCase();
          return name.includes(queryLower);
        })
        .slice(0, limit)
        .map(doc => ({
          name: doc.filerName,
          edinet_code: doc.edinetCode,
          sec_code: doc.secCode || null,
          jcn: doc.JCN || null,
          recent_filing: {
            document_id: doc.docID,
            document_type: doc.docTypeCode,
            document_description: doc.docDescription,
            period_start: doc.periodStart,
            period_end: doc.periodEnd,
            submit_date: doc.submitDateTime
          }
        }));
  
      return {
        query,
        companies: matchingCompanies,
        total_found: matchingCompanies.length,
        country: 'JP',
        source: 'EDINET API',
        date_searched: searchDate
      };
  
    } catch (error) {
      if (error.response?.status === 401) {
        throw new Error('EDINET API key is required. Please set EDINET_API_KEY environment variable.');
      }
      throw new Error(`EDINET company search failed: ${error.message}`);
    }
  }
  
  /**
   * Get company information by EDINET code
   * @param {string} edinetCode - EDINET code (E-number)
   * @returns {Promise<Object>} Company information
   */
  export async function getCompanyByEdinetCode(edinetCode) {
    try {
      // Get recent filings for this company
      const today = new Date();
      const startDate = new Date(today.getFullYear() - 1, today.getMonth(), today.getDate());
  
      const filings = await getCompanyFilings(edinetCode, {
        startDate: startDate.toISOString().split('T')[0],
        endDate: today.toISOString().split('T')[0],
        limit: 1
      });
  
      if (!filings.filings || filings.filings.length === 0) {
        throw new Error(`No filings found for EDINET code: ${edinetCode}`);
      }
  
      const latestFiling = filings.filings[0];
  
      return {
        edinet_code: edinetCode,
        name: latestFiling.filer_name,
        sec_code: latestFiling.sec_code,
        jcn: latestFiling.jcn,
        latest_filing: {
          document_id: latestFiling.document_id,
          submit_date: latestFiling.submit_date,
          document_type: latestFiling.document_type
        },
        country: 'JP',
        source: 'EDINET API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get company by EDINET code: ${error.message}`);
    }
  }
  
  /**
   * Get company filings by EDINET code
   * @param {string} edinetCode - EDINET code
   * @param {Object} options - Options (startDate, endDate, limit)
   * @returns {Promise<Object>} Filings list
   */
  export async function getCompanyFilings(edinetCode, options = {}) {
    const { startDate, endDate, limit = 100 } = options;
  
    try {
      const start = startDate ? new Date(startDate) : new Date(Date.now() - 365 * 24 * 60 * 60 * 1000);
      const end = endDate ? new Date(endDate) : new Date();
  
      const allFilings = [];
  
      // Iterate through dates to find filings for this company
      const currentDate = new Date(start);
  
      while (currentDate <= end && allFilings.length < limit) {
        const dateStr = currentDate.toISOString().split('T')[0].replace(/-/g, '');
  
        try {
          const response = await axios.get(`${EDINET_API_BASE}/documents.json`, {
            params: {
              date: dateStr,
              type: 2
            },
            headers: {
              'Subscription-Key': EDINET_API_KEY
            },
            timeout: 15000
          });
  
          if (response.data?.results) {
            const companyFilings = response.data.results
              .filter(doc => doc.edinetCode === edinetCode)
              .map(doc => ({
                document_id: doc.docID,
                edinet_code: doc.edinetCode,
                sec_code: doc.secCode,
                jcn: doc.JCN,
                filer_name: doc.filerName,
                document_type: doc.docTypeCode,
                document_description: doc.docDescription,
                period_start: doc.periodStart,
                period_end: doc.periodEnd,
                submit_date: doc.submitDateTime,
                xbrl_flag: doc.xbrlFlag === '1',
                pdf_flag: doc.pdfFlag === '1',
                urls: {
                  document: `${EDINET_API_BASE}/documents/${doc.docID}`,
                  viewer: `https://disclosure.edinet-fsa.go.jp/EKW0EZ0001.html?docID=${doc.docID}`
                }
              }));
  
            allFilings.push(...companyFilings);
          }
        } catch (error) {
          // Skip dates with errors
        }
  
        // Move to next date
        currentDate.setDate(currentDate.getDate() + 1);
  
        // Rate limiting
        await new Promise(resolve => setTimeout(resolve, 200));
      }
  
      return {
        edinet_code: edinetCode,
        filings: allFilings.slice(0, limit),
        total_found: allFilings.length,
        date_range: {
          start: start.toISOString().split('T')[0],
          end: end.toISOString().split('T')[0]
        },
        source: 'EDINET API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get company filings: ${error.message}`);
    }
  }
  
  /**
   * Get filing document (download)
   * @param {string} docId - Document ID
   * @param {string} type - Document type (1: submission, 2: PDF, 3: attachments, 4: XBRL)
   * @returns {Promise<Object>} Document data
   */
  export async function getFilingDocument(docId, type = '1') {
    try {
      const response = await axios.get(`${EDINET_API_BASE}/documents/${docId}`, {
        params: { type },
        headers: {
          'Subscription-Key': EDINET_API_KEY
        },
        responseType: type === '4' ? 'arraybuffer' : 'stream',
        timeout: 30000
      });
  
      return {
        document_id: docId,
        type: type === '1' ? 'submission' : type === '2' ? 'pdf' : type === '3' ? 'attachments' : 'xbrl',
        data: response.data,
        content_type: response.headers['content-type']
      };
  
    } catch (error) {
      throw new Error(`Failed to download document: ${error.message}`);
    }
  }
  
  /**
   * Get documents list for a specific date
   * @param {string} date - Date in YYYY-MM-DD format
   * @returns {Promise<Object>} Documents list
   */
  export async function getDocumentsByDate(date) {
    try {
      const dateStr = date.replace(/-/g, '');
  
      const response = await axios.get(`${EDINET_API_BASE}/documents.json`, {
        params: {
          date: dateStr,
          type: 2
        },
        headers: {
          'Subscription-Key': EDINET_API_KEY
        },
        timeout: 15000
      });
  
      if (!response.data || !response.data.results) {
        return {
          date,
          documents: [],
          total_count: 0,
          source: 'EDINET API'
        };
      }
  
      return {
        date,
        documents: response.data.results.map(doc => ({
          document_id: doc.docID,
          edinet_code: doc.edinetCode,
          sec_code: doc.secCode,
          filer_name: doc.filerName,
          document_type: doc.docTypeCode,
          document_description: doc.docDescription,
          period_start: doc.periodStart,
          period_end: doc.periodEnd,
          submit_date: doc.submitDateTime,
          xbrl_flag: doc.xbrlFlag === '1'
        })),
        total_count: response.data.metadata?.resultset?.count || response.data.results.length,
        source: 'EDINET API'
      };
  
    } catch (error) {
      if (error.response?.status === 401) {
        throw new Error('EDINET API key is required. Please set EDINET_API_KEY environment variable.');
      }
      throw new Error(`Failed to get documents by date: ${error.message}`);
    }
  }
  
  /**
   * Get and parse XBRL facts from a filing
   * @param {string} docId - Document ID
   * @returns {Promise<Object>} Parsed XBRL facts
   */
  export async function getFilingFacts(docId) {
    try {
      // Download XBRL document (type 4)
      const response = await axios.get(`${EDINET_API_BASE}/documents/${docId}`, {
        params: { type: '4' },
        headers: {
          'Subscription-Key': EDINET_API_KEY
        },
        responseType: 'text',
        timeout: 30000
      });
  
      // Parse iXBRL HTML
      const parsed = xbrlParser.parseIXBRL(response.data);
  
      return {
        document_id: docId,
        ...parsed,
        summary: xbrlParser.buildSummary(parsed.facts)
      };
  
    } catch (error) {
      throw new Error(`Failed to get filing facts: ${error.message}`);
    }
  }
  
  /**
   * Get dimensional facts from a filing
   * @param {string} docId - Document ID
   * @param {Object} searchCriteria - Search criteria
   * @returns {Promise<Object>} Dimensional facts
   */
  export async function getDimensionalFacts(docId, searchCriteria = {}) {
    try {
      const { facts, ...metadata } = await getFilingFacts(docId);
  
      // Filter facts based on criteria
      let filteredFacts = facts;
      if (Object.keys(searchCriteria).length > 0) {
        filteredFacts = xbrlParser.filterFacts(facts, searchCriteria);
      }
  
      // Extract dimensional breakdowns
      const dimensions = xbrlParser.extractDimensions(filteredFacts);
  
      return {
        document_id: docId,
        search_criteria: searchCriteria,
        facts: filteredFacts,
        total_found: filteredFacts.length,
        dimensions,
        ...metadata
      };
  
    } catch (error) {
      throw new Error(`Failed to get dimensional facts: ${error.message}`);
    }
  }
  
  export default {
    searchCompanies,
    getCompanyByEdinetCode,
    getCompanyFilings,
    getFilingDocument,
    getDocumentsByDate,
    getFilingFacts,
    getDimensionalFacts
  };

• src/dart-api.js:1-398 (helper)

  Helper module implementing South Korea DART API calls for company search, filings, financial statements, shareholder/executive info, and XBRL facts.

  import axios from 'axios';
  import * as xbrlParser from './xbrl-parser.js';
  
  const DART_API_BASE = 'https://opendart.fss.or.kr/api';
  
  // API key should be set via environment variable
  const DART_API_KEY = process.env.DART_API_KEY || '';
  
  /**
   * Search Korean companies by name
   * @param {string} query - Company name to search
   * @param {Object} options - Search options
   * @returns {Promise<Object>} Search results
   */
  export async function searchCompanies(query, options = {}) {
    const { limit = 10 } = options;
  
    try {
      // Get company list (corp_code.xml contains all companies)
      // For now, we'll search through recent disclosures
      const response = await axios.get(`${DART_API_BASE}/list.json`, {
        params: {
          crtfc_key: DART_API_KEY,
          corp_name: query,
          bgn_de: new Date(Date.now() - 365 * 24 * 60 * 60 * 1000).toISOString().split('T')[0].replace(/-/g, ''),
          end_de: new Date().toISOString().split('T')[0].replace(/-/g, ''),
          page_count: limit
        },
        timeout: 15000
      });
  
      if (response.data.status !== '000') {
        throw new Error(`DART API error: ${response.data.message}`);
      }
  
      const companies = [];
      const seenCodes = new Set();
  
      if (response.data.list) {
        for (const item of response.data.list) {
          if (!seenCodes.has(item.corp_code)) {
            seenCodes.add(item.corp_code);
            companies.push({
              name: item.corp_name,
              corp_code: item.corp_code,
              stock_code: item.stock_code || null,
              recent_filing: {
                report_name: item.report_nm,
                receipt_number: item.rcept_no,
                report_date: item.rcept_dt,
                remarks: item.rm
              }
            });
  
            if (companies.length >= limit) break;
          }
        }
      }
  
      return {
        query,
        companies,
        total_found: companies.length,
        country: 'KR',
        source: 'DART Open API'
      };
  
    } catch (error) {
      if (error.response?.data?.status === '020') {
        throw new Error('DART API key is required or invalid. Please set DART_API_KEY environment variable.');
      }
      throw new Error(`DART company search failed: ${error.message}`);
    }
  }
  
  /**
   * Get company information by corporate code
   * @param {string} corpCode - Corporate code
   * @returns {Promise<Object>} Company information
   */
  export async function getCompanyByCorpCode(corpCode) {
    try {
      const response = await axios.get(`${DART_API_BASE}/company.json`, {
        params: {
          crtfc_key: DART_API_KEY,
          corp_code: corpCode
        },
        timeout: 15000
      });
  
      if (response.data.status !== '000') {
        throw new Error(`DART API error: ${response.data.message}`);
      }
  
      return {
        corp_code: corpCode,
        name: response.data.corp_name,
        name_eng: response.data.corp_name_eng,
        stock_code: response.data.stock_code,
        ceo_name: response.data.ceo_nm,
        corporation_number: response.data.corp_cls,
        legal_form: response.data.corp_cls,
        business_registration_number: response.data.bizr_no,
        address: response.data.adres,
        homepage: response.data.hm_url,
        phone: response.data.phn_no,
        establishment_date: response.data.est_dt,
        accounting_month: response.data.acc_mt,
        country: 'KR',
        source: 'DART Open API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get company by corp code: ${error.message}`);
    }
  }
  
  /**
   * Get company filings/disclosures
   * @param {string} corpCode - Corporate code
   * @param {Object} options - Options (startDate, endDate, reportType, limit)
   * @returns {Promise<Object>} Filings list
   */
  export async function getCompanyFilings(corpCode, options = {}) {
    const {
      startDate,
      endDate,
      reportType = '', // A: Annual, Q: Quarterly, etc.
      limit = 100
    } = options;
  
    try {
      const start = startDate ? startDate.replace(/-/g, '') : new Date(Date.now() - 365 * 24 * 60 * 60 * 1000).toISOString().split('T')[0].replace(/-/g, '');
      const end = endDate ? endDate.replace(/-/g, '') : new Date().toISOString().split('T')[0].replace(/-/g, '');
  
      const response = await axios.get(`${DART_API_BASE}/list.json`, {
        params: {
          crtfc_key: DART_API_KEY,
          corp_code: corpCode,
          bgn_de: start,
          end_de: end,
          pblntf_ty: reportType,
          page_count: limit
        },
        timeout: 15000
      });
  
      if (response.data.status !== '000') {
        throw new Error(`DART API error: ${response.data.message}`);
      }
  
      const filings = (response.data.list || []).map(item => ({
        corp_code: item.corp_code,
        corp_name: item.corp_name,
        stock_code: item.stock_code,
        report_name: item.report_nm,
        receipt_number: item.rcept_no,
        filing_date: item.flr_nm,
        report_date: item.rcept_dt,
        remarks: item.rm,
        urls: {
          viewer: `https://dart.fss.or.kr/dsaf001/main.do?rcpNo=${item.rcept_no}`,
          document: `${DART_API_BASE}/document.xml?crtfc_key=${DART_API_KEY}&rcept_no=${item.rcept_no}`
        }
      }));
  
      return {
        corp_code: corpCode,
        filings,
        total_found: filings.length,
        date_range: {
          start: startDate || start,
          end: endDate || end
        },
        source: 'DART Open API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get company filings: ${error.message}`);
    }
  }
  
  /**
   * Get financial statements for a company
   * @param {string} corpCode - Corporate code
   * @param {string} businessYear - Business year (YYYY)
   * @param {string} reportCode - Report code (11013: Q1, 11012: Q2, 11014: Q3, 11011: Annual)
   * @returns {Promise<Object>} Financial statements
   */
  export async function getFinancialStatements(corpCode, businessYear, reportCode = '11011') {
    try {
      // Get consolidated financial statements
      const response = await axios.get(`${DART_API_BASE}/fnlttSinglAcntAll.json`, {
        params: {
          crtfc_key: DART_API_KEY,
          corp_code: corpCode,
          bsns_year: businessYear,
          reprt_code: reportCode
        },
        timeout: 15000
      });
  
      if (response.data.status !== '000') {
        throw new Error(`DART API error: ${response.data.message}`);
      }
  
      // Parse XBRL data
      const parsed = xbrlParser.parseXBRLJSON(response.data);
  
      return {
        corp_code: corpCode,
        business_year: businessYear,
        report_code: reportCode,
        report_type: reportCode === '11011' ? 'Annual' : reportCode === '11013' ? 'Q1' : reportCode === '11012' ? 'Q2' : 'Q3',
        statements: response.data.list || [],
        ...parsed,
        summary: xbrlParser.buildSummary(parsed.facts),
        source: 'DART Open API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get financial statements: ${error.message}`);
    }
  }
  
  /**
   * Get dimensional facts from financial statements
   * @param {string} corpCode - Corporate code
   * @param {string} businessYear - Business year (YYYY)
   * @param {string} reportCode - Report code
   * @param {Object} searchCriteria - Search criteria
   * @returns {Promise<Object>} Dimensional facts
   */
  export async function getDimensionalFacts(corpCode, businessYear, reportCode, searchCriteria = {}) {
    try {
      const { facts, ...metadata } = await getFinancialStatements(corpCode, businessYear, reportCode);
  
      // Filter facts based on criteria
      let filteredFacts = facts;
      if (Object.keys(searchCriteria).length > 0) {
        filteredFacts = xbrlParser.filterFacts(facts, searchCriteria);
      }
  
      // Extract dimensional breakdowns
      const dimensions = xbrlParser.extractDimensions(filteredFacts);
  
      return {
        corp_code: corpCode,
        business_year: businessYear,
        report_code: reportCode,
        search_criteria: searchCriteria,
        facts: filteredFacts,
        total_found: filteredFacts.length,
        dimensions,
        ...metadata
      };
  
    } catch (error) {
      throw new Error(`Failed to get dimensional facts: ${error.message}`);
    }
  }
  
  /**
   * Get major shareholder information
   * @param {string} corpCode - Corporate code
   * @returns {Promise<Object>} Major shareholder data
   */
  export async function getMajorShareholders(corpCode) {
    try {
      const response = await axios.get(`${DART_API_BASE}/majorstock.json`, {
        params: {
          crtfc_key: DART_API_KEY,
          corp_code: corpCode
        },
        timeout: 15000
      });
  
      if (response.data.status !== '000') {
        throw new Error(`DART API error: ${response.data.message}`);
      }
  
      return {
        corp_code: corpCode,
        shareholders: (response.data.list || []).map(item => ({
          report_date: item.rcept_dt,
          shareholder_name: item.nm,
          relation: item.relate,
          shares_owned: item.stock_knd,
          ownership_percent: item.hold_stock_ratio,
          change_reason: item.change_cause
        })),
        source: 'DART Open API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get major shareholders: ${error.message}`);
    }
  }
  
  /**
   * Get company executive information
   * @param {string} corpCode - Corporate code
   * @returns {Promise<Object>} Executive information
   */
  export async function getExecutiveInfo(corpCode) {
    try {
      const response = await axios.get(`${DART_API_BASE}/exctvSttus.json`, {
        params: {
          crtfc_key: DART_API_KEY,
          corp_code: corpCode
        },
        timeout: 15000
      });
  
      if (response.data.status !== '000') {
        throw new Error(`DART API error: ${response.data.message}`);
      }
  
      return {
        corp_code: corpCode,
        executives: (response.data.list || []).map(item => ({
          name: item.nm,
          position: item.sexdstn,
          registration_date: item.rcept_dt,
          birth_year: item.birth_ym,
          career: item.career
        })),
        source: 'DART Open API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get executive information: ${error.message}`);
    }
  }
  
  /**
   * Get dividend information
   * @param {string} corpCode - Corporate code
   * @param {string} businessYear - Business year (YYYY)
   * @returns {Promise<Object>} Dividend information
   */
  export async function getDividendInfo(corpCode, businessYear) {
    try {
      const response = await axios.get(`${DART_API_BASE}/alotMatter.json`, {
        params: {
          crtfc_key: DART_API_KEY,
          corp_code: corpCode,
          bsns_year: businessYear
        },
        timeout: 15000
      });
  
      if (response.data.status !== '000') {
        throw new Error(`DART API error: ${response.data.message}`);
      }
  
      return {
        corp_code: corpCode,
        business_year: businessYear,
        dividends: response.data.list || [],
        source: 'DART Open API'
      };
  
    } catch (error) {
      throw new Error(`Failed to get dividend information: ${error.message}`);
    }
  }
  
  /**
   * Filter filings by criteria
   * @param {Array} filings - Array of filings
   * @param {Object} filters - Filter criteria
   * @returns {Array} Filtered filings
   */
  export function filterFilings(filings, filters = {}) {
    const { startDate, endDate, reportType, hasXbrl } = filters;
  
    return filings.filter(filing => {
      if (startDate && filing.report_date < startDate.replace(/-/g, '')) return false;
      if (endDate && filing.report_date > endDate.replace(/-/g, '')) return false;
      if (reportType && !filing.report_name.includes(reportType)) return false;
      // Note: hasXbrl filter would require additional metadata
      return true;
    });
  }
  
  export default {
    searchCompanies,
    getCompanyByCorpCode,
    getCompanyFilings,
    getFinancialStatements,
    getMajorShareholders,
    getExecutiveInfo,
    getDividendInfo,
    filterFilings,
    getDimensionalFacts
  };

• src/fact-table-builder.js:20-184 (helper)

  Advanced helper for building fact tables around target values with BI summaries, supporting both JP and KR filings with dimensional breakdowns.

  export async function buildFactTable(params) {
    const {
      country,
      companyId,
      targetValue,
      tolerance = 50000000,
      documentId = null,
      options = {}
    } = params;
  
    const defaultOptions = {
      maxRows: 25,
      showDimensions: true,
      sortBy: 'deviation', // 'deviation', 'value', 'concept'
      filters: {}
    };
  
    const tableOptions = { ...defaultOptions, ...options };
  
    try {
      let xbrlData;
      let filingInfo = {};
      let currencySymbol = country === 'JP' ? '¥' : '₩';
  
      // 1. Get XBRL data based on country
      if (country === 'JP') {
        // Japan - EDINET
        let targetDocId = documentId;
  
        if (!targetDocId) {
          // Get recent filing to find document ID
          const filings = await edinetApi.getCompanyFilings(companyId, { limit: 1 });
          if (!filings.filings || filings.filings.length === 0) {
            throw new Error('No filings found for company');
          }
          targetDocId = filings.filings[0].document_id;
          filingInfo = filings.filings[0];
        }
  
        xbrlData = await edinetApi.getFilingFacts(targetDocId);
        filingInfo.document_id = targetDocId;
  
      } else if (country === 'KR') {
        // Korea - DART
        if (!documentId) {
          throw new Error('business_year and report_code are required for Korean filings');
        }
  
        // documentId should be formatted as "businessYear:reportCode"
        const [businessYear, reportCode] = documentId.split(':');
        xbrlData = await dartApi.getFinancialStatements(companyId, businessYear, reportCode || '11011');
        filingInfo.business_year = businessYear;
        filingInfo.report_code = reportCode;
  
      } else {
        throw new Error('Unsupported country. Use JP for Japan or KR for Korea');
      }
  
      // 2. Find facts in value range
      const searchCriteria = {
        valueRange: {
          min: targetValue - tolerance,
          max: targetValue + tolerance
        },
        hasValue: true,
        ...tableOptions.filters
      };
  
      const matchingFacts = xbrlParser.filterFacts(xbrlData.facts, searchCriteria);
  
      if (matchingFacts.length === 0) {
        return {
          country,
          company: companyId,
          filing_info: filingInfo,
          targetValue,
          tolerance,
          searchRange: {
            min: targetValue - tolerance,
            max: targetValue + tolerance,
            minFormatted: formatCurrency(targetValue - tolerance, currencySymbol),
            maxFormatted: formatCurrency(targetValue + tolerance, currencySymbol)
          },
          table: [],
          summary: {
            totalFacts: 0,
            message: 'No facts found in the specified value range'
          }
        };
      }
  
      // 3. Enrich facts with business intelligence
      const enrichedFacts = matchingFacts.map((fact, index) => {
        const deviation = fact.value - targetValue;
        const exactMatch = Math.abs(deviation) < 1000;
  
        return {
          rowNumber: index + 1,
          concept: fact.concept,
          accountName: fact.accountName || null, // Korean-specific
          namespace: fact.namespace || 'unknown',
          value: fact.value,
          valueFormatted: formatCurrency(fact.value, currencySymbol),
          exactMatch,
          deviationFromTarget: deviation,
          deviationFormatted: `${deviation >= 0 ? '+' : ''}${formatCurrency(deviation, currencySymbol)}`,
          deviationPercent: targetValue !== 0 ? ((deviation / targetValue) * 100).toFixed(2) + '%' : 'N/A',
  
          periodType: fact.period?.instant ? 'instant' : 'duration',
          periodStart: fact.period?.startDate,
          periodEnd: fact.period?.endDate || fact.period?.instant,
  
          dimensions: fact.dimensions || {},
          dimensionCount: Object.keys(fact.dimensions || {}).length,
  
          geography: extractGeographyFromDimensions(fact.dimensions),
          segment: extractSegmentFromDimensions(fact.dimensions),
          product: extractProductFromDimensions(fact.dimensions),
  
          hasGeographicDimension: hasGeographyDimension(fact.dimensions),
          hasSegmentDimension: hasSegmentDimension(fact.dimensions),
          hasProductDimension: hasProductDimension(fact.dimensions),
  
          businessClassification: xbrlParser.classifyFact(fact.concept, country === 'JP' ? 'J-GAAP' : 'K-GAAP'),
  
          contextRef: fact.contextRef,
          unitRef: fact.unitRef || fact.unit,
          decimals: fact.decimals,
          scale: fact.scale
        };
      });
  
      // 4. Sort based on options
      sortFacts(enrichedFacts, tableOptions.sortBy);
  
      // 5. Limit results
      const limitedFacts = enrichedFacts.slice(0, tableOptions.maxRows);
  
      // 6. Generate business intelligence summary
      const summary = generateFactTableSummary(enrichedFacts, targetValue, tolerance, currencySymbol);
  
      return {
        country,
        company: companyId,
        filing_info: filingInfo,
        targetValue,
        tolerance,
        searchRange: {
          min: targetValue - tolerance,
          max: targetValue + tolerance,
          minFormatted: formatCurrency(targetValue - tolerance, currencySymbol),
          maxFormatted: formatCurrency(targetValue + tolerance, currencySymbol)
        },
        table: limitedFacts,
        summary,
        totalFactsFound: enrichedFacts.length,
        totalFactsReturned: limitedFacts.length,
        source: country === 'JP' ? 'EDINET J-GAAP Analysis' : 'DART K-GAAP Analysis',
        taxonomy: country === 'JP' ? 'J-GAAP' : 'K-GAAP/IFRS'
      };
  
    } catch (error) {
      throw new Error(`Failed to build fact table: ${error.message}`);
    }
  }