Schema.org MCP服务器
一个MCP（模型上下文协议）服务器，提供对结构化数据的schema.org词汇表的全面访问。该服务器使AI助手能够探索类型，生成JSON-LD示例，验证结构化数据，并浏览完整的schema.org本体。
v1.1.0功能
- 持久缓存：Schema.org数据通过基于TTL的刷新在本地缓存，消除了冷启动延迟
- 模糊匹配：使用“你的意思是什么？”建议对类型和属性进行拼写错误容忍查找
- 类型别名：自然语言快捷方式，如“博客”→ 博客发布，“常见问题解答”→ 常见问题页面
- 筛选属性检索：仅获取直接、仅继承或分页的属性列表
- 批量操作：比较类型、验证多个JSON-LD对象、批量类型查找
- 动态示例：生成的示例使用当前日期和现实数据
核心功能
- 获取架构类型：检索有关任何schema.org类型的详细信息，包括弃用状态
- 搜索模式：按关键字和相关性排名搜索模式类型
- 类型层次结构：探索继承关系、祖先和子女
- 类型属性：列出所有具有预期类型的属性，包括继承的属性
- 生成示例：创建具有多个细节级别的逼真JSON-LD示例
- 属性详细信息：获取有关特定房产的全面信息
- 枚举值：检索枚举类型的所有有效值
- 验证JSON-LD：根据schema.org词汇表验证结构化数据
- 相关类型：发现通过属性关系连接的类型
安装
# Clone the repository
git clone https://github.com/your-org/schema-org-mcp.git
cd schema-org-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run the server
npm start用法
使用克劳德桌面
将此添加到您的Claude Desktop配置中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"schema-org": {
"command": "node",
"args": ["/absolute/path/to/schema-org-mcp/dist/index.js"]
}
}
}使用npx（发布后）
{
"mcpServers": {
"schema-org": {
"command": "npx",
"args": ["schema-org-mcp"]
}
}
}可用工具（共14个）
操作工具
服务器信息
获取服务器版本、构建信息和运行时指纹。 使用此选项验证部署了哪个版本。
{}答复包括：
version,gitSha,gitBranch,buildTimeruntime-节点版本、平台、正常运行时间tools-注册工具的数量和名称cache-缓存状态
服务器状态
获取服务器性能统计数据，包括缓存命中率、工具调用计数和时间。
{}答复包括：
coldStartMs,warmStartMscacheHits,cacheMisses,cacheStaleHitstoolInvocations-每工具计数、错误、平均值uptimeMs
核心工具
1.get_schema_type
获取schema.org类型的详细信息。 支持拼写错误的模糊匹配。
{
"typeName": "Person"
}也适用于：
- 拼写错误：“Persn”→ 建议使用“Person”
- 别名：“博客”→ 博客发布，“常见问题解答”→ 常见问题页面
答复包括：
name,description,id,urlsuperTypes-直接父类型category-核心、待定、自动、bib或健康生活deprecated和supersededBy（如适用）
2.搜索模式
通过基于相关性的排名按关键字搜索模式类型。
{
"query": "local business",
"limit": 10
}3.获取类型层次结构
获取完整的继承层次结构，包括祖先和子代。
{
"typeName": "NewsArticle"
}4.获取类型属性
获取某一类型的所有可用属性。 现在支持过滤和分页。
{
"typeName": "Organization",
"mode": "direct",
"includeDeprecated": false,
"limit": 20,
"offset": 0
}筛选器选项：
mode：“全部”（默认）、“直接”（仅此类型）、“继承”（仅来自父母）includeDeprecated：false（默认）或truelimit：要返回的最大属性数offset：跳过这么多属性（分页）
5.生成示例
生成逼真的JSON-LD示例。 现在使用动态日期。
{
"typeName": "LocalBusiness",
"style": "comprehensive",
"customProperties": {
"name": "My Coffee Shop"
}
}样式选项：
minimal-只是名称属性standard-常见属性comprehensive-许多具有嵌套类型的相关属性
支持的域预设：
- 个人、组织、当地企业
- 产品、活动、文章、博客发布
- 食谱、网站、常见问题页面、地点
6.获取_属性_详细信息
获取有关特定房产的全面信息。 支持模糊匹配。
{
"propertyName": "address"
}7.获取数值
获取枚举类型的所有有效值。
{
"enumerationType": "DayOfWeek"
}8.validate_jsonld
验证JSON-LD结构化数据。 现在为拼写错误提供“你的意思是什么？”建议。
{
"jsonld": {
"@context": "https://schema.org",
"@type": "Product",
"name": "Widget",
"nmae": "typo"
}
}答复包括：
valid-布尔验证结果errors-未知类型或属性（带建议）warnings-弃用的类型/属性，缺少上下文suggestions-要添加的推荐属性
9.获取相关类型
查找通过属性关系连接的类型。
{
"typeName": "Person"
}批处理工具（v1.1.0中的新功能）
10.多种类型
在一次呼叫中获取有关多种类型的信息。
{
"typeNames": ["Person", "Organization", "LocalBusiness"]
}11.比较类型
并排比较2-5种schema.org类型。 包括建议。
{
"typeNames": ["Article", "BlogPosting", "NewsArticle"]
}答复包括：
types-每种类型的总结sharedProperties-所有类型共有的属性uniqueProperties-每种类型特有的属性recommendation-何时使用每种类型（用于常见比较）
12.验证_jsonld_batch
在一次调用中验证多个JSON-LD对象。
{
"items": [
{ "@context": "https://schema.org", "@type": "Person", "name": "John" },
{ "@context": "https://schema.org", "@type": "Organization", "name": "Acme" }
]
}示例工作流
寻找电子商务类型
User: "What schema.org types should I use for a product page?"
1. search_schemas: {"query": "product"}
2. compare_types: {"typeNames": ["Product", "Offer", "AggregateOffer"]}
3. get_type_properties: {"typeName": "Product", "mode": "direct", "limit": 15}
4. generate_example: {"typeName": "Product", "style": "comprehensive"}文章与博客发布决策
User: "Should I use Article or BlogPosting?"
1. compare_types: {"typeNames": ["Article", "BlogPosting"]}
→ Returns recommendation: "Use BlogPosting for blog content with clear publication dates and author. Use Article for general news or editorial content."验证多个标记块
User: "Validate all my schema markup"
1. validate_jsonld_batch: {"items": [...array of JSON-LD objects...]}
→ Returns per-object validation with suggestions处理拼写错误
User: "What properties does a Perosn have?"
1. get_schema_type: {"typeName": "Perosn"}
→ Error: "Type 'Perosn' not found. Did you mean: Person, Physician, Performer?"运作原理
缓存
服务器获取完整的schema.org词汇表并将其缓存在本地：
- 位置:
~/.cache/schema-org-mcp/schema-org-data.json - 生存时间：24小时（可配置）
- 后备方案：如果schema.org不可用，则使用过时的缓存
- 记忆：首次加载后，数据也会缓存在内存中
模糊匹配
当未准确找到类型或属性时：
- 检查自然语言别名（博客→ 博客发布）
- 尝试不区分大小写和规范化匹配
- 使用Levenshtein距离计算相似性得分
- 如果得分>0.4，返回前3条建议
数据已索引
- 约800+种（类）
- 约1400多处房产
- ~ 80+个枚举类型及其值
发展
# Run TypeScript compiler in watch mode
npm run dev
# Run tests (requires network access for first run)
npm test
# Build for production (generates build fingerprint)
npm run build
# Run full QA checklist
npm run qa
# Verify deployment
npm run verify部署
使用指纹构建
每个构建都嵌入了版本、git SHA、分支和时间戳：
npm run build
# Output: Build info generated: v1.1.0 (abc1234)验证部署
部署后，验证运行的版本是否正确：
npm run verify
# Or with explicit version:
npm run verify 1.1.0 abc1234这将运行金丝雀检查：
- 版本和git SHA匹配
compare_types工具工程- 模糊匹配给出建议
- FAQPage示例有main Entity
- 缓存状态可用
运行时指纹
启动时，服务器会记录其指纹：
═══════════════════════════════════════════
schema-org-mcp v1.1.0 (abc1234)
Built: 2026-04-04T15:00:00.000Z
Branch: main
Node: v22.20.0
Tools: 14 registered
server_info, server_stats, get_schema_type, ...
═══════════════════════════════════════════使用 server_info 以编程方式检查运行版本的工具。
配置
客户端接受可选配置：
const client = new SchemaOrgClient({
cacheDir: '/custom/cache/path', // Default: ~/.cache/schema-org-mcp
ttlMs: 12 * 60 * 60 * 1000, // Default: 24 hours
offline: false, // Default: false (fetch from network)
});需求
- Node.js>=18.0.0
- 网络访问以获取schema.org词汇表（首次使用时）
故障排除
冷启动仍然缓慢
如果第一个请求很慢，则缓存可能已过期。检查：
ls -la ~/.cache/schema-org-mcp/打字建议不起作用
模糊匹配需要加载模式数据。确保 initialize() 在搜索之前完成。
缓存问题
要强制重新获取，请删除缓存：
rm -rf ~/.cache/schema-org-mcp/贡献
欢迎投稿！请随时提交拉取请求。
许可证
MIT许可证-有关详细信息，请参阅许可证文件。