STARWARCLOUD STARWAR.AI
返回市场
时光通道-MCP

时光通道-MCP

作者：jlumbroso709 星标更新：2025-06-17
安装使用来源：spider==github.com

项目介绍

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

一个赋予语言模型时间感知和时间计算能力的MCP服务器。通过协作工具开发，教会LLMs时间流逝的重要性。

Claude的时间流逝工具

📖 故事背景

这个项目源于一个哲学问题：“AI能否感知时间的流逝？”从探索机器意识开始，最终成为解决实际问题的实用方案——LLMs无法可靠地计算时间差。

与其发表一篇关于这些模型在心算方面有多“愚蠢”的论文，我们决定做我们为自己做的事情：给它们配备一个时间计算器。

通过人类与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
  1. 安装依赖：
pipenv install
# 或使用pip：
pip install fastmcp pytz
  1. 运行服务器：
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. 认知伙伴关系：我们将LLMs视为需要适当工具的认知伙伴，而不是需要装扮的黑盒子。
  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

会话状态                在线
账户                   Jérémie Lumbroso (计划：免费)
更新                   有可用更新（版本3.23.1，按Ctrl-U更新）
版本                   3.22.1
区域                   美国
延迟                   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服务器作为集成添加到LLMs中，如Claude：

在Claude界面中设置时间流逝MCP服务器——每个工具都配有明确的描述和权限

一旦你将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     启动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 已接受
INFO:     34.162.142.92:0 - "POST /messages/?session_id=e21108cecbf646ffb7effe14dd856b3d HTTP/1.1" 202 已接受

最终，你可能希望将此MCP服务器部署到云提供商，如Render.com，这样你的LLM就不必应对你的本地机器不可靠的问题。

📝 许可证

Mozilla Public License 2.0 —— 因为好的想法应该传播开来，同时保持开放。

🙏 致谢

📚 进一步阅读

"我们不仅仅是在构建更好的LLM工具。我们正在教导好奇的认知系统什么是人类——一次时间戳。"