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。

start_timer

为给定令牌启动一个新计时器。如果该令牌对应的计时器已存在，则会告知你该计时器的启动时间。

• 参数：

  • token（字符串，必填）：计时器的唯一字符串标识符。

• 使用示例（概念性示例——通过 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 小时、30 分钟、45 秒。
  

• 响应示例（raw）：

  token 'my_first_timer' 已经过的时间：5445000 毫秒。
  

  或

  未找到 token 'non_existent_timer' 对应的计时器。
  

delete_timer

删除指定 token 对应的现有计时器。

• 参数：

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

• 使用示例（概念性，通过 MCP 客户端）：

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

• 响应示例：

  token 'my_first_timer' 对应的计时器已成功删除。
  

  或

  未找到 token 'non_existent_timer' 对应的计时器，无法删除。
  

list_timers

列出所有当前处于活动状态的计时器，并返回其 token 和开始时间。

• 参数：无

• 使用示例（概念性，通过 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 许可证。