Example Async MCP

TypeScript Node.js License: MIT PRs Welcome

🚀 A high-performance Model Context Protocol (MCP) server implementation showcasing asynchronous task processing with robust status tracking and error handling. Built with TypeScript • Powered by Node.js • MCP Protocol

✨ Features

• 🔄 Asynchronous Task Processing - Handle long-running operations efficiently
• 📊 Real-time Status Tracking - Monitor task progress with polling support
• 🧹 Automatic Resource Management - Smart task cleanup and memory management
• ⏱️ Timeout Handling - Configurable timeouts for tasks
• 🛡️ Robust Error Handling - Custom error types and comprehensive error reporting
• 📝 TypeScript Support - Full type safety and modern JavaScript features
• 🔍 Built-in Inspector - Debug and test your MCP server with ease

🚀 Quick Start

Prerequisites

• Node.js 20.x or higher
• npm 9.x or higher

Installing via

To install Async MCP Server for Claude Desktop automatically via :

npx -y @/cli install @ViezeVingertjes/example-async-mcp --client claude

Installation

# Clone the repository
git clone 
# Navigate to the project directory
cd example-async-mcp
# Install dependencies
npm install
# Build the project
npm run build

Running the Server

npm start

Using the Inspector

npm run inspector

📖 API Reference

Available Tools

process_task

Creates a new asynchronous task.

 "name": "process_task",
 "arguments": {
 "input": "Hello, World!",
 "delayMs": 5000,
 "timeoutMs": 30000

| Parameter | Type | Required | Default | Description | | input | string | ✅ | - | The input string to process | | delayMs | number | ❌ | 5000 | Processing delay in milliseconds | | timeoutMs | number | ❌ | 30000 | Task timeout in milliseconds |

check_task_status

Check the status of an existing task.

 "name": "check_task_status",
 "arguments": {
 "taskId": "550e8400-e29b-41d4-a716-446655440000"

| Parameter | Type | Required | Description | | taskId | string | ✅ | The ID of the task to check |

Task States

| Status | Description | | 🕒 pending | Task created but not started | | ⚡ processing | Task is being processed | | ✅ complete | Task completed successfully | | ❌ error | Task failed |

⚙️ Configuration

Key configuration options in src/constants.ts:

export const DEFAULT_TASK_TIMEOUT_MS = 30000; // 30 seconds
export const DEFAULT_TASK_DELAY_MS = 5000; // 5 seconds
export const DEFAULT_POLL_DELAY_MS = 10000; // 10 seconds
export const POLL_INTERVAL_MS = 100; // 100ms
export const MAX_TASKS = 1000; // Maximum concurrent tasks

🛠️ Development

Project Structure

src/
├── index.ts # Main server implementation
├── types.ts # TypeScript types and interfaces
├── constants.ts # Configuration constants
└── utils.ts # Utility functions

Development Commands

# Build the project
npm run build
# Watch for changes
npm run watch
# Run tests
npm test
# Run inspector
npm run inspector

📝 License

This project is licensed under the MIT License - see the LICENSE file for details. Made with ❤️ by the MCP community