Task API Server - MCP TypeScript Implementation

Task API Server - MCP TypeScript 実装

TypeScript で記述された Task Management API 向けの Model Context Protocol（MCP）実装です。このプロジェクトは、リファレンス実装であると同時に、実際に利用できるタスク管理サーバーとして機能します。

概要

この MCP サーバーは外部の Task API サービスに接続し、タスク管理のための標準化されたインターフェースを提供します。次の 2 つの実行モードに対応しています。

1. STDIO モード：CLI ベースのアプリケーションや AI エージェント向けの標準入出力通信
2. HTTP+SSE モード：ブラウザーや HTTP ベースのクライアント向けの、Server-Sent Events を使用するウェブアクセス可能なサーバー

このサーバーは、包括的なタスク管理操作、幅広い検証、堅牢なエラー処理を提供します。

機能

• タスク管理操作：

  • フィルタリング機能を使って既存のタスクを一覧表示
  • カスタマイズ可能なプロパティを指定して新しいタスクを作成
  • タスクの詳細（説明、ステータス、カテゴリー、優先度）を更新
  • 完了したタスクや不要になったタスクを削除

• 2 種類のインターフェースモード：

  • コマンドラインおよび AI エージェントとの連携向けの STDIO プロトコル対応
  • ブラウザーベースでアクセスできるウェブインターフェースを備えた HTTP+SSE プロトコル

• MCP プロトコルの実装：

  • Model Context Protocol の完全な実装
  • タスクデータ構造のリソース
  • タスク操作用のツール
  • エラー処理とわかりやすいメッセージ

• 品質保証：

  • 検証用の包括的なテストクライアント
  • テスト完了後のサーバーの自動シャットダウン
  • API レスポンスの詳細な検証

はじめに

前提条件

• Node.js 16.x 以降
• npm または pnpm パッケージマネージャー

インストール

1. リポジトリをクローンします。

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

2. 依存関係をインストールします。

   npm install
   

   または pnpm を使用します。

   pnpm install
   

3. Task API の認証情報を含む .env ファイルを作成します。

   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. プロジェクトをビルドします。

   npm run build
   

サーバーの起動

STDIO モード（CLI／AI 連携向け）

npm start

または

node dist/index.js

HTTP モード（ウェブアクセス向け）

npm run start:http

または

node dist/http-server.js

デフォルトでは、HTTP サーバーはポート 3000 で起動します。TASK_MANAGER_HTTP_PORT 環境変数を設定すると、ポートを変更できます。

テスト

包括的なテストスイートを実行して、機能を検証します。

npm test

次の処理が行われます。

1. プロジェクトをビルドします
2. サーバーインスタンスを起動します
3. テストクライアントをサーバーに接続します
4. すべてのタスク操作を実行します
5. 正しいレスポンスが返されることを検証します
6. サーバーを自動的にシャットダウンします

MCP クライアントの使用

STDIO クライアント

アプリケーションから STDIO サーバーに接続するには、次のようにします。

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 クライアント

ブラウザーから HTTP サーバーに接続するには、次のようにします。

<!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>
  
</body>
</html>

利用可能なツール

listTasks

利用可能なすべてのタスクを一覧表示します。

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

新しいタスクを作成します。

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

既存のタスクを更新します。

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

タスクを削除します。

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

環境変数

変数	説明	デフォルト
TASK_MANAGER_API_BASE_URL	外部 Task API の URL	なし（必須）
TASK_MANAGER_API_KEY	認証用の API キー	なし（必須）
TASK_MANAGER_HTTP_PORT	HTTP サーバーのポート	3000
PORT	代替のポート名（こちらが優先されます）	なし

プロジェクト構成

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

開発

1. TypeScript コンパイラーをウォッチモードで起動します。

   npm run watch
   

2. テストを実行して変更を検証します。

   npm test
   

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。

謝辞

• このプロジェクトでは、MCP プロトコルの実装に @modelcontextprotocol/sdk を使用しています
• AI ツールやウェブアプリケーションとの連携を目的として構築されています