タスク API サーバー - MCP TypeScript 実装

TypeScriptで記述されたタスク管理APIのモデルコンテキストプロトコル（MCP）実装。このプロジェクトは、リファレンス実装と機能的なタスク管理サーバーの両方として機能します。

概要

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

STDIO モード: CLI ベースのアプリケーションと AI エージェントの標準入出力通信
HTTP+SSE モード: ブラウザおよび HTTP ベースのクライアント向けの Server-Sent Events を備えた Web アクセス可能なサーバー

サーバーは、タスク管理操作、広範な検証、および堅牢なエラー処理の完全なセットを提供します。

特徴

タスク管理操作:
- フィルタリング機能を使用して既存のタスクを一覧表示する
- カスタマイズ可能なプロパティを持つ新しいタスクを作成する
- タスクの詳細（説明、ステータス、カテゴリ、優先度）を更新します
- 完了または不要になったらタスクを削除する
デュアルインターフェースモード:
- コマンドラインと AI エージェントの統合のための STDIO プロトコルのサポート
- ブラウザベースのアクセスのためのWebインターフェースを備えたHTTP + SSEプロトコル
MCPプロトコル実装:
- モデルコンテキストプロトコルの完全な実装
- タスクデータ構造のリソース
- タスク操作のためのツール
- エラー処理と情報メッセージ
品質保証：
- 検証のための包括的なテストクライアント
- テスト完了後の自動サーバーシャットダウン
- APIレスポンスの詳細な検証

はじめる

前提条件

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

インストール

リポジトリをクローンします。
git clone https://github.com/yourusername/mcp-template-ts.git cd mcp-template-ts
依存関係をインストールします:
npm install
またはpnpmを使用します:
pnpm install
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
プロジェクトをビルドします。
npm run build

サーバーの実行

STDIO モード (CLI/AI 統合用)

npm start

または

node dist/index.js

HTTP モード (Web アクセス用)

npm run start:http

または

node dist/http-server.js

デフォルトでは、HTTP サーバーはポート 3000 で実行されます。TASK_MANAGER_HTTP_PORT 環境変数TASK_MANAGER_HTTP_PORT設定することでこれを変更できます。

テスト

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

npm test

これにより、次のようになります。

プロジェクトを構築する
サーバーインスタンスを起動する
テストクライアントをサーバーに接続する
すべてのタスク操作を実行する
正しい回答を確認する
サーバーを自動的にシャットダウンする

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>
  <!-- Your interface elements here -->
</body>
</html>

利用可能なツール

タスク一覧

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

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
  }
});

タスク作成

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

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
  }
});

タスクの更新

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

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
  }
});

タスクの削除

タスクを削除します。

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

環境変数

変数	説明	デフォルト
タスクマネージャーAPIベースURL	外部タスク API の URL	なし（必須）
タスクマネージャーAPIキー	認証用のAPIキー	なし（必須）
タスクマネージャーHTTPポート	HTTPサーバーのポート	3000
ポート	代替ポート名（優先）	なし

プロジェクト構造

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

発達

TypeScript コンパイラをウォッチモードで起動します。
npm run watch
変更を確認するためにテストを実行します。
npm test

ライセンス

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

謝辞

このプロジェクトはMCPプロトコル実装に@modelcontextprotocol/sdkを使用します
AIツールやWebアプリケーションとの統合用に構築

Task API Server

Integrations