tm-mcp

Name: tm-mcp
Author: pyunto

本地服务

tm.pyunto.com生产力02 周前更新

代码仓库访问官网

关于 tm-mcp

tm-mcp 是面向 Pyunto Time Management 的 MCP 服务，供 AI 助手查看日程并管理工时记录。提供密码时，服务器会在本地解密加密内容。

主要功能

01查看项目和任务
02列出日程块并汇总工时
03创建、更新和删除时间块
04在本地解密加密的名称和备注

适用场景

01按项目或日期查看工时
02通过 AI 助手记录时间
03不解密内容也能查看日程

MCP 相关

向 MCP 客户端提供 Pyunto Time Management 账户和时间跟踪工具。无需 API 密钥即可列出工具；访问账户数据则需要密钥。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "pyunto-tm": {
      "command": "npx",
      "args": [
        "-y",
        "@pyunto/tm-mcp"
      ],
      "env": {
        "PYUNTO_TM_API_KEY": "<PYUNTO_TM_API_KEY>",
        "PYUNTO_TM_BASE_URL": "<PYUNTO_TM_BASE_URL>",
        "PYUNTO_TM_PASSWORD": "<PYUNTO_TM_PASSWORD>",
        "PYUNTO_TM_PASSWORD_FILE": "<PYUNTO_TM_PASSWORD_FILE>"
      }
    }
  }
}

启动命令npx -y @pyunto/tm-mcp

需要配置的环境变量

PYUNTO_TM_API_KEY密钥API key (ptm_...) minted in Settings → Account → API keys

PYUNTO_TM_BASE_URLBase URL, for self-hosted instances

PYUNTO_TM_PASSWORD密钥Account password; unwraps the private key locally so E2EE project and task names decrypt

PYUNTO_TM_PASSWORD_FILE密钥Path to a file holding the account password, instead of PYUNTO_TM_PASSWORD

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@pyunto/tm-mcp0.3.4stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

@pyunto/tm-mcp

适用于 Pyunto Time Management 的 MCP（Model Context Protocol）服务。可连接 Claude Code、Claude Desktop、Codex CLI、Cursor 及任何其他 MCP 客户端与 Pyunto TM 账户，让助手读取日程、汇总时间去向并记录时间。

面向用户的设置说明位于 https://tm.pyunto.com/docs/mcp.en.md（日本語: https://tm.pyunto.com/docs/mcp.ja.md）。本文面向开发者。

工具

工具	权限范围
`whoami` — 账户、密钥名称、权限范围、解密状态	—
`list_projects`	`projects:read`
`list_tasks`（按项目或任务涵盖的日期筛选）	`projects:read`
`list_time_blocks`（范围 ≤ 92 天）	`blocks:read`
`time_summary`（按项目／任务／日期分组）	`record:read`
`log_time`（写入）	`blocks:write`
`update_time_block`（写入）	`blocks:write`
`delete_time_block` — 单个 ID，永久删除，并一并删除附件	`blocks:delete`

每个工具都会以文本形式返回 JSON。失败时会返回 isError 结果，消息会说明如何修复（缺少权限范围、密钥错误、E2EE 已锁定），而不是在传输层抛出异常——Agent 可以据此采取行动，而无法处理堆栈跟踪。

安装

npx -y @pyunto/tm-mcp        # what an MCP client config runs

从源代码构建

此软件包与其依赖的 SDK 同处于 npm-workspaces 仓库中；请从仓库根目录构建，以使用工作区链接：

npm install
npm run build                 # both packages
npm test                      # sdk crypto round-trips + 25 MCP tool checks

结果：mcp/dist/cli.js，可执行的 stdio 服务（dist/index.js 仍是无副作用、可供测试导入的模块）。

配置

仅使用环境变量——MCP 客户端会启动进程，并从其配置文件中注入环境变量。

服务无需 API 密钥即可启动并响应 tools/list——客户端或目录可以在任何人注册前查看它提供的功能。没有 API 密钥时调用工具，会返回与 isError 相同的说明，而不是含糊的 401；whoami 也会报告缺少密钥，而不会失败。

变量	必需	默认值	用途
`PYUNTO_TM_API_KEY`	用于数据	—	`ptm_…`，在 Settings → Account → API keys 中创建。无需密钥即可列出工具
`PYUNTO_TM_BASE_URL`		`https://tm.pyunto.com`	可自托管的实例
`PYUNTO_TM_PASSWORD`		无	在本地解包私钥，以解密 E2EE 名称／备注
`PYUNTO_TM_PASSWORD_FILE`		无	同上，从文件而非环境变量读取

{
  "mcpServers": {
    "pyunto-tm": {
      "command": "npx",
      "args": ["-y", "@pyunto/tm-mcp"],
      "env": { "PYUNTO_TM_API_KEY": "ptm_…" }
    }
  }
}

如何处理 E2EE

内容字段在用户的浏览器中加密；服务器从不持有明文，默认情况下本进程也不会持有。提供密码后，服务器会在此处于内存中解包由密码封装的私钥数据块（GET /api/v1/keys，权限范围为 keys:read），并用它打开每个项目封存的 DEK。密码绝不会传输，也不会写入磁盘。

没有密码时，服务器仍会响应所有与日程相关的数据——ID、日期、时间、时长、汇总；名称字段则为空，并附上解释原因的 NOTE:，以便模型如实说明限制，而不是编造名称。

目录结构

src/index.ts     tool definitions + implementations + server wiring
src/cli.ts       the bin: calls start()
test/tools.mjs   stub /api/v1 server, exercises every tool and error path
test/cli.mjs     spawns the built bin (directly and via symlink) over real MCP

callTool(name, args) 已导出供测试使用；start() 会挂载传输层，且仅由 cli.ts 调用。

delete_time_block 刻意设计为仅支持单个 ID：不提供按范围或筛选条件删除的功能，因为自动化调用方一旦弄错范围，就可能销毁无法恢复的大量数据。该工具的描述要求模型先向用户展示确切的时间块，并取得用户对该时间块的确认。

支持 Markdown

登录后评论