MCP Fundamentals & Version Boundaries

// A request/response teaching fixture pinned to MCP 2026-07-28.
// Not a complete server/client, transport, authentication or conformance implementation.
export const protocolVersion = '2026-07-28';
export function toolRequest(id, planId) {
  if (!Number.isSafeInteger(id) || id < 1) throw new Error('Invalid request ID');
  return {
    jsonrpc: '2.0', id, method: 'tools/call',
    params: {
      name: 'readPlan', arguments: { planId },
      _meta: {
        'io.modelcontextprotocol/protocolVersion': protocolVersion,
        'io.modelcontextprotocol/clientInfo': { name: 'teaching-host', version: '1.0.0' },
        'io.modelcontextprotocol/clientCapabilities': {},
      },
    },
  };
}
export function fixtureReply(request, trustedTenant) {
  const fail = (code, message, data) => ({ jsonrpc: '2.0', id: request.id, error: { code, message, ...(data ? { data } : {}) } });
  const meta = request.params?._meta;
  if (request.jsonrpc !== '2.0' || request.id == null || !meta ||
      !meta['io.modelcontextprotocol/protocolVersion'] || !meta['io.modelcontextprotocol/clientCapabilities']) {
    return fail(-32602, 'Invalid params');
  }
  if (meta['io.modelcontextprotocol/protocolVersion'] !== protocolVersion) {
    return fail(-32022, 'Unsupported protocol version', { supported: [protocolVersion], requested: meta['io.modelcontextprotocol/protocolVersion'] });
  }
  if (request.method !== 'tools/call') return fail(-32601, 'Method not found');
  const { name, arguments: args } = request.params;
  if (name !== 'readPlan' || !args || Object.keys(args).join(',') !== 'planId' ||
      typeof args.planId !== 'string' || !/^PLAN-\d+$/.test(args.planId)) return fail(-32602, 'Invalid params');
  // Tenant comes from the host's configured credential boundary, never clientInfo or tool arguments.
  const authorized = trustedTenant === 'tenant-a' && args.planId === 'PLAN-1';
  return { jsonrpc: '2.0', id: request.id, result: {
    resultType: 'complete', isError: !authorized,
    content: [{ type: 'text', text: authorized ? 'IN_PROGRESS' : 'Forbidden' }],
  } };
}
export function validateCorrelation(request, response) {
  if (response.jsonrpc !== '2.0' || response.id !== request.id) throw new Error('Uncorrelated response');
  if (Object.hasOwn(response, 'result') === Object.hasOwn(response, 'error')) throw new Error('Ambiguous response');
  return response;
}