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

Model Context Protocol TypeScript SDK

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

TypeScript implementation for building MCP servers and clients. Enables exposing context (resources, tools, prompts) to LLMs with transports, OAuth, sampling, and elicitation.

Package: @modelcontextprotocol/sdk@1.20.2 | npm install @modelcontextprotocol/sdk | Protocol: 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07

Quick Start

Server:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

server.registerTool('add', {
  title: 'Addition Tool',
  description: 'Add two numbers',
  inputSchema: { a: z.number(), b: z.number() },
  outputSchema: { result: z.number() }
}, async ({ a, b }) => ({
  content: [{ type: 'text', text: String(a + b) }],
  structuredContent: { result: a + b }
}));

await server.connect(new StdioServerTransport());

Client:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(new StdioClientTransport({ command: 'node', args: ['server.js'] }));

const { tools } = await client.listTools();
const result = await client.callTool({ name: 'add', arguments: { a: 5, b: 3 } });
console.log(result.structuredContent); // { result: 8 }

Core Concepts

Server Primitives:

Primitive	Purpose	Control	Use Case
Tools	Model actions	Model	Computations, APIs, side effects
Resources	App data	App	Config, files, data
Prompts	Templates	User	Slash commands, starters

Transports:

Transport	Use Case	Characteristics
Stdio	Local/CLI	Simple, fast
StreamableHTTP	Remote/web	Stateless, scalable
WebSocket	Real-time	Low latency
InMemory	Testing	Isolated

Common Patterns

File System Server

import fs from 'fs/promises';

server.registerResource('readme', 'file:///project/README.md', {
  title: 'Project README', mimeType: 'text/markdown'
}, async (uri) => ({
  contents: [{ uri: uri.href, mimeType: 'text/markdown', text: await fs.readFile('/project/README.md', 'utf-8') }]
}));

server.registerTool('list-files', {
  description: 'List files in a directory',
  inputSchema: { path: z.string() }
}, async ({ path }) => ({
  content: [{ type: 'text', text: (await fs.readdir(path)).join('\n') }]
}));

API Integration Server

server.registerTool('fetch-api', {
  description: 'Fetch from external API',
  inputSchema: { url: z.string().url(), method: z.enum(['GET', 'POST']).optional() }
}, async ({ url, method = 'GET' }) => {
  const response = await fetch(url, { method });
  const data = await response.json();
  return { content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: data };
});

Database Server

import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';

server.registerResource('user', new ResourceTemplate('db://users/{userId}', {}), {
  title: 'User Profile'
}, async (uri, { userId }) => {
  const user = await db.getUser(userId);
  return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(user) }] };
});

server.registerTool('query-users', {
  description: 'Query users by criteria',
  inputSchema: { role: z.string().optional(), active: z.boolean().optional() }
}, async (args) => {
  const users = await db.queryUsers(args);
  return {
    content: users.map(u => ({ type: 'text', text: `${u.name} (${u.email})` })),
    structuredContent: { users }
  };
});

API Reference

Server Tools - Register model-controlled actions with validation
Server Resources - Expose application data (static & dynamic)
Server Prompts - Reusable conversation templates
Server Advanced - Sampling, elicitation, dynamic capabilities
Client API - Consume server capabilities
Transports - Communication protocols (Stdio, HTTP, WebSocket)
Authentication - OAuth 2.0 implementation
Types - TypeScript type definitions

Critical Patterns

Validation with Zod

server.registerTool('safe-add', {
  inputSchema: { a: z.number().min(0).max(1000), b: z.number().min(0).max(1000) },
  outputSchema: { result: z.number() }
}, async ({ a, b }) => ({
  content: [{ type: 'text', text: String(a + b) }],
  structuredContent: { result: a + b }
}));

Structured Output (Required when outputSchema defined)

return {
  content: [{ type: 'text', text: JSON.stringify(output) }],
  structuredContent: output // Must match outputSchema
};

Error Handling

try {
  const result = await performOperation(id);
  return { content: [{ type: 'text', text: `Success: ${result}` }], structuredContent: { success: true, result } };
} catch (error) {
  return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
}

Common Issues

Tools not appearing: Call server.connect() after registration; verify client capabilities. Transport errors: Verify server is listening; check URLs/credentials. Validation errors: Ensure Zod schemas match; structuredContent must match outputSchema.

Essential Imports

// Server
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport, StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Client
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Types
import type { Tool, Resource, Prompt, CallToolResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';

// Error handling
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
throw new McpError(ErrorCode.InvalidParams, 'Message', { field: 'value' });

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:npm/@modelcontextprotocol/sdk@1.20.x
Publish Source: CLI
Badge