tessl/npm-modelcontextprotocol--sdk

TypeScript SDK for implementing the Model Context Protocol, enabling developers to build MCP servers and clients with support for multiple transports, tools, resources, prompts, and authentication

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Type System Reference

Name: tessl/npm-modelcontextprotocol--sdk
Author: tessl

Complete type definitions for the MCP protocol.

Core Protocol Types

JSON-RPC Base

const JSONRPC_VERSION = '2.0';

type RequestId = string | number;
type ProgressToken = string | number;
type Cursor = string;

interface Request {
  method: string;
  params?: { _meta?: { progressToken?: ProgressToken; }; [key: string]: unknown; };
}

interface Notification {
  method: string;
  params?: { _meta?: Record<string, unknown>; [key: string]: unknown; };
}

interface Result {
  _meta?: Record<string, unknown>;
  [key: string]: unknown;
}

interface JSONRPCRequest extends Request { jsonrpc: '2.0'; id: RequestId; }
interface JSONRPCNotification extends Notification { jsonrpc: '2.0'; }
interface JSONRPCResponse { jsonrpc: '2.0'; id: RequestId; result: Result; }
interface JSONRPCError {
  jsonrpc: '2.0';
  id: RequestId;
  error: { code: number; message: string; data?: unknown; };
}

type JSONRPCMessage = JSONRPCRequest | JSONRPCNotification | JSONRPCResponse | JSONRPCError;

Protocol Version

const LATEST_PROTOCOL_VERSION = '2025-06-18';
const DEFAULT_NEGOTIATED_PROTOCOL_VERSION = '2025-03-26';
const SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07'];

Error Codes

enum ErrorCode {
  ConnectionClosed = -32000,
  RequestTimeout = -32001,
  ParseError = -32700,
  InvalidRequest = -32600,
  MethodNotFound = -32601,
  InvalidParams = -32602,
  InternalError = -32603
}

class McpError extends Error {
  code: number;
  data?: unknown;
  constructor(code: number, message: string, data?: unknown);
}

Implementation Info

interface Implementation {
  name: string;
  version: string;
}

Capabilities

interface ServerCapabilities {
  prompts?: { listChanged?: boolean; };
  resources?: { subscribe?: boolean; listChanged?: boolean; };
  tools?: { listChanged?: boolean; };
  logging?: {};
  completions?: {};
  sampling?: {};
  elicitation?: {};
}

interface ClientCapabilities {
  sampling?: {};
  elicitation?: {};
  roots?: { listChanged?: boolean; };
}

Content Types

interface TextContent {
  type: 'text';
  text: string;
  annotations?: { audience?: ('user' | 'assistant')[]; priority?: number; };
}

interface ImageContent {
  type: 'image';
  data: string;           // Base64 or data URI
  mimeType: string;
}

interface AudioContent {
  type: 'audio';
  data: string;           // Base64
  mimeType: string;
}

interface EmbeddedResource {
  type: 'resource';
  resource: { uri: string; mimeType?: string; text?: string; blob?: string; };
}

interface ResourceLink {
  type: 'resource_link';
  name: string;
  title?: string;
  uri: string;
  description?: string;
  mimeType?: string;
  icons?: Icon[];
  _meta?: Record<string, unknown>;
}

type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink;

Metadata Types

interface Icon {
  src: string;
  mimeType?: string;
  sizes?: string[];       // WxH format (e.g., "48x48", "96x96") or "any"
}

interface Icons {
  icons?: Icon[];
}

interface BaseMetadata {
  name: string;           // Required: programmatic/logical identifier
  title?: string;         // Optional: human-readable display name
}

Tool Types

interface Tool extends BaseMetadata {
  name: string;
  inputSchema: JSONSchema;
  outputSchema?: JSONSchema;
  annotations?: ToolAnnotations;
  _meta?: Record<string, unknown>;
}

interface ToolAnnotations {
  audience?: ('user' | 'assistant')[];
  [key: string]: unknown;
}

interface CallToolResult {
  content: ContentBlock[];
  isError?: boolean;
  structuredContent?: Record<string, unknown>;
  _meta?: Record<string, unknown>;
}

interface ListToolsResult {
  tools: Tool[];
  nextCursor?: string;
}

Resource Types

interface Resource extends BaseMetadata {
  uri: string;
  name: string;
  mimeType?: string;
  _meta?: Record<string, unknown>;
}

interface ResourceTemplate extends BaseMetadata {
  uriTemplate: string;
  name: string;
  mimeType?: string;
  _meta?: Record<string, unknown>;
}

interface TextResourceContents {
  uri: string;
  mimeType?: string;
  text: string;
}

interface BlobResourceContents {
  uri: string;
  mimeType?: string;
  blob: string;           // Base64 encoded
}

type ResourceContents = TextResourceContents | BlobResourceContents;

interface ReadResourceResult {
  contents: ResourceContents[];
  _meta?: Record<string, unknown>;
}

interface ListResourcesResult {
  resources: Resource[];
  nextCursor?: string;
}

interface ListResourceTemplatesResult {
  resourceTemplates: ResourceTemplate[];
  nextCursor?: string;
}

Prompt Types

interface Prompt extends BaseMetadata {
  name: string;
  arguments?: PromptArgument[];
  _meta?: Record<string, unknown>;
}

interface PromptArgument {
  name: string;
  description?: string;
  required?: boolean;
}

interface PromptMessage {
  role: 'user' | 'assistant';
  content: TextContent | ImageContent | AudioContent | EmbeddedResource;
}

interface GetPromptResult {
  description?: string;
  messages: PromptMessage[];
  _meta?: Record<string, unknown>;
}

interface ListPromptsResult {
  prompts: Prompt[];
  nextCursor?: string;
}

Sampling Types

interface SamplingMessage {
  role: 'user' | 'assistant';
  content: TextContent | ImageContent | AudioContent;
}

interface ModelHint {
  name?: string;
}

interface ModelPreferences {
  hints?: ModelHint[];
  costPriority?: number;            // 0-1
  speedPriority?: number;           // 0-1
  intelligencePriority?: number;    // 0-1
}

interface CreateMessageResult {
  role: 'assistant';
  content: TextContent | ImageContent | AudioContent;
  model: string;
  stopReason?: 'endTurn' | 'stopSequence' | 'maxTokens';
  _meta?: Record<string, unknown>;
}

Elicitation Types

interface ElicitResult {
  action: 'accept' | 'decline' | 'cancel';
  content?: Record<string, unknown>;
  _meta?: Record<string, unknown>;
}

Completion Types

interface PromptReference {
  type: 'ref/prompt';
  name: string;
}

interface ResourceTemplateReference {
  type: 'ref/resource';
  uri: string;
}

interface CompleteResult {
  completion: { values: string[]; total?: number; hasMore?: boolean; };
  _meta?: Record<string, unknown>;
}

Logging Types

type LoggingLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';

Root Types

interface Root {
  uri: string;
  name: string;
}

interface ListRootsResult {
  roots: Root[];
  _meta?: Record<string, unknown>;
}

Progress and Cancellation

interface Progress {
  progress: number;
  total?: number;
}

interface ProgressNotification {
  method: 'notifications/progress';
  params: { progressToken: ProgressToken; progress: number; total?: number; };
}

interface CancelledNotification {
  method: 'notifications/cancelled';
  params: { requestId: RequestId; reason?: string; };
}

Utility Types

interface PaginatedRequest {
  cursor?: string;
}

interface PaginatedResult {
  nextCursor?: string;
}

type EmptyResult = Record<string, never>;

interface RequestInfo {
  headers?: Record<string, string | string[]>;
}

interface AuthInfo {
  token: string;
  clientId: string;
  scopes: string[];
  userId?: string;
  expiresAt?: number;
}

interface RequestMeta {
  progressToken?: ProgressToken;
  [key: string]: unknown;
}

type FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>;

interface TransportSendOptions {
  priority?: number;
  [key: string]: unknown;
}

interface JSONSchema {
  type?: string | string[];
  properties?: Record<string, JSONSchema>;
  items?: JSONSchema | JSONSchema[];
  required?: string[];
  enum?: unknown[];
  enumNames?: string[];
  const?: unknown;
  title?: string;
  description?: string;
  default?: unknown;
  examples?: unknown[];
  [key: string]: unknown;
}

Type Guards

function isJSONRPCRequest(value: unknown): value is JSONRPCRequest;
function isJSONRPCNotification(value: unknown): value is JSONRPCNotification;
function isJSONRPCResponse(value: unknown): value is JSONRPCResponse;
function isJSONRPCError(value: unknown): value is JSONRPCError;