EuConquisto Composer MCP

# Model Context Protocol (MCP) Official Specification Analysis for Educational Content Server Compliance ## Executive Summary The Model Context Protocol (MCP) is Anthropic's open standard for connecting AI applications with external data sources, designed as a "USB-C port for AI applications." Released in November 2024, MCP standardizes how LLMs integrate with tools and data through a client-server architecture built on JSON-RPC 2.0. For educational content management servers, MCP provides a robust framework with three core primitives: Resources (structured content), Tools (executable functions), and Prompts (reusable templates). Key findings indicate that MCP compliance requires strict adherence to JSON-RPC 2.0 messaging, OAuth 2.1 authentication for HTTP transports, capability-based feature negotiation, and comprehensive security measures. Educational MCP servers must implement specific patterns for content exposure, pagination, versioning, and metadata management while maintaining stateful connections and proper session handling. ## MCP server implementation requirements - official specifications ### Core Architecture Requirements MCP servers must implement a **stateful connection model** with three mandatory lifecycle phases. During initialization, servers must respond with their supported protocol version (currently "2025-03-26") and declare capabilities. The operation phase handles bidirectional JSON-RPC 2.0 message exchange, while shutdown relies on transport-specific termination mechanisms. **Required Server Capabilities:** - **Resources**: URI-based structured content with optional subscription support - **Tools**: Executable functions invokable by LLMs with user consent - **Prompts**: Optional pre-defined templates for guided interactions Each capability requires explicit declaration during initialization: ```json { "capabilities": { "resources": { "subscribe": true, "listChanged": true }, "tools": { "listChanged": true }, "prompts": { "listChanged": true } } } ``` ### Protocol Compliance Standards **JSON-RPC 2.0 is non-negotiable** - all messages must be UTF-8 encoded with exact "2.0" protocol version. The specification mandates three message types: Requests (with unique IDs), Responses (success or error), and Notifications (one-way messages). Error handling requires standard JSON-RPC codes (-32700 through -32603) plus MCP-specific extensions like -32001 for timeouts. Custom error codes must fall outside the reserved range. ### Transport Layer Requirements MCP supports two primary transport mechanisms: 1. **STDIO Transport** (mandatory for local servers): Newline-delimited JSON via stdin/stdout 2. **Streamable HTTP Transport** (for remote servers): Unified endpoint supporting POST/GET with SSE HTTP transports require Origin header validation to prevent DNS rebinding attacks, while STDIO implementations should bind only to localhost (127.0.0.1). ## MCP client integration patterns ### Client-Host-Server Architecture The protocol establishes clear separation of concerns: - **Hosts**: AI applications managing multiple client connections - **Clients**: Protocol handlers maintaining 1:1 server connections - **Servers**: Lightweight programs exposing specific capabilities Clients must implement proper lifecycle management, starting with initialization handshake where they declare their capabilities and negotiate features with servers. The initialization sequence is strictly ordered: request → response → initialized notification. ### Authentication Framework **OAuth 2.1 is mandatory for HTTP transports**, with PKCE required for all clients. The specification mandates: - Authorization headers for every HTTP request (never query strings) - Short-lived access tokens with rotation for public clients - Audience-restricted tokens to prevent confused deputy attacks - Dynamic client registration support (RFC7591) recommended For STDIO transports, authentication typically uses environment variables rather than OAuth flows. ### Security Requirements MCP enforces comprehensive security measures: - **HTTPS mandatory** for all authorization endpoints - **Origin validation** required for SSE connections - **User consent** required before any tool execution - **Token audience validation** preventing passthrough vulnerabilities - **Session IDs** must be cryptographically secure, visible ASCII only ## TypeScript implementation guidelines ### SDK Architecture The official TypeScript SDK (`@modelcontextprotocol/sdk`) requires Node.js 18+ and provides type-safe server implementation: ```typescript import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const server = new McpServer({ name: "educational-content-server", version: "1.0.0" }); ``` ### Type Safety with Zod The SDK leverages Zod for runtime type validation, essential for tool parameter schemas: ```typescript server.tool( "search-content", { query: z.string().describe("Search query"), category: z.enum(["lesson", "exercise", "reference"]).optional(), difficulty: z.enum(["beginner", "intermediate", "advanced"]).optional() }, async (params) => { /* implementation */ } ); ``` ### Resource Templates Dynamic content exposure uses URI templates following RFC 6570: ```typescript server.resource( "course-content", new ResourceTemplate("course://{courseId}/module/{moduleId}/lesson/{lessonId}", { list: ["courseId", "moduleId"] }), async (uri, params) => { /* hierarchical content handler */ } ); ``` ## Interface design standards ### Required Method Signatures All MCP servers must implement standard request handlers: - `initialize(params)`: Protocol handshake and capability exchange - `list_resources()`, `read_resource(uri)`: Resource management - `list_tools()`, `call_tool(name, arguments)`: Tool execution - `list_prompts()`, `get_prompt(name, arguments)`: Prompt handling ### Data Structure Requirements Resources must include: ```typescript interface Resource { uri: string; // Unique identifier name: string; // Human-readable name mimeType?: string; // Optional MIME type description?: string; } ``` Tools require JSON Schema input definitions: ```typescript interface Tool { name: string; description: string; inputSchema: { type: "object"; properties: Record<string, any>; required?: string[]; }; } ``` ## Protocol communication standards ### Message Format Specifications Every message follows strict JSON-RPC 2.0 format with MCP extensions: - Request IDs must be unique strings or numbers - Responses must echo request IDs exactly - Notifications omit ID fields entirely - Progress notifications use dedicated `progressToken` parameters ### Session Management Servers may implement session tracking via `Mcp-Session-Id` headers: - Must be globally unique and cryptographically secure - Limited to visible ASCII characters (0x21-0x7E) - Servers can terminate sessions anytime with 404 responses ### Performance Constraints While no explicit message size limits exist, implementations should: - Default to 60-second request timeouts - Reset timeouts on progress notifications - Implement exponential backoff for retries - Consider transport-specific limitations ## Educational content integration patterns ### Content Hierarchy Patterns Educational servers should leverage MCP's resource system for hierarchical content: ```typescript // Multi-level educational structure new ResourceTemplate("edu://{subject}/{grade}/unit/{unitId}/lesson/{lessonId}") ``` This enables natural navigation through curricula while maintaining clean URI structures. ### Pagination Implementation For large content collections, implement cursor-based pagination: ```typescript server.tool("list-courses", { page: z.number().min(1).default(1), pageSize: z.number().min(1).max(100).default(20) }, async ({ page, pageSize }) => { // Return paginated results with metadata }); ``` ### Content Versioning Educational content requires version tracking: - Expose version history through dedicated tools - Include timestamps and changelogs in metadata - Support rollback through version-specific URIs ### Metadata Standards Rich metadata enhances educational content discovery: ```typescript interface EducationalMetadata { difficulty: "beginner" | "intermediate" | "advanced"; prerequisites: string[]; estimatedDuration: number; tags: string[]; language: string; author: { name: string; email?: string; }; } ``` ## Compliance gap analysis framework When comparing existing implementations to MCP specifications, evaluate: ### Protocol Compliance - **JSON-RPC 2.0 adherence**: Exact message format matching - **Lifecycle implementation**: Proper initialization/shutdown sequences - **Error code usage**: Standard codes for standard scenarios ### Security Compliance - **OAuth 2.1 implementation**: Full framework for HTTP transports - **Token handling**: No query strings, proper headers only - **Origin validation**: Mandatory for SSE connections - **User consent flows**: Explicit approval before tool execution ### Feature Compliance - **Capability declaration**: Accurate capability advertisement - **Resource URI patterns**: RFC 6570 template compliance - **Tool parameter validation**: Zod schemas for all inputs - **Progress reporting**: Proper notification patterns ### TypeScript-Specific Compliance - **Type safety**: Full TypeScript with strict mode - **SDK usage**: Leverage official SDK patterns - **Error handling**: Typed error responses - **Async patterns**: Proper Promise/async-await usage ## Implementation modification recommendations To ensure full MCP compliance for educational content servers: ### Immediate Requirements 1. **Implement proper initialization handshake** with capability negotiation 2. **Adopt JSON-RPC 2.0 exactly** - no custom message formats 3. **Add OAuth 2.1 support** for HTTP transport variants 4. **Validate all inputs** using Zod schemas ### Architectural Modifications 1. **Separate transport from protocol logic** for flexibility 2. **Implement stateful session management** with secure IDs 3. **Add subscription support** for real-time content updates 4. **Create hierarchical URI templates** for course structures ### Security Enhancements 1. **Enforce HTTPS** for all network communications 2. **Implement token audience validation** preventing confused deputy 3. **Add comprehensive audit logging** for security events 4. **Rate limit all endpoints** preventing abuse ### Educational-Specific Patterns 1. **Design content-aware URI schemes** (edu://, course://, lesson://) 2. **Implement semantic search tools** leveraging content metadata 3. **Add progress tracking resources** for student advancement 4. **Create collaborative prompt templates** for guided learning This comprehensive analysis provides the foundation for building fully compliant MCP educational content servers that leverage the protocol's strengths while maintaining security and usability standards defined by Anthropic's official specifications.