Semantic Index Status

Instructions

Implementation Reference

• src/semantic/tools.ts:218-234 (registration)

  Registration of the 'semantic_status' tool with the MCP server. Defines title, description, inputSchema (empty), and annotations (readOnlyHint: true).

  server.registerTool(
    "semantic_status",
    {
      title: "Semantic Index Status",
      description: "Show the current state of the semantic vector index -- total entries, breakdown by source.",
      inputSchema: {},
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    },
    async () => {
      try {
        const status = await service.status();
        return ok(status);
      } catch (e) {
        return toolError("check semantic status", e);
      }
    },
  );

• src/semantic/tools.ts:226-234 (handler)

  Handler function for 'semantic_status' that calls service.status() and returns the result. On error, returns a tool error via toolError().

    async () => {
      try {
        const status = await service.status();
        return ok(status);
      } catch (e) {
        return toolError("check semantic status", e);
      }
    },
  );

• src/semantic/tools.ts:220-225 (schema)

  Input/output schema for 'semantic_status': title='Semantic Index Status', description, empty inputSchema, and readOnly annotations.

  {
    title: "Semantic Index Status",
    description: "Show the current state of the semantic vector index -- total entries, breakdown by source.",
    inputSchema: {},
    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
  },

• src/semantic/service.ts:319-332 (helper)

  SemanticSearchService.status() method: returns embeddingAvailable, provider, total, bySource, indexedAt, and stale. Delegates to VectorStore.getStats() for store statistics.

  /** Get status of the vector store and embedding provider. */
  async status(): Promise<{
    embeddingAvailable: boolean;
    provider: string;
    total: number;
    bySource: Record<string, number>;
    indexedAt: string | null;
    stale: boolean;
  }> {
    const available = await this.isEmbeddingAvailable();
    const provider = await this.getProvider();
    const stats = await this.store.getStats();
    return { embeddingAvailable: available, provider, ...stats };
  }

• src/semantic/store.ts:133-147 (helper)

  VectorStore.getStats() method: loads the store, computes total count and breakdown by source, checks staleness, and returns the aggregated status data.

  /** Get store stats. */
  async getStats(): Promise<{
    total: number;
    bySource: Record<string, number>;
    indexedAt: string | null;
    stale: boolean;
  }> {
    const store = await this.load();
    const bySource: Record<string, number> = {};
    for (const entry of Object.values(store.entries)) {
      bySource[entry.source] = (bySource[entry.source] || 0) + 1;
    }
    const stale = await this.isIndexStale();
    return { total: Object.keys(store.entries).length, bySource, indexedAt: store.indexedAt ?? null, stale };
  }