describe_semantic_entity

Instructions

Implementation Reference

• adapters/mcp/server-stdio.js:995-1004 (handler)

  The handler for the describe_semantic_entity tool. It loads the semanticLayer private module, calls describeSemanticSchema(), looks up the entity/metric by args.type, and returns the definition.

  case 'describe_semantic_entity': {
    const module = loadPrivateMcpModule('semanticLayer');
    if (!module) return unavailablePrivateMcpFeature('describe_semantic_entity');
    const schema = module.describeSemanticSchema();
    const entity = schema.entities[args.type] || schema.metrics[args.type];
    if (!entity) {
      throw new Error(`Unknown semantic entity: ${args.type}`);
    }
    return toTextResult(entity);
  }

• scripts/semantic-layer.js:90-97 (helper)

  Returns the SemanticSchema object containing all entity and metric definitions used by the handler.

  function describeSemanticSchema() {
    return SemanticSchema;
  }
  
  module.exports = {
    getBusinessMetrics,
    describeSemanticSchema,
    SemanticSchema,

• scripts/semantic-layer.js:14-79 (schema)

  The SemanticSchema defining entities (Customer, Revenue, Funnel, DataPipeline) and metrics (ConversionRate, BookedRevenue, etc.) queried by describe_semantic_entity.

  const SemanticSchema = {
    entities: {
      Customer: {
        description: 'An individual or organization using the gateway.',
        states: ['active', 'disabled'],
        tiers: ['free', 'pro', 'enterprise-sprint'],
      },
      Revenue: {
        description: 'Financial value captured by the system.',
        types: ['booked', 'reconciled', 'projected'],
      },
      Funnel: {
        description: 'The journey from anonymous visitor to paid customer.',
        stages: ['visitor', 'checkout_start', 'acquisition', 'paid'],
      },
      DataPipeline: {
        description: 'The staged analytics pipeline that materializes raw, staging, semantic, and lineage artifacts.',
        stages: ['raw', 'staging', 'semantic', 'lineage'],
      },
    },
    metrics: {
      ConversionRate: {
        description: 'The percentage of unique visitors who become paid customers.',
        calculation: 'paid_customers / unique_visitors',
      },
      BookedRevenue: {
        description: 'Total revenue documented in the system (Stripe + GitHub + Manual).',
        unit: 'cents',
      },
      ActiveProUsers: {
        description: 'Count of unique customers with at least one active Pro API key.',
      },
      AttributionCoverageRate: {
        description: 'The share of tracked web page views carrying attribution metadata.',
        unit: 'ratio',
      },
      UnreconciledPaidEvents: {
        description: 'Count of paid events still waiting for billing reconciliation.',
        unit: 'count',
      },
      PipelineWarnings: {
        description: 'Warning count emitted by the staged analytics reconciliation checks.',
        unit: 'count',
      },
      PredictedBookedRevenue: {
        description: 'Model-assisted projection of likely booked revenue from current funnel and attribution signals.',
        unit: 'cents',
      },
      IncrementalRevenueOpportunity: {
        description: 'Forecasted revenue left on the table relative to currently booked revenue.',
        unit: 'cents',
      },
      ProUpgradeScore: {
        description: '0-1 propensity score that free/local activity is ripe for Pro conversion.',
        unit: 'ratio',
      },
      TeamUpgradeScore: {
        description: '0-1 propensity score that current activity is ripe for Team rollout and expansion.',
        unit: 'ratio',
      },
      PredictiveAnomalyCount: {
        description: 'Count of predictive analytics anomalies requiring operator attention.',
        unit: 'count',
      },
    },
  };

• adapters/mcp/server-stdio.js:160-174 (registration)

  Registration of semanticLayer as a private MCP module, mapping the key to the module path.

  const PRO_CHECKOUT_URL = 'https://thumbgate-production.up.railway.app/checkout/pro';
  const PRIVATE_MCP_MODULES = Object.freeze({
    intentRouter: path.resolve(__dirname, '../../scripts/intent-router.js'),
    delegationRuntime: path.resolve(__dirname, '../../scripts/delegation-runtime.js'),
    orgDashboard: path.resolve(__dirname, '../../scripts/org-dashboard.js'),
    reflectorAgent: path.resolve(__dirname, '../../scripts/reflector-agent.js'),
    swarmCoordinator: path.resolve(__dirname, '../../scripts/swarm-coordinator.js'),
    sessionReport: path.resolve(__dirname, '../../scripts/session-report.js'),
    operatorArtifacts: path.resolve(__dirname, '../../scripts/operator-artifacts.js'),
    managedLessonAgent: path.resolve(__dirname, '../../scripts/managed-lesson-agent.js'),
    semanticLayer: path.resolve(__dirname, '../../scripts/semantic-layer.js'),
    lessonInference: path.resolve(__dirname, '../../scripts/lesson-inference.js'),
    lessonSearch: path.resolve(__dirname, '../../scripts/lesson-search.js'),
  });

• adapters/mcp/server-stdio.js:565-566 (helper)

  Alias: describe_reliability_entity is mapped to describe_semantic_entity.

  if (name === 'describe_reliability_entity') name = 'describe_semantic_entity';