MCP 服务器（claude.ai / Claude Desktop / Code / Cursor）- Entity Enricher 文档

MCP 服务器（Claude Desktop / Code / Cursor）

Entity Enricher 在 /api/mcp 内置了一个 Model Context Protocol 服务器——列出您的模式、增强实体、检查结果并解决分类警告，全部在一个 Claude 聊天中完成。无需工作流编辑器。

既然已有 n8n + Make，为何还需要 MCP？

形态不同,用例也不同。n8n 和 Make 连接器为工作流自动化封装 API:触发器、定时运行、多步骤管道、持久化状态。MCP 则为交互式聊天封装 API:临时提问、探索式富集、后续澄清。工作流呈批量形态,聊天呈对话形态——界面不同,用户体验也不同。

只有 MCP 才能解锁的杀手级功能：交互式分类恢复。当预检分类器拒绝你的实体时（例如你要求以 Planet schema 增强“Titan”，但 Titan 是一颗卫星），n8n/Make 由于是非交互式的，只能自动取消。MCP 会将警告呈现给 Claude，Claude 会请你确认，一旦“确认”，工具便会跳过分类器重新运行。不会在流程中途失败，也无需从头重来。

快速开始

方式 1 — OAuth（推荐）

适用于 claude.ai、Claude Code、Cursor 以及任何支持标准 OAuth 流程的 MCP 客户端。无需创建或粘贴 API 密钥——客户端会自动发现授权服务器。

将 Entity Enricher 添加为连接器（在 claude.ai 中：设置 → 连接器 → 添加自定义连接器，或从目录中选择），URL 为 https://entityenricher.ai/api/mcp/。
浏览器将打开 Entity Enricher 授权确认页面——如有需要请登录，然后点击授权。该连接将以你自己的角色代表你执行操作。
可随时在 API 密钥 → 已连接应用 下管理或撤销连接——撤销将立即切断访问权限。

方式 2 — API 密钥（静态 JSON 配置）

适用于通过 JSON 文件配置而非交互式登录的客户端（Claude Desktop、Continue、Zed）。

1. 创建 API 密钥
在 Entity Enricher 网页界面中：设置 → API 密钥 → 新建组织访问密钥。选择一个角色（operator 主要用于只读，editor 用于创建/编辑 schema，owner 拥有完全控制权）。复制 ent_… 值——它只会显示一次。
2. 在您的 MCP 客户端中注册
对于 Claude Desktop，请编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：
```
{
  "mcpServers": {
    "entityenricher": {
      "url": "https://entityenricher.ai/api/mcp/",
      "headers": { "X-API-Key": "ent_your_key_here" }
    }
  }
}
```
重启 Claude Desktop。同样的代码片段适用于 Claude Code、Cursor、Continue 和 Zed——任何兼容 MCP 的客户端。

试一试

在新对话中：“列出我的 Entity Enricher schema，然后使用 Claude Sonnet 根据制药公司 schema 增强 Sanofi。” Claude 会自动发现工具、选择正确的工具、提示您确认模型和 schema 的选择，并内联流式返回结果。

工具

54 个工具覆盖了扩充、schema 编写、数据库同步和语义 ID 的全部功能。其行为与所封装的 REST 端点完全一致（相同的校验、计费和套餐限制）——Web 界面修复的问题，MCP 也会同步获得修复。长时间运行的任务（批量扩充、样本生成、基准测试运行）为异步执行：启动工具返回 job_id，Claude 轮询 get_job_status，任务完成后再从你的记录中获取已保存的输出。

类别	工具	描述
发现	list_models	列出模型密钥、标称能力、自动选择的默认值以及您套餐的 profile_limits。优先使用自动选择：可用性并不保证每个提供商的配额或组合的媒体/工具模式。
Schema	list_schemas	列出你组织中已保存的 JSON 模式，置顶项优先。
Schema	get_schema	通过 UUID 获取 schema 的完整内容。
Schema	generate_sample	在一次任务中生成 1..N 份可编辑的示例合同（第一份定义字段集，其余为字段相同的快速实例变体），支持知识模式（无附件，可选网页搜索）或来源模式（附件为权威依据，规划器可能会提出问题）。在创建 schema 之前，请与用户一起审阅重要编辑。
Schema	create_schema_from_sample	从 entity_samples（同一实体类型的 1..N 个样本——字段取并集，缺失处可为空，采用真实观测到的示例）、sample_record_id，或经编辑的数据加上其关联记录的附件，生成并自动保存 schema。语义 ID 需主动选用；建议会经过审阅，绝不自动应用。
Schema	save_schema	持久化 Claude 直接编写的模式——无需 LLM 调用、无成本，并在服务器端完成校验。
Schema	update_schema	无需 LLM 调用，即可对已保存的架构进行重命名、替换内容、重新打标签、置顶或开关歧义检查。
Schema	get_schema_part	无需完整文档即可读取模式的某一部分：命名类型索引、$defs/$enums 定义、对象子树，或包含其关系与标志的单个属性卡片。
Schema	update_schema_property	按路径编辑单个属性——重命名、类型或 $ref、描述、示例、标志——或将其删除，并附带服务端校验；无需完整内容往返传输。
Schema	add_schema_property	向根节点、嵌套对象或 $defs 类型添加标量、嵌套对象或 $ref 属性。
Schema	move_schema_property	将某个属性移动到另一个容器——根、嵌套对象或 $defs 类型——并保留其标记和专业领域。
Schema	publish_schema	将已链接模式的工作副本发布为数据丰富及其数据库同步所依据的契约。结构性编辑仅在此处生效——而新链接的同步在其模式首次发布之前不会传输任何内容。validate_only=true 可预览迁移差异。
Schema	analyze_sample	分析示例 JSON，找出在其父级上下文中可有多种解读（或完全无从解读）的属性名，以及将实体事实与各父级专属事实混在一起的关联项。生成无状态报告，列出相互冲突的解读及重命名建议；不修改任何内容。
Schema	analyze_schema	对已保存的架构运行歧义检查和身份范围检查，并写入逐属性的注释——由于已上线的架构无法重命名，会为每个有歧义的名称重写描述。默认增量执行，force=true 则重新分析全部。
Schema	delete_schema	按 UUID 软删除已保存的模式。
丰富化	enrich_entity	带可选自动融合的多模型增强。接受可选的 attachment_ids 列表。分类不匹配时返回非错误响应，以便 Claude 可以要求用户确认并重试。
丰富化	start_batch_enrichment	异步丰富任意数量的实体——无固定批次大小上限，仅受套餐实时用量配额限制——每个实体运行完整流程并自动融合。返回 job_id；结果将写入你的记录。
丰富化	fetch_entities	在服务器端从外部 REST API 获取实体的 JSON 数组（bearer / api_key / basic 认证）——与批量增强搭配使用。
丰富化	retry_expertises	仅重新运行某条记录中失败的专业领域，并将恢复的值合并回来——已成功的部分无需再次付费。
丰富化	merge_records	将 2 个以上的现有记录合并为一个融合结果——基于规则或使用 LLM 仲裁模型。
作业	get_job_status	轮询异步作业以获取进度、结果、失败和澄清问题。在显式模型兼容性失败后，请使用自动选择重试一次，而不是逐个尝试模型。
作业	cancel_job	取消处于待处理、运行中或已暂停状态的作业。
作业	answer_job_question	回答已暂停作业的澄清问题并恢复该作业——generate_sample 的交互式部分。
基准测试	list_benchmark_scenarios	列出你保存的基准测试场景（可复用的增强测试）。
基准测试	get_benchmark_scenario	一个场景及其按模型评分的结果（质量 / 成本 / 速度）。
基准测试	create_benchmark_scenario	创建场景：模式 + 固定实体 + 策略 + 评分裁判。需要所有者角色以及包含基准测试的套餐。
基准测试	update_benchmark_scenario	更新场景的测试定义或评分配置；现有结果会被标记为过期。
基准测试	set_benchmark_reference	保存黄金参考输出并将其标记为已验证——运行前必需。
基准测试	delete_benchmark_scenario	删除场景及其结果。
基准测试	run_benchmark	在指定的模型列表、所选提供商的每个活跃模型或全部活跃模型上运行场景——每个结果都会根据参考基准自动评分。
记录	list_records	分页浏览扩充、示例/架构生成、架构编辑、演练场、分类、仲裁和歧义分析记录，并可按成功状态、模型、任务和搜索条件筛选。
记录	get_record	单条记录的完整结构化输出 + 验证错误。
记录	get_stats	汇总的组织统计数据：总数、成功率、令牌数、成本。
附件	upload_attachment	上传 base64 文件并返回其附件 ID 以及所需的模型能力。将该 ID 传给 generate_sample 会激活源模式。
附件	delete_attachment	按 ID 删除附件——便捷的丰富后清理步骤。
Database Sync	list_database_syncs	列出在已保存模式上注册的数据库同步，包含待处理的增量数量以及每个同步的选项。
Database Sync	create_database_sync	将数据库连接到已保存的 schema，把它的 enrichment 转换为可用于你自己 PostgreSQL 的关系型 SQL 增量。schema 以未发布状态链接，数据库模型在后台进行 classification——审阅完成后，publish_schema 即会启动数据推送。
Database Sync	classify_database_model	在编辑已链接的 schema 后重新运行数据库模型 classification：由 LLM 为每个新增或变更的 property 提出其 key、SQL 类型、索引和归属。首次执行会在数据库连接时自动完成。
Database Sync	delete_database_sync	删除数据库同步及其排队的增量——你的副本表绝不会被触及。可选的拆除标志还会删除不再关联任何数据库的模式的实体状态和数据库模型。
Database Sync	create_database_credential	(重新)签发数据库同步的 sync-client 凭据——ee-database 工作流的配对步骤，随安装和配对命令一并返回。
Database Sync	fetch_database_deltas	获取数据库同步的下一个 FIFO 窗口的 SQL 增量——claim=true 为其租约以进行确认交付，claim=false 则是可重放的读取。
Database Sync	ack_database_deltas	确认已应用直至某个 id 的增量：释放租约并应用该同步的清除选项。
Database Sync	assign_sync_host	指定（或清除）在托管模式下预配数据库同步的同步主机 — 主机会认领凭据、在物理数据库缺失时创建它并开始同步，无需手动配对。
Database Sync	list_entity_states	浏览某个模式当前的实体状态 — 即实体层保存、并由每个关联数据库镜像的去重、后写入优先的行，而非 list_records 的逐次运行记录。
Database Sync	sync_records_to_database	将已存储的富化输出注入某个模式的 Database Sync —— 会依据已发布的契约重新校验，然后通过准入关卡。
语义 ID	list_semantic_concepts	浏览组织的概念词汇表及其类型分面——或使用 view="duplicates" 查看略低于解析阈值的概念对。
语义 ID	get_semantic_concept	完整展示单个概念：表面形式、身份来源键、关联记录，以及带相似度的最近邻（仅在其所属概念类型和嵌入模型切片内有定义）。
语义 ID	probe_semantic_concept	对某段文本试运行解析阶梯——查看富化会如何处理它——且不创建任何内容。新增前先探测。
语义 ID	add_semantic_concept	新增一个使用次数为 0 的概念，或通过 alias_of 为已有概念新增一种表面形式。若该文本已在阈值内被覆盖，则请求被拒绝并返回既有概念。
语义 ID	update_concept_alias	移除概念的某个表面形式，或将其提升为规范形式。最后一个表面形式不可移除——删除概念应由删除流程完成。
语义 ID	import_semantic_concepts	通过富化阶梯解析最多 1000 条身份文本：默认输出逐行报告，使用 mint=true（所有者权限）可为未命中项创建新概念。
语义 ID	merge_semantic_concepts	将一个概念合并到另一个概念中。impact_only=true（默认）会报告影响范围；合并本身（所有者权限）会重新指向别名和实体，并使每个关联数据库收敛。
语义 ID	delete_semantic_concepts	按 id、整个类型或仅未使用项删除概念。impact_only=true（默认）会先报告数量以及受影响的架构/数据库；删除操作可自愈，但会破坏与已存储 id 的收敛。
语义 ID	migrate_semantic_embeddings	查看组织嵌入模型迁移的状态、冲突预览，或启动/取消迁移——这是在嵌入模型之间迁移现有概念的唯一方式。

样本生成模式

知识模式

省略 attachment_ids。模型会根据其知识设计可复用的样本，而 enable_web_search=true 可以为外部事实提供依据。

源模式

传入 attachment_ids。规划器将这些文件视为权威依据：它会转录文档中的值，或仅描述照片中可见的属性。字段和额外指令无法添加不相关的外部事实。

你的额外指令具有约束力

你传入的额外指令，要么被执行，要么会明确回报为未被执行。如果某条确定性规则不得不撤销你的要求——比如生成器无法输出的结构——完成的任务会带上一个 warnings 列表加以说明。请把这些信息转达给用户：被悄悄忽略的指令，正是样本悄无声息出错的根源。

对于混合请求，例如从照片中识别一辆汽车并研究其公开露面情况，请调用两次 generate_sample：先在源模式下关闭网络搜索，然后在不带附件的情况下使用已确认的身份并开启网络搜索。在对话中合并结果；Entity Enricher 会保留独立的记录，以便源观测和研究得出的事实保持各自不同的出处。

除非您明确需要某个模型，否则请保持 model=auto。自动选择会应用任务、附件和网络搜索要求；可用的模型密钥仍可能遇到特定提供商的配额或组合工具限制。

批准样本，然后审查 schema

样本即契约

在生成 schema 之前，客户端会审查实体范围、键、类型、基数、缺失的代表性字段以及嵌套关系。重要的编辑会分组提交给您批准；事实值和结构绝不会被静默更改。

在有用时选择稳定的语义 ID

对于关系表、主数据、知识图谱或可复用的嵌套实体，客户端会询问是否生成语义 ID。它们需要组织的嵌入模型并会增加嵌入成本，因此默认保持禁用。

传入 entity_data 以创建新的或编辑后的样本，或传入 sample_record_id 以复用已存储的 JSON 及其关联附件。同时传入两者时，会使用编辑后的 JSON 并保留附件。显式的 attachment_ids（包括空列表）会覆盖继承。

生成后，客户端会检查样本一致性、键、注释、专业领域、关系以及语义 ID 覆盖情况。结构性建议需要编辑样本并重新生成；仅注释的编辑仍需您的批准。任何内容都不会自动应用。

资源

资源让 Claude 无需消耗工具调用即可浏览数据——LLM 客户端会把它们当作文件对待。两种资源类型都以 Markdown 渲染，便于低成本内联展示。

URI 模板	描述
enricher://schemas/{schema_id}	以 Markdown 呈现的已保存架构——元数据标题 + 作为 JSON 代码块的 GeneratedJsonSchema。
enricher://records/{record_id}	以 Markdown 呈现的过往扩充记录——元数据 + 结构化输出 + 校验错误。

杀手级功能：交互式分类恢复

当你要求 enrich_entity 使用分类模型，而实体与架构类型不匹配时，该工具会返回一个非错误响应，其中包含结构化的详细信息。Claude 会读取该响应，将推理过程呈现给你，并（在你确认后）使用 force_after_classification_warning=true 重试——即在重试时跳过分类器。

{
  "success": false,
  "error_code": "classification_warning",
  "message": "Pre-flight classification rejected the entity. ...",
  "classification": {
    "status": "mismatch",
    "reasoning": "Titan is a moon of Saturn, not a planet.",
    "confidence": 0.97
  },
  "job_id": "..."
}

n8n 和 Make 在此状态下会自动取消，因为它们无法在流水线中途询问用户。MCP 可以做到，正是这一点差异让该连接器有了存在的意义。

同样的交互能力也驱动着第二种流程：当 generate_sample 带源文档运行时，其规划器可能会暂停并提出结构性澄清问题。Claude 会将它们转达给你，并通过 answer_job_question 恢复作业——一轮接一轮，直到样本生成完毕。

错误代码

工具错误会被映射为带有 error_code 字段的结构化字典，以便 Claude 进行模式匹配，而无需解析自由文本。HTTP 层的映射清晰明确：402 → 配额或额度错误，422 → 分类警告，504 → 超时，502 → 上游 LLM 故障。

error_code	时间
invalid_request	UUID 格式错误、参数互斥（schema_id + target_schema），或请求体验证失败。
prompt_limit_reached	每日／每周／每月 prompt 配额已用尽（HTTP 402）。响应体包含 period、limit、used、needed。
insufficient_credits	组织已启用计费，但信用额余额过低，无法启动任务（HTTP 402）。响应正文包含余额和购买链接。
model_limit_exceeded	请求的模型数量超出套餐允许范围（HTTP 402）。会回显限制值与请求值。
language_limit_exceeded	请求的语言数量超出套餐允许范围（HTTP 402）。
concurrent_job_limit_reached	该组织正在运行的富集任务过多。请等待或升级套餐。
classification_warning	⚡ 非错误：预检 classifier 拒绝了该 entity。响应中携带 classification 上下文，以便 Claude 请用户确认，并使用 force_after_classification_warning=true 重试。
benchmarks_not_in_plan	基准测试工具需要所有者角色以及包含 Model Benchmarks 的套餐（HTTP 403）。
ambiguity_check_disabled	对一个已关闭歧义检查的架构调用了 analyze_schema（HTTP 400）。请先通过 update_schema 设置 ambiguity_check_enabled=true 重新启用。
enrichment_timeout	作业超过 timeout_seconds。建议减少模型数量或拆分实体。
schema_generation_timeout	Schema 生成超过 timeout_seconds。
schema_generation_failed	生成 schema 时上游 LLM 出错（HTTP 502）。
model_output_invalid	模型返回的输出与 schema 不匹配（HTTP 502）。响应正文中会给出模型名称、出错的属性路径以及 retryable: true —— 请再次调用该工具，或选择更强的 model。
cancelled	作业在运行中被取消（HTTP 499）。
not_found	Schema 或记录 ID 在您的组织中不存在。
http_error	用于捕获没有结构化详情正文的 HTTP 错误。

有意省略的部分

自定义提示词（playground）——Claude 本就能运行任意提示词，将其封装为工具显得多余。
记录删除 / 基准测试结果导入导出 — 破坏性操作和维护操作仍保留在 Web 界面中。
成本分析 — get_stats 提供聊天端的摘要；完整的仪表板仍保留在应用中。

另请参阅

REST API 参考 — MCP 所封装的端点。
n8n 连接器 — 用于工作流自动化。
Make.com 连接器——用于基于场景的流水线。
Model Context Protocol — 服务器实现的开放规范。
GitHub 上的 mcp-server-entity-enricher——客户端配置、方案演练以及问题跟踪。