Back to Documentation

Documentation

Schema Definition

Learn how to define and validate your context schema for different use cases.

What is a Schema?

In MCP, a schema defines the structure and validation rules for your context. It specifies what components are available, their data types, and any constraints on their values.

A well-defined schema helps ensure consistency and makes it easier to maintain your AI application as it grows.

Basic Schema Structure

An MCP schema consists of a set of components, each with its own type and validation rules. Here's a basic example:

// Define your MCP schema
const mcpSchema = {
  version: "1.0",
  components: {
    systemInstruction: {
      type: "string",
      description: "High-level instruction for the LLM",
      required: true
    },
    userGoal: {
      type: "string",
      description: "Current user objective",
      required: true
    },
    memory: {
      type: "object",
      properties: {
        shortTerm: { type: "array" },
        longTerm: { type: "object" }
      }
    },
    tools: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string", required: true },
          description: { type: "string" },
          parameters: { type: "object" }
        }
      }
    },
    retrievedDocuments: {
      type: "array",
      items: { type: "object" }
    }
  }
};

Creating a Context with a Schema

Once you've defined your schema, you can use it to create a new MCP context:

import { MCPContext } from '@modl/mcp';

// Create a context with the schema
const assistant = new MCPContext({
  schema: mcpSchema,
  systemInstruction: "You are a helpful assistant.",
  userGoal: "Answer questions about programming",
  memory: {
    shortTerm: [],
    longTerm: {}
  },
  tools: [
    {
      name: "searchDocumentation",
      description: "Search programming documentation",
      parameters: {
        query: "string",
        language: "string"
      }
    }
  ]
});

The schema will validate the initial context and any updates to ensure they conform to the defined structure.

Schema Types

MCP supports several data types for schema components:

  • string: Text values
  • number: Numeric values
  • boolean: True/false values
  • array: Lists of items
  • object: Nested structures with properties
  • enum: Values from a predefined set

Example with Various Types

const schema = {
  components: {
    // String type
    name: { 
      type: "string",
      minLength: 2,
      maxLength: 50
    },
    
    // Number type
    age: { 
      type: "number",
      minimum: 0,
      maximum: 120
    },
    
    // Boolean type
    isActive: { 
      type: "boolean",
      default: true
    },
    
    // Array type
    tags: { 
      type: "array",
      items: { type: "string" },
      minItems: 1
    },
    
    // Object type
    address: { 
      type: "object",
      properties: {
        street: { type: "string" },
        city: { type: "string" },
        zipCode: { type: "string" }
      },
      required: ["city"]
    },
    
    // Enum type
    role: { 
      type: "string",
      enum: ["user", "admin", "guest"]
    }
  }
};

Schema Validation

MCP automatically validates context updates against the schema. If an update violates the schema, an error will be thrown.

// This will throw an error if the schema requires userGoal to be a string
try {
  assistant.updateContext({
    userGoal: 123 // Error: userGoal must be a string
  });
} catch (error) {
  console.error("Validation error:", error.message);
}

// This will throw an error if a required field is missing
try {
  assistant.updateContext({
    systemInstruction: undefined // Error: systemInstruction is required
  });
} catch (error) {
  console.error("Validation error:", error.message);
}

Custom Schemas for Different Use Cases

You can create custom schemas for different types of AI applications:

E-commerce Assistant Schema

const ecommerceSchema = {
  components: {
    systemInstruction: { type: "string", required: true },
    userGoal: { type: "string", required: true },
    userProfile: {
      type: "object",
      properties: {
        name: { type: "string" },
        style: { type: "array", items: { type: "string" } },
        size: { type: "string" },
        pastPurchases: { type: "array", items: { type: "string" } },
        preferredPriceRange: { type: "string" }
      }
    },
    productCatalog: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          price: { type: "string" },
          features: { type: "array", items: { type: "string" } }
        }
      }
    },
    tools: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          description: { type: "string" },
          parameters: { type: "object" }
        }
      }
    }
  }
};

Customer Support Schema

const supportSchema = {
  components: {
    systemInstruction: { type: "string", required: true },
    userGoal: { type: "string", required: true },
    customerInfo: {
      type: "object",
      properties: {
        name: { type: "string" },
        email: { type: "string" },
        accountCreated: { type: "string" },
        previousTickets: { type: "array" }
      }
    },
    knowledgeBase: {
      type: "array",
      items: {
        type: "object",
        properties: {
          topic: { type: "string" },
          content: { type: "string" }
        }
      }
    },
    tools: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          description: { type: "string" },
          parameters: { type: "object" }
        }
      }
    }
  }
};

Schema Versioning

As your application evolves, you may need to update your schema. MCP supports schema versioning to help manage these changes:

const schemaV1 = {
  version: "1.0",
  components: {
    // Original components
  }
};

const schemaV2 = {
  version: "2.0",
  components: {
    // Updated components
  },
  migrations: {
    "1.0": (oldContext) => {
      // Convert from v1 to v2 format
      return {
        ...oldContext,
        // Add new fields or transform existing ones
      };
    }
  }
};

Next Steps

Now that you understand how to define schemas, you can: