Task API Server

Task API Server

A Model Context Protocol implementation that provides a standardized interface for task management, supporting both STDIO mode for CLI/AI applications and HTTP+SSE mode for browser-based clients.

milkosten

Developer Tools
Browser Automation
JavaScript
Visit Server

Tools

listTasks

createTask

updateTask

deleteTask

README

Task API Server - MCP TypeScript Implementation

A Model Context Protocol (MCP) implementation for Task Management API written in TypeScript. This project serves as both a reference implementation and a functional task management server.

Overview

This MCP server connects to an external Task API service and provides a standardized interface for task management. It supports two runtime modes:

  1. STDIO Mode: Standard input/output communication for CLI-based applications and AI agents
  2. HTTP+SSE Mode: Web-accessible server with Server-Sent Events for browser and HTTP-based clients

The server offers a complete set of task management operations, extensive validation, and robust error handling.

Features

  • Task Management Operations:

    • List existing tasks with filtering capabilities
    • Create new tasks with customizable properties
    • Update task details (description, status, category, priority)
    • Delete tasks when completed or no longer needed

  • Dual Interface Modes:

    • STDIO protocol support for command-line and AI agent integration
    • HTTP+SSE protocol with web interface for browser-based access

  • MCP Protocol Implementation:

    • Complete implementation of the Model Context Protocol
    • Resources for task data structures
    • Tools for task operations
    • Error handling and informative messages

  • Quality Assurance:

    • Comprehensive test client for validation
    • Automatic server shutdown after tests complete
    • Detailed validation of API responses

Getting Started

Prerequisites

  • Node.js 16.x or higher
  • npm or pnpm package manager

Installation

  1. Clone the repository:

    git clone https://github.com/yourusername/mcp-template-ts.git
cd mcp-template-ts

  2. Install dependencies:

    npm install

    or using pnpm:

    pnpm install

  3. Create an .env file with your Task API credentials:

    TASK_MANAGER_API_BASE_URL=https://your-task-api-url.com/api
TASK_MANAGER_API_KEY=your_api_key_here
TASK_MANAGER_HTTP_PORT=3000

  4. Build the project:

    npm run build

Running the Server

STDIO Mode (for CLI/AI integration)

npm start

or

node dist/index.js

HTTP Mode (for web access)

npm run start:http

or

node dist/http-server.js

By default, the HTTP server runs on port 3000. You can change this by setting the TASK_MANAGER_HTTP_PORT environment variable.

Testing

Run the comprehensive test suite to verify functionality:

npm test

This will:

  1. Build the project
  2. Start a server instance
  3. Connect a test client to the server
  4. Run through all task operations
  5. Verify correct responses
  6. Automatically shut down the server

Using the MCP Client

STDIO Client

To connect to the STDIO server from your application:

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

// Create transport
const transport = new StdioClientTransport({
  command: 'node',
  args: [path.resolve('path/to/dist/index.js')]
});

// Initialize client
const client = new Client(
  {
    name: "your-client-name",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

// Connect to server
await client.connect(transport);

// Example: List all tasks
const listTasksResult = await client.callTool({
  name: "listTasks",
  arguments: {}
});

// Example: Create a new task
const createTaskResult = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete project documentation",
    category: "Documentation",
    priority: "high"
  }
});

// Clean up when done
await client.close();

HTTP Client

To connect to the HTTP server from a browser:

<!DOCTYPE html>
<html>
<head>
  <title>Task Manager</title>
  <script type="module">
    import { Client } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/index.js';
    import { SSEClientTransport } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/sse.js';

    document.addEventListener('DOMContentLoaded', async () => {
      // Create transport
      const transport = new SSEClientTransport('http://localhost:3000/mcp');
      
      // Initialize client
      const client = new Client(
        {
          name: "browser-client",
          version: "1.0.0"
        },
        {
          capabilities: {
            prompts: {},
            resources: {},
            tools: {}
          }
        }
      );

      // Connect to server
      await client.connect(transport);
      
      // Now you can use client.callTool() for tasks
    });
  </script>
</head>
<body>
  <h1>Task Manager</h1>
  <!-- Your interface elements here -->
</body>
</html>

Available Tools

listTasks

Lists all available tasks.

const result = await client.callTool({
  name: "listTasks",
  arguments: {
    // Optional filters
    status: "pending", // Filter by status
    category: "Work",  // Filter by category
    priority: "high"   // Filter by priority
  }
});

createTask

Creates a new task.

const result = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete the project report",  // Required: task description
    category: "Work",                     // Optional: task category
    priority: "high"                      // Optional: low, medium, high
  }
});

updateTask

Updates an existing task.

const result = await client.callTool({
  name: "updateTask",
  arguments: {
    taskId: 123,                       // Required: ID of task to update
    task: "Updated task description",  // Optional: new description
    status: "done",                    // Optional: pending, started, done
    category: "Personal",              // Optional: new category
    priority: "medium"                 // Optional: low, medium, high
  }
});

deleteTask

Deletes a task.

const result = await client.callTool({
  name: "deleteTask",
  arguments: {
    taskId: 123  // Required: ID of task to delete
  }
});

Environment Variables

Variable Description Default
TASK_MANAGER_API_BASE_URL URL for the external Task API None (Required)
TASK_MANAGER_API_KEY API key for authentication None (Required)
TASK_MANAGER_HTTP_PORT Port for the HTTP server 3000
PORT Alternative port name (takes precedence) None

Project Structure

mcp-template-ts/
├── dist/               # Compiled JavaScript files
├── src/                # TypeScript source files
│   ├── index.ts        # STDIO server entry point
│   ├── http-server.ts  # HTTP+SSE server entry point
│   ├── test-client.ts  # Test client implementation
├── .env                # Environment variables
├── package.json        # Project dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation

Development

  1. Start the TypeScript compiler in watch mode:

    npm run watch

  2. Run tests to verify changes:

    npm test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • This project uses the @modelcontextprotocol/sdk for MCP protocol implementation
  • Built for integration with AI tooling and web applications

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Playwright MCP Server

Playwright MCP Server

Provides a server utilizing Model Context Protocol to enable human-like browser automation with Playwright, allowing control over browser actions such as navigation, element interaction, and scrolling.

Featured
Local
TypeScript
MCP Package Docs Server

MCP Package Docs Server

Facilitates LLMs to efficiently access and fetch structured documentation for packages in Go, Python, and NPM, enhancing software development with multi-language support and performance optimization.

Featured
Local
TypeScript
@kazuph/mcp-fetch

@kazuph/mcp-fetch

Model Context Protocol server for fetching web content and processing images. This allows Claude Desktop (or any MCP client) to fetch web content and handle images appropriately.

Featured
Local
JavaScript
Claude Code MCP

Claude Code MCP

An implementation of Claude Code as a Model Context Protocol server that enables using Claude's software engineering capabilities (code generation, editing, reviewing, and file operations) through the standardized MCP interface.

Featured
Local
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

Model Context Protocol server for Task Management. This allows Claude Desktop (or any MCP client) to manage and execute tasks in a queue-based system.

Featured
Local
JavaScript
DuckDuckGo MCP Server

DuckDuckGo MCP Server

A Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.

Featured
Python
Linear MCP Server

Linear MCP Server

Enables interaction with Linear's API for managing issues, teams, and projects programmatically through the Model Context Protocol.

Featured
JavaScript
Supabase MCP Server

Supabase MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to the Supabase Management API. This server allows AI models and other clients to manage Supabase projects and organizations through a standardized interface.

Featured
JavaScript