Schema.org MCP Server

A Model Context Protocol server for the complete schema.org vocabulary

Empower AI assistants to explore schema.org types, generate JSON-LD examples, validate structured data, and navigate the complete ontology with intelligent fuzzy matching and persistent caching.

Features · Installation · Quick Start · Documentation · Contributing

Table of Contents

• Features

• Installation

• Quick Start

• Available Tools

  • Operational Tools

  • Core Tools

  • Batch Tools

• Example Workflows

• How It Works

• Configuration

• Development

• Deployment

• Troubleshooting

• Contributing

• License

Related MCP server: mcp-json-yaml-toml

Features

v1.1.0 Highlights

Core Capabilities

• Type Exploration — Detailed information about any schema.org type with deprecation status

• Smart Search — Keyword search with relevance-based ranking

• Hierarchy Navigation — Explore inheritance relationships, ancestors, and descendants

• Property Discovery — List all properties with expected types, including inherited ones

• JSON-LD Generation — Create realistic examples at minimal, standard, or comprehensive detail levels

• Validation — Check structured data against the schema.org vocabulary with actionable feedback

• Relationship Mapping — Discover types connected through property relationships

Installation

Prerequisites

• Node.js >= 18.0.0

• npm or yarn

Install via npm (recommended)

npm install -g schema-org-mcp

Or run directly without installing:

npx schema-org-mcp

Build from Source

# Clone the repository
git clone https://github.com/Theycallmeholla/schema-org-mcp.git
cd schema-org-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Verify the installation
npm start

Quick Start

Integration with Claude Desktop

Add the server to your Claude Desktop configuration:

Via npx (recommended):

{
  "mcpServers": {
    "schema-org": {
      "command": "npx",
      "args": ["schema-org-mcp"]
    }
  }
}

Local build:

{
  "mcpServers": {
    "schema-org": {
      "command": "node",
      "args": ["/absolute/path/to/schema-org-mcp/dist/index.js"]
    }
  }
}

Available Tools

The server provides 14 tools organized into three categories.

Operational Tools

server_info

Returns server version, build metadata, and runtime information. Use this to verify which version is deployed.

{}

Response:

• version, gitSha, gitBranch, buildTime

• runtime — Node version, platform, uptime

• tools — Count and names of registered tools

• cache — Cache status

server_stats

Returns performance statistics including cache hit rates, tool invocation counts, and timing metrics.

{}

Response:

• coldStartMs, warmStartMs

• cacheHits, cacheMisses, cacheStaleHits

• toolInvocations — Per-tool count, errors, average duration

• uptimeMs

Core Tools

get_schema_type

Retrieve detailed information about a schema.org type. Supports fuzzy matching for typos and natural aliases.

{
  "typeName": "Person"
}

Also accepts:

• Typos: "Persn" → suggests Person

• Aliases: "blog" → BlogPosting, "faq" → FAQPage

Response:

• name, description, id, url

• superTypes — Direct parent types

• category — core, pending, auto, bib, or health-lifesci

• deprecated and supersededBy (if applicable)

search_schemas

Search for schema types by keyword with relevance-based ranking.

{
  "query": "local business",
  "limit": 10
}

get_type_hierarchy

Get complete inheritance hierarchy including ancestors and children.

{
  "typeName": "NewsArticle"
}

get_type_properties

List all properties available for a type with filtering and pagination support.

{
  "typeName": "Organization",
  "mode": "direct",
  "includeDeprecated": false,
  "limit": 20,
  "offset": 0
}

generate_example

Generate realistic JSON-LD examples with dynamic dates and nested types.

{
  "typeName": "LocalBusiness",
  "style": "comprehensive",
  "customProperties": {
    "name": "My Coffee Shop"
  }
}

Supported domain presets: Person, Organization, LocalBusiness, Product, Event, Article, BlogPosting, Recipe, WebSite, FAQPage, Place

get_property_details

Get comprehensive information about a specific property. Supports fuzzy matching.

{
  "propertyName": "address"
}

get_enumeration_values

Retrieve all valid values for an enumeration type.

{
  "enumerationType": "DayOfWeek"
}

validate_jsonld

Validate JSON-LD structured data with intelligent suggestions for typos.

{
  "jsonld": {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": "Widget",
    "nmae": "typo"
  }
}

Response:

• valid — Boolean result

• errors — Unknown types or properties with suggestions

• warnings — Deprecated items, missing context

• suggestions — Recommended properties to add

get_related_types

Discover types connected through property relationships.

{
  "typeName": "Person"
}

Batch Tools

get_multiple_types

Retrieve information about multiple types in a single call.

{
  "typeNames": ["Person", "Organization", "LocalBusiness"]
}

compare_types

Compare 2–5 schema.org types side by side with usage recommendations.

{
  "typeNames": ["Article", "BlogPosting", "NewsArticle"]
}

Response:

• types — Summary of each type

• sharedProperties — Properties common to all

• uniqueProperties — Properties unique to each

• recommendation — When to use each type

validate_jsonld_batch

Validate multiple JSON-LD objects in a single call.

{
  "items": [
    { "@context": "https://schema.org", "@type": "Person", "name": "John" },
    { "@context": "https://schema.org", "@type": "Organization", "name": "Acme" }
  ]
}

Example Workflows

E-commerce 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"}

Article vs BlogPosting Decision

1. compare_types → {"typeNames": ["Article", "BlogPosting"]}

   Response includes recommendation:
   "Use BlogPosting for blog content with clear publication dates and author.
    Use Article for general news or editorial content."

Bulk Markup Validation

1. validate_jsonld_batch → {"items": [...array of JSON-LD objects...]}

   Returns per-object validation with actionable suggestions

Typo Recovery

1. get_schema_type → {"typeName": "Perosn"}

   Error: "Type 'Perosn' not found. Did you mean: Person, Physician, Performer?"

How It Works

Caching Architecture

The server fetches the complete schema.org vocabulary and implements a multi-layer cache:

• TTL: 24 hours (configurable)

• Fallback: Uses stale cache if schema.org is unavailable

Fuzzy Matching Pipeline

1. Check natural language aliases (blog → BlogPosting)

2. Attempt case-insensitive and normalized matching

3. Calculate similarity scores using Levenshtein distance

4. Return top 3 suggestions if score > 0.4

Indexed Data

Configuration

The client accepts optional configuration parameters:

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
});

Development

# Watch mode for development
npm run dev

# Run the test suite
npm test

# Build for production (generates build fingerprint)
npm run build

# Run full QA checklist
npm run qa

# Verify deployment
npm run verify

Deployment

Build with Fingerprint

Every build embeds version metadata for traceability:

npm run build
# Output: Build info generated: v1.1.0 (abc1234)

Verify Deployment

Confirm the correct version is running:

npm run verify

# Or with explicit version:
npm run verify 1.1.0 abc1234

Verification checks:

1. Version and git SHA match

2. compare_types tool responds correctly

3. Fuzzy matching returns suggestions

4. FAQPage examples include mainEntity

5. Cache status is available

Runtime Fingerprint

On startup, the server logs its identity:

═══════════════════════════════════════════
schema-org-mcp v1.1.0 (abc1234)
Built: 2025-04-04T15:00:00.000Z
Branch: main
Node: v22.20.0
Tools: 14 registered
  server_info, server_stats, get_schema_type, ...
═══════════════════════════════════════════

Use the server_info tool to check the running version programmatically.

Troubleshooting

Slow Cold Start

If the first request is slow, the cache may have expired:

ls -la ~/.cache/schema-org-mcp/

Fuzzy Suggestions Not Appearing

Ensure schema data is fully loaded. The initialize() method must complete before fuzzy matching works.

Force Cache Refresh

Delete the cache directory to fetch fresh data:

rm -rf ~/.cache/schema-org-mcp/

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Please ensure all tests pass before submitting.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Back to Top