extract_entities

Instructions

Implementation Reference

• src/tools/extract-entities.ts:36-94 (handler)

  Main handler function for extract_entities: fetches URL (or uses provided text), parses body text and JSON-LD, extracts entities from both sources, merges them, computes citation density score, and generates findings about entity coverage.

  export async function extractEntities(
    input: ExtractEntitiesInput,
    hostDelays?: HostDelayMap,
    robotsCache?: Map<string, string>
  ): Promise<ExtractEntitiesResult> {
    const findings: Finding[] = [];
    let bodyText = "";
    let jsonLdBlocks: ReturnType<typeof parseJsonLd> = [];
  
    if (input.url) {
      const result = await politeFetch(input.url, {
        respectRobots: input.respect_robots,
        hostDelays,
        robotsCache,
      });
      const pageData = parseBody(result.body, input.url);
      bodyText = pageData.bodyText;
      jsonLdBlocks = parseJsonLd(result.body);
    } else {
      bodyText = input.text!;
    }
  
    const jsonLdEntities = extractJsonLdEntities(jsonLdBlocks);
    const textEntities = extractTextEntities(bodyText);
    const entities = mergeEntities(jsonLdEntities, textEntities, bodyText);
  
    const entity_count = entities.length;
    const connected_entity_count = entities.filter((e) => e.same_as.length > 0).length;
    // Threshold: 15 connected entities = score of 100
    const citation_density_score = Math.min(100, Math.round((connected_entity_count / 15) * 100));
  
    if (entity_count === 0) {
      findings.push({
        severity: "warning",
        category: "authority",
        where: "page-level",
        message: "No named entities detected on this page.",
        fix: "Add JSON-LD schema with named entities (Organization, Person, Product) and sameAs links.",
        estimated_impact: "medium",
      });
    } else if (connected_entity_count < 5) {
      findings.push({
        severity: "warning",
        category: "authority",
        where: "page-level",
        message: `Only ${connected_entity_count} entities have sameAs links. Pages with 15+ connected entities have 4.8x higher AI citation probability.`,
        fix: "Add sameAs links to JSON-LD entity nodes pointing to Wikidata, Wikipedia, LinkedIn, or official brand sites.",
        estimated_impact: "high",
      });
    }
  
    return {
      entities,
      entity_count,
      connected_entity_count,
      citation_density_score,
      findings,
    };
  }

• src/tools/extract-entities.ts:16-24 (schema)

  Zod input schema (url, text, respect_robots) and TypeScript output interface (entities, entity_count, connected_entity_count, citation_density_score, findings).

  export const extractEntitiesInputSchema = z
    .object({
      url: z.string().url().optional(),
      text: z.string().optional(),
      respect_robots: z.boolean().optional().default(true),
    })
    .refine((d) => d.url !== undefined || d.text !== undefined, {
      message: "One of url or text is required",
    });

• src/index.ts:356-388 (registration)

  MCP server registration of extract_entities tool with description, inline Zod parameter schema, and handler that wraps extractEntities.

  // --- Tool 13: extract_entities ---
  server.tool(
    "extract_entities",
    [
      "Extract named entities, linked concepts, and sameAs graph nodes from a page's content and structured data. Combines body-text NER heuristics with JSON-LD `@type` / `sameAs` walking.",
      "Read-only when given `url` (one HTTP GET). Zero network when given `text`.",
      "Deterministic, rule-based; no LLM. Output is a list of entities with type, confidence, and any sameAs URIs found in structured data.",
      "When to use: building an entity map for schema generation, or auditing whether a page's entities match its target topic. To validate the JSON-LD itself, use `audit_schema`.",
      "Either `url` or `text` must be provided.",
    ].join("\n\n"),
    {
      url: z
        .string()
        .url()
        .optional()
        .describe("Public URL to fetch and analyze. Either this OR `text` is required."),
      text: z
        .string()
        .optional()
        .describe("Raw text/HTML to analyze directly. Either this OR `url` is required."),
      respect_robots: z
        .boolean()
        .optional()
        .default(true)
        .describe("If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used."),
    },
    async (input) => {
      if (!input.url && !input.text) {
        return toolError({ type: "invalid_url", message: "One of url or text is required" });
      }
      return wrapHandler(() => extractEntities(input as Parameters<typeof extractEntities>[0]));
    }
  );

• src/lib/entities.ts:29-51 (helper)

  Extracts typed entities (name, type, sameAs) from parsed JSON-LD blocks.

  export function extractJsonLdEntities(
    blocks: Array<{ parsed: Record<string, unknown>; types: string[] }>
  ): ExtractedEntity[] {
    const entities: ExtractedEntity[] = [];
    for (const block of blocks) {
      const name = block.parsed["name"];
      if (typeof name !== "string" || !name.trim()) continue;
      const sameAs = block.parsed["sameAs"];
      const saList: string[] = Array.isArray(sameAs)
        ? (sameAs as string[])
        : typeof sameAs === "string"
        ? [sameAs]
        : [];
      entities.push({
        name: name.trim(),
        type: block.types[0] ?? null,
        same_as: saList,
        mention_count: 0, // will be updated by text pass
        is_defined: false,
      });
    }
    return entities;
  }

• src/lib/entities.ts:99-122 (helper)

  Merges JSON-LD entities with text-extracted entities, updating mention counts from body text.

  export function mergeEntities(
    jsonLdEntities: ExtractedEntity[],
    textEntities: ExtractedEntity[],
    bodyText: string
  ): ExtractedEntity[] {
    const merged = new Map<string, ExtractedEntity>();
  
    // Add JSON-LD entities first
    for (const e of jsonLdEntities) {
      const key = e.name.toLowerCase();
      const count = countOccurrences(bodyText, e.name);
      merged.set(key, { ...e, mention_count: count });
    }
  
    // Add text entities (skip if already captured from JSON-LD)
    for (const e of textEntities) {
      const key = e.name.toLowerCase();
      if (!merged.has(key)) {
        merged.set(key, e);
      }
    }
  
    return Array.from(merged.values()).sort((a, b) => b.mention_count - a.mention_count);
  }