Simple Timer MCP Server

简单定时器MCP服务器

使用基于令牌的时间跟踪提供间隔计时功能的MCP（模型上下文协议）服务器。该项目是MCP服务器实现的初学者友好示例，通过最小的实用功能演示了核心MCP开发概念。

特性

• 基于令牌的计时器：使用唯一的字符串标识符（令牌）启动和检查计时器。
• 经过时间计算：计算并返回自计时器启动以来经过的时间。
• 人类可读输出：以人类可读格式获取经过时间的选项（例如，“2小时15分钟前”）。
• 定时器删除：能够删除现有计时器。
• 计时器列表：列出所有当前活动的计时器。
• SQLite数据库：使用轻量级 better-sqlite3 用于持久存储定时器数据的数据库。

入门指南

这些说明将为您提供一份项目副本，并在本地计算机上运行，以用于开发和测试目的。

先决条件

• Node.js（建议使用v18.x或更高版本）
• 纱线（v1.x或更高版本）

安装

1. 克隆存储库：

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

1. 安装依赖项：

   yarn install

建设项目

该项目是用TypeScript编写的，需要编译成JavaScript。

yarn build

这将编译TypeScript文件 src/ 进入 dist/ 目录。

运行服务器

要启动MCP服务器，请运行以下命令：

yarn start

服务器将初始化SQLite数据库(timer.db 在项目根目录中），如果它不存在，并通过以下方式开始监听MCP请求 StdioServerTransport。您应该看到类似于以下内容的输出：

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.

1. 提供执行命令：运行此服务器的命令是 node dist/index.js.

- 对于接受直接命令的主机：只需提供 node dist/index.js. - 对于需要完整路径的主机：您可能需要提供项目的绝对路径 dist/index.js 文件。， /path/to/your/project/timer_mcp_server/dist/index.js. - 对于使用 package.json 脚本：某些主机可能会自动检测并使用 start 脚本定义于 package.json （即。， 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.

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 （string，必填）：计时器的唯一字符串标识符。 - format （枚举，可选）： raw （默认）毫秒，或 human_readable 对于描述性字符串。

• 示例用法（概念性-通过MCP客户端）:

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

• 示例响应（human_readable）:

  Elapsed time for token 'my_first_timer': 1 hour, 30 minutes, 45 seconds.

• 示例响应（原始）:

  Elapsed time for token 'my_first_timer': 5445000 milliseconds.

或

  No timer found for token 'non_existent_timer'.

delete_timer

删除给定令牌的现有计时器。

• 参数:

- token （string，必填）：要删除的计时器的唯一字符串标识符。

• 示例用法（概念性-通过MCP客户端）:

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

• 示例响应:

  Timer for token 'my_first_timer' deleted successfully.

或

  No timer found for token 'non_existent_timer' to delete.

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

贡献

欢迎投稿！请随时打开问题或提交pull请求。

许可证

该项目根据ISC许可证获得许可。