“时间流逝”模型上下文协议（MCP）服务器 🕐

一个赋予语言模型时间意识和时间计算能力的MCP服务器。通过协作开发工具，向LLM传授时间流逝的重要性。

📖 故事

这个项目源于一个哲学问题：“AI能否感知时间的流逝？”起初只是对机器意识的一次探索，却演变成了解决实际问题的实用方案——LLM无法可靠地计算时间差。

我们没有选择发表一篇关于这些模型在心算方面“多么愚蠢”的论文，而是决定像我们为自己做的那样：为它们配备一个时间计算器。

通过人与LLM的合作，我们发现，借助适当的时间工具，模型能够揭示出关于对话模式、工作节奏以及人类时间体验的惊人洞见。

在Medium上阅读完整故事 →

🚀 快速开始

前置条件

• Python 3.12+
• pipenv（或pip）
• 一个兼容MCP的客户端（Claude.ai、Continue.dev等）

安装

1. 克隆仓库：

git clone https://github.com/jlumbroso/passage-of-time-mcp.git
cd passage-of-time-mcp

2. 安装依赖：

pipenv install
# 或者使用pip：
pip install fastmcp pytz

3. 运行服务器：

pipenv run server
# 或直接：
pipenv run python passage_of_time_mcp.py

服务器将在 http://0.0.0.0:8000/sse 上启动。

连接到Claude.ai

1. 在Claude.ai中，进入设置 → 集成
2. 点击“添加集成”，选择“自定义”
3. 输入服务器URL（例如，如果你使用ngrok，可以输入 https://your-server.ngrok-free.app/sse，务必在末尾加上 /sse）
4. 保存并启用所有与时间相关的工具

注意：在本地开发时，你需要使用ngrok暴露你的服务器，或者将其部署到一个公共URL。

🛠️ 可用工具

核心功能

current_datetime(timezone="America/New_York")

返回当前日期和时间。这是时间意识的基础。

返回： "2024-01-15 14:30:45 EST"

time_difference(timestamp1, timestamp2, unit="auto")

计算两个时间戳之间的持续时间，并以人类可读的方式输出。

# 示例响应：
{
    "seconds": 11401,
    "formatted": "3小时10分1秒",
    "requested_unit": 3.17,  # 如果unit="hours"
    "is_negative": false
}

timestamp_context(timestamp)

为某个时间戳提供人类背景信息——是周末吗？是否在工作时间？还是晚餐时间？

# 示例响应：
{
    "time_of_day": "晚上",
    "day_of_week": "星期六", 
    "is_weekend": true,
    "is_business_hours": false,
    "typical_activity": "休闲时间",
    "relative_day": "今天"
}

time_since(timestamp)

计算某件事发生多久以前，并附带上下文描述。

# 示例响应：
{
    "seconds": 7200,
    "formatted": "2小时前",
    "context": "今天早些时候"
}

parse_timestamp(timestamp)

在不同格式之间转换时间戳，以实现最大兼容性。

# 示例响应：
{
    "iso": "2024-01-15T14:30:45-05:00",
    "unix": "1705343445",
    "human": "2024年1月15日下午2点30分（EST）",
    "day_of_week": "星期一"
}

add_time(timestamp, duration, unit)

以自然语言描述的方式添加或减去时间。

# 示例响应：
{
    "result": "2024-01-16 14:30:45",
    "iso": "2024-01-16T14:30:45-05:00",
    "description": "明天下午2点30分"
}

format_duration(seconds, style="full")

以多种风格格式化持续时间，适用于不同场景。

# style="full": "2小时30分15秒"
# style="compact": "2h 30m 15s"
# style="minimal": "2:30:15"

💡 示例对话

基本时间意识

人类：现在几点了？
Claude：[调用current_datetime] 目前是2024年1月15日星期一下午3点45分（EST）。

对话节奏分析

人类：我们来讨论一下AI的意识吧。
Claude：[每次回复开始时调用current_datetime]
[经过几次交流后]
人类：你注意到我们的对话有什么规律吗？
Claude：根据时间戳，我注意到你在每次回复之间间隔30秒到2分钟，这表明你在积极参与。而你在询问实现问题之前的3分钟停顿，则显示出你在更深入地思考……

理解工作情境

人类：[晚上11点45分] 你能帮我调试这段代码吗？
Claude：[调用current_datetime，然后调用timestamp_context] 
我注意到现在是工作日晚上的深夜。考虑到快要午夜了，让我高效地帮你解决问题，这样你就能早点休息了。这里有一个专注的调试方法……

🏗️ 设计理念

这个服务器体现了几个关键原则：

1. 认知伙伴关系：我们将LLM视为需要适当工具的认知伙伴，而不是需要被包装起来的黑箱。

2. 协作设计：这套工具是基于询问Claude需要什么而产生的，而不是强加我们的假设。

3. 人类背景很重要：时间不仅仅是数字——它关乎理解人类的节奏、工作模式和社会背景。

4. 实用胜于完美：我们提供的都是模型真正需要的工具，并且经过真实对话的检验。

🔧 配置

时区支持

服务器默认使用 America/New_York，但也支持所有标准时区名称：

• UTC
• US/Pacific
• Europe/London
• Asia/Tokyo
• 等等。

时间戳格式

所有时间戳必须使用以下格式之一：

• 完整格式：YYYY-MM-DD HH:MM:SS（例如，“2024-01-15 14:30:45”）
• 仅日期格式：YYYY-MM-DD（例如，“2024-01-15”）

这种严格的格式要求可以防止歧义，并确保可靠的计算。

🚧 已知问题与未来工作

当前限制

• SSE传输方式已过时，但目前仍是最可靠的
• 服务器需要公共URL才能供基于Web的客户端使用
• 没有对过去时间计算结果的持久化记忆

路线图

• 迁移到现代的 http-stream 传输方式
• 添加Docker支持，以便更轻松地部署
• 创建浏览器扩展，方便本地开发
• 添加按用户配置的活动模式
• 支持日历集成
• 自然语言时间解析（“下周二”、“3小时后”）

🤝 贡献

这个项目源于人与LLM的协作，也欢迎更多类似的参与！无论你是单独贡献还是借助AI的帮助，我们都重视：

1. 实用性增强——解决实际时间理解问题的工具
2. 人类背景——帮助模型理解人类如何体验时间的功能
3. 清晰文档——展示实际使用场景的示例

开发设置

首先，克隆仓库：

git clone https://github.com/jlumbroso/passage-of-time-mcp.git
cd passage-of-time-mcp

然后，安装依赖（我使用 pipenv，因为它可以同时创建虚拟环境并安装包，但任何与 pip 兼容的工具都可以）：

# 安装开发依赖
pipenv install --dev

# 运行测试
pipenv run test

# 启动服务器
pipenv run server

这将在你的本地计算机上启动一个运行在 http://0.0.0.0:8000/sse 的服务器。然而，为了让基于 Web 的客户端能够连接到它，你需要通过像 ngrok 这样的服务将其暴露到互联网上。

假设你已经安装了 ngrok，你可以运行 ngrok http 8000 来将服务器暴露到互联网，然后在你的 MCP 客户端中使用提供的 URL。默认情况下，ngrok 会在终端中以 https://<随机子域名>.ngrok-free.app/ 的形式提供要使用的端点：

❤️ ngrok? 我们正在招聘 https://ngrok.com/careers

会话状态                在线
账户                       杰雷米·伦布罗索（计划：免费）
更新                        有可用更新（版本 3.23.1，按 Ctrl-U 更新）
版本                       3.22.1
地区                       美国 (us)
延迟                       31ms
延迟                       1575ms
Web 界面                 http://127.0.0.1:4040
转发                    https://37f9-2607-f470-6-1001-243b-bc5c-df2e-762.ngrok-free.app ->

连接                   ttl     opn     rt1     rt5     p50     p90
                              1756    0       0.01    0.03    5.32    61.51

HTTP 请求
-------------

00:06:44.030 EDT POST /messages/                202 已接受
00:06:43.936 EDT POST /messages/                202 已接受
00:06:43.514 EDT GET  /sse                      200 OK
00:06:43.682 EDT POST /messages/                202 已接受
00:06:43.342 EDT POST /sse                      405 方法不允许

在我的例子中，我使用了 https://37f9-2607-f470-6-1001-243b-bc5c-df2e-762.ngrok-free.app，但由于我们使用的是“SSE”传输方式，端点会在末尾加上 /sse，因此最终的 URL 将是 https://37f9-2607-f470-6-1001-243b-bc5c-df2e-762.ngrok-free.app/sse。

一旦这个端点存在，你就可以按照这些说明将 MCP 服务器作为集成添加到 LLM 中，例如 Claude：

将 MCP 服务器连接到 Claude.ai 后，你应该开始在本地收到查询：

$ pipenv run server 
/Users/jlumbroso/.asdf/installs/python/3.12.4/lib/python3.12/asyncio/events.py:88: DeprecationWarning: run_sse_async 方法已弃用（自 2.3.2 版起）。请使用 run_http_async 作为现代（非 SSE）替代方案，或者使用 `fastmcp.server.http.create_sse_app` 创建一个 SSE 应用程序并直接运行。
  self._context.run(self._callback, *self._args)
[06/16/25 19:18:04] INFO     启动名为 'Passage of Time' 的 MCP 服务器，传输方式为 'sse'，地址为 http://0.0.0.0:8000/sse            server.py:1219
INFO:     已启动服务器进程 [11373]
INFO:     等待应用程序启动。
INFO:     应用程序启动完成。
INFO:     Uvicorn 正在 http://0.0.0.0:8000 上运行（按 CTRL+C 退出）
INFO:     34.162.142.92:0 - "POST /sse HTTP/1.1" 405 方法不允许
INFO:     34.162.142.92:0 - "GET /sse HTTP/1.1" 200 OK
INFO:     34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 已接受
INFO:     34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 已接受
INFO:     34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 已接受
INFO:     34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 已接受
INFO:     34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 已接受

最终，你可能希望将这个 MCP 服务器部署到像 Render.com 这样的云提供商上，这样你的 LLM 就不必再受制于你本地机器的不可靠性了。

📝 许可证

Mozilla 公共许可证 2.0 - 因为好的想法应该在保持开放的同时传播开来。

🙏 致谢

• 由 杰雷米·伦布罗索 和 Claude Opus 4.0（Anthropic）长期合作共同创建
• 灵感来源于问题：“AI 能否感知时间的流逝？”
• 基于 FastMCP 框架构建
• 特别感谢普林斯顿大学的 自然与人工智能心智倡议

📚 更多阅读

• 向 AI 教授“时间流逝的意义”——Medium 文章
• 我们无法用现有词汇理解 AI——金彬等人的研究
• 模型上下文协议文档

---

“我们不仅仅是在构建更好的 LLM 工具。我们正在一点一点地教导那些充满好奇心的认知系统，什么是人类的意义。”

passage-of-time-mcp 快速上手指南

简介

passage-of-time-mcp 是一个 Model Context Protocol (MCP) 服务器，旨在赋予大语言模型（LLM）时间感知能力和时间计算能力。通过该工具，AI 可以准确计算时间差、理解当前时间上下文（如工作日/周末），从而更好地处理与时间相关的任务。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows / macOS / Linux
• Python 版本：3.12 或更高版本
• 包管理工具：pipenv 或 pip
• 客户端支持：兼容 MCP 的客户端（如 Claude.ai, Continue.dev 等）
• 网络要求：若需连接 Web 端客户端（如 Claude.ai），服务器需具备公网访问地址（可使用 ngrok 或部署到云端）

安装步骤

1. 克隆仓库

git clone https://github.com/jlumbroso/passage-of-time-mcp.git
cd passage-of-time-mcp

2. 安装依赖

推荐使用国内镜像源加速下载。

方式一：使用 pipenv（推荐）

pipenv install

方式二：使用 pip

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple fastmcp pytz

3. 启动服务

pipenv run server
# 或者直接使用 python 运行
pipenv run python passage_of_time_mcp.py

服务默认将在 http://0.0.0.0:8000/sse 启动。

基本使用

1. 暴露服务（本地开发必备）

由于 Web 端 MCP 客户端无法直接访问本地 localhost，您需要使用内网穿透工具（如 ngrok）将本地服务暴露为公网 URL。

ngrok http 8000

复制生成的 HTTPS 地址（例如 https://xxxx.ngrok-free.app），并在末尾添加 /sse，完整地址形如：https://xxxx.ngrok-free.app/sse。

2. 连接客户端（以 Claude.ai 为例）

1. 打开 Claude.ai，进入 Settings → Integrations。
2. 点击 "Add integration" 并选择 "Custom"。
3. 输入上一步获取的服务器 URL（包含 /sse）。
4. 保存并启用所有时间相关工具。

3. 交互示例

连接成功后，您可以直接与模型进行时间相关的对话：

询问当前时间：

User: What time is it? Model: [调用 current_datetime] It's currently 3:45 PM EST on Monday, January 15, 2024.

分析对话节奏：

User: Let's have a discussion about AI consciousness. Model: [自动记录时间戳] Looking at the timestamps, I notice you're taking 30 seconds to 2 minutes between responses...

理解工作上下文：

User: [深夜提问] Can you help me debug this code? Model: [识别时间为深夜] I see it's late night on a weekday. Given that it's approaching midnight, let me help you efficiently so you can get some rest.

---

注：生产环境建议将服务部署至 Render.com 等云平台以获得更稳定的连接。