trackmcp
Back to directory
milkosten

task-mcp-server

View on GitHub

A MCP Task Server

10 stars JavaScriptServers & Infrastructure Updated Sep 19, 2025

Documentation

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:

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

2. Install dependencies:

code
npm install

or using pnpm:

code
pnpm install

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

code
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:

code
npm run build

Running the Server

STDIO Mode (for CLI/AI integration)

code
npm start

or

code
node dist/index.js

HTTP Mode (for web access)

code
npm run start:http

or

code
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:

code
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:

typescript
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:

html
Task Manager
  
    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
    });
  

  Task Manager

Available Tools

listTasks

Lists all available tasks.

typescript
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.

typescript
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.

typescript
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.

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

Environment Variables

VariableDescriptionDefault
TASK_MANAGER_API_BASE_URLURL for the external Task APINone (Required)
TASK_MANAGER_API_KEYAPI key for authenticationNone (Required)
TASK_MANAGER_HTTP_PORTPort for the HTTP server3000
PORTAlternative port name (takes precedence)None

Project Structure

code
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:

code
npm run watch

2. Run tests to verify changes:

code
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

Frequently asked questions

What is task-mcp-server?

task-mcp-server is A MCP Task Server

How do I install task-mcp-server?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is task-mcp-server open source?

Yes — it is hosted on GitHub at https://github.com/milkosten/task-mcp-server and has 10 stars.

Related MCP tools

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP