Simple Timer MCP Server

シンプルタイマー MCP サーバー

トークンベースの時間計測を使用して、インターバル計測機能を提供する MCP（Model Context Protocol）サーバーです。このプロジェクトは、MCP サーバー実装の初心者向けサンプルとして、最小限かつ実用的な機能を通じて MCP 開発の基本概念を紹介します。

機能

• トークンベースのタイマー：一意の文字列識別子（トークン）を使って、タイマーを開始したり確認したりできます。
• 経過時間の計算：タイマーの開始から経過した時間を計算して返します。
• 人が読みやすい出力：経過時間を人が読みやすい形式（例：「2 時間 15 分前」）で取得できます。
• タイマーの削除：既存のタイマーを削除できます。
• タイマーの一覧表示：現在有効なすべてのタイマーを一覧表示します。
• SQLite データベース：軽量な better-sqlite3 データベースを使用して、タイマーデータを永続的に保存します。

はじめに

以下の手順に従うと、開発およびテスト用にプロジェクトをローカルマシンで実行できます。

前提条件

• Node.js（v18.x 以降を推奨）
• Yarn（v1.x 以降）

インストール

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

   git clone https://github.com/tonyOgbonna/Simple-Timer-MCP-Server.git
   cd Simple-Timer-MCP-Server
   

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

   yarn install
   

プロジェクトのビルド

このプロジェクトは TypeScript で記述されており、JavaScript にコンパイルする必要があります。

yarn build

これにより、src/ 内の TypeScript ファイルが dist/ ディレクトリにコンパイルされます。

サーバーの起動

MCP サーバーを起動するには、次のコマンドを実行します。

yarn start

サーバーは、存在しない場合は SQLite データベース（プロジェクトルートの timer.db）を初期化し、StdioServerTransport を介して MCP リクエストの待ち受けを開始します。次のような出力が表示されます。

Database initialized and 'timers' table ensured.
MCP Server 'Simple Timer' started and listening via StdioServerTransport.

MCP ホストとの連携

このセクションでは、このローカル MCP サーバーをさまざまな MCP 対応ホスト（例：Cline、Roo Code、Cursor、Claude Code）と連携するための一般的な手順を説明します。正確な手順は、ホストのインターフェースによって多少異なる場合があります。

通常は、このサーバーを実行するコマンドをホストに指定する必要があります。

1. サーバーがビルドされていることを確認します：連携する前に、yarn build を実行してプロジェクトをビルドしてください。

2. 実行コマンドを指定します：このサーバーを実行するコマンドは node dist/index.js です。

   • コマンドを直接指定できるホストの場合：node dist/index.js を指定するだけです。
   • フルパスが必要なホストの場合：プロジェクトの dist/index.js ファイルの絶対パスを指定する必要がある場合があります。例：/path/to/your/project/timer_mcp_server/dist/index.js。
   • package.json のスクリプトを使用するホストの場合：ホストによっては、package.json で定義された start スクリプト（つまり yarn start）を自動的に検出して使用する場合があります。

   ローカル MCP サーバーの追加方法については、使用する MCP ホストのドキュメントを参照してください。

   一般的には、次のように設定します。

   "mcpServers": {
     "Simple-Timer-MCP-Server": {
       "command": "node",
       "args": [
         "/path/to/install/folder/dist/index.js"
       ]
     }
   }
   

MCP ツール

この MCP サーバーは、start_timer、check_timer、delete_timer、list_timers の 4 つのツールを公開します。

start_timer

指定したトークンの新しいタイマーを開始します。そのトークンのタイマーがすでに存在する場合は、既存のタイマーの開始時刻を通知します。

• 引数：

  • token（string、必須）：タイマー用の一意の文字列識別子です。

• 使用例（概念例 — MCP クライアント経由）：

  {
    "tool_name": "start_timer",
    "arguments": {
      "token": "my_first_timer"
    }
  }
  

• 応答例：

  Timer for token 'my_first_timer' started at: 2025-06-03T01:55:00.000Z
  

  または

  Timer for token 'my_first_timer' already exists. Started at: 2025-06-03T01:00:00.000Z
  

check_timer

既存のタイマーの経過時間を確認します。

• 引数：

  • token（文字列、必須）：タイマーを識別する一意の文字列です。
  • format（列挙型、任意）：ミリ秒単位の raw（デフォルト）、または説明形式の文字列を返す human_readable です。

• 使用例（概念上の例 — MCP クライアント経由）：

  {
    "tool_name": "check_timer",
    "arguments": {
      "token": "my_first_timer",
      "format": "human_readable"
    }
  }
  

• 応答例（human_readable）：

  token 'my_first_timer' の経過時間：1 hour, 30 minutes, 45 seconds.
  

• 応答例（raw）：

  token 'my_first_timer' の経過時間：5445000 milliseconds.
  

  または

  token 'non_existent_timer' のタイマーが見つかりません。
  

delete_timer

指定したトークンの既存のタイマーを削除します。

• 引数：

  • token（文字列、必須）：削除するタイマーを識別する一意の文字列です。

• 使用例（概念上の例 — MCP クライアント経由）：

  {
    "tool_name": "delete_timer",
    "arguments": {
      "token": "my_first_timer"
    }
  }
  

• 応答例：

  token 'my_first_timer' のタイマーを正常に削除しました。
  

  または

  削除する token 'non_existent_timer' のタイマーが見つかりません。
  

list_timers

現在有効なすべてのタイマーを一覧表示し、それぞれのトークンと開始時刻を返します。

• 引数：なし

• 使用例（概念上の例 — MCP クライアント経由）：

  {
    "tool_name": "list_timers",
    "arguments": {}
  }
  

• 応答例：

  [
    {
      "token": "my_first_timer",
      "startTime": "2025-06-03T01:55:00.000Z"
    },
    {
      "token": "another_timer",
      "startTime": "2025-06-03T02:00:00.000Z"
    }
  ]
  

  または（タイマーが存在しない場合）

  []
  

プロジェクト構成

.
├── .git/                 # Git version control directory
├── dist/                 # Compiled JavaScript output
├── src/                  # TypeScript source code
│   └── index.ts          # Main MCP server logic
├── .gitignore            # Specifies intentionally untracked files to ignore
├── package.json          # Project metadata and dependencies
├── README.md             # This file
├── tsconfig.json         # TypeScript configuration
├── yarn.lock             # Yarn dependency lock file
└── test-client.ts        # Script for testing server functionality

コントリビューション

コントリビューションを歓迎します！お気軽にイシューを作成するか、プルリクエストを送信してください。

ライセンス

このプロジェクトは ISC ライセンスの下でライセンスされています。