example async mcp

Local 2025-09-01 00:32:51 0

Developer Tools @ViezeVingertjes/example-async-mcp

This server implements the Model Context Protocol (MCP) to handle asynchronous tasks with real-time status tracking, robust error handling, and automatic resource management.

? 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 Smithery

To install Async MCP Server for Claude Desktop automatically via Smithery:

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

Installation

# Clone the repository
git clone https://github.com/ViezeVingertjes/example-async-mcp.git

# 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

[
  {
    "description": "Start processing a task asynchronously.",
    "inputSchema": {
      "properties": {
        "delayMs": {
          "default": 5000,
          "description": "Optional delay in milliseconds to simulate processing time",
          "type": "number"
        },
        "input": {
          "description": "The input to process",
          "type": "string"
        },
        "timeoutMs": {
          "default": 30000,
          "description": "Optional timeout in milliseconds",
          "type": "number"
        }
      },
      "required": [
        "input"
      ],
      "type": "object"
    },
    "name": "process_task"
  },
  {
    "description": "Check the status of an async task",
    "inputSchema": {
      "properties": {
        "taskId": {
          "description": "The task ID returned by process_task",
          "type": "string"
        }
      },
      "required": [
        "taskId"
      ],
      "type": "object"
    },
    "name": "check_task_status"
  }
]