Work Diary MCP

工作日记mcp

A. 模型上下文协议（MCP） 用于管理每周工作日记的服务器。内置于 FastMCP 在Python中。

通过对话方式与您的日记互动 Claude 命令行界面 或 泽德服务器将Markdown文件写入磁盘，可以直接复制到Microsoft Loop（或任何兼容Markdown的工具）中。

有关更改的运行摘要，请参阅 更改日志.md.

______________________________________________________________________

索引

• 快速开始
• 配置
• 工具
• 用法
• 特性
• 支持的状态值
• 支持的角色价值观
• Jira自动链接
• 数据格式
• 数据位置
• 延续行为
• 项目结构
• 测试

______________________________________________________________________

快速开始

先决条件

• Python 3.11+
• uv --使用官方文档中的平台说明安装它：

该项目旨在同时开展这两项工作 macOS 和 视窗以下示例在需要时使用Unix风格的路径；在Windows上，使用等效的本地路径 uv 您环境的可执行文件位置。

安装依赖项

cd ~/work-diary-mcp/python
uv sync

在Zed注册

添加到您的Zed settings.json (cmd+,).此示例显示了以下对象的macOS样式路径 uv；在Windows上，使用以下路径 uv.exe 或另一个解析为 uv 在您的环境中：

{
  "context_servers": {
    "work-diary": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/Users/yourname/work-diary-mcp/python",
        "run",
        "work-diary-mcp"
      ],
      "env": {}
    }
  }
}

在Claude CLI注册

使用任何东西 uv 可执行路径适合您的平台：

claude mcp add work-diary /path/to/uv \
  --directory $HOME/work-diary-mcp/python run work-diary-mcp

______________________________________________________________________

配置

默认情况下，日记文件会写入 data/ 在存储库内部。您可以将服务器指向任何目录，并使用环境变量或设置文件配置Jira自动链接。

环境变量

数据目录

集 WORK_DIARY_DATA_DIR 绝对（或 ~-前缀）路径：

export WORK_DIARY_DATA_DIR=~/Documents/work-diary

要使其永久化，请将导出添加到您的shell配置文件中，并将其传递到MCP客户端配置中的服务器。

泽德 --添加一个 env 条目：

{
  "context_servers": {
    "work-diary": {
      "command": "/path/to/uv",
      "args": ["--directory", "/Users/yourname/work-diary-mcp/python", "run", "work-diary-mcp"],
      "env": {
        "WORK_DIARY_DATA_DIR": "/Users/yourname/Documents/work-diary"
      }
    }
  }
}

Claude 命令行界面 --注册时添加env-var：

claude mcp add work-diary /path/to/uv \
  --directory $HOME/work-diary-mcp/python run work-diary-mcp \
  --env WORK_DIARY_DATA_DIR=$HOME/Documents/work-diary

在Windows上，使用Windows样式路径 uv 可执行和 WORK_DIARY_DATA_DIR.

Jira自动链接

您还可以通过环境变量配置Jira链接：

• WORK_DIARY_JIRA_BASE_URL
• WORK_DIARY_JIRA_PREFIXES

例子：

export WORK_DIARY_JIRA_BASE_URL=https://jira.example.com/browse
export WORK_DIARY_JIRA_PREFIXES=PROJ,INFRA,ENG

WORK_DIARY_JIRA_BASE_URL 必须是非空URL，并且必须包含以下方案 https://.

多过程安全

默认情况下， work-diary-mcp 使用进程内 threading.Locks来协调写入。对于单个MCP服务器进程是数据目录的唯一写入者的常见情况，这是安全的，并避免了每次调用 flock / msvcrt.locking 头顶。

如果运行多个写入同一数据目录的进程，请设置 WORK_DIARY_FILE_LOCKS=1 要额外获取每周和提醒写入的文件系统锁：

export WORK_DIARY_FILE_LOCKS=1

设置文件

使用以下键的任意组合创建设置文件：

• macOS/Linux： ~/.config/work-diary/settings.toml
• 窗户： %APPDATA%\work-diary\settings.toml

data_dir = "~/Documents/work-diary"
jira_base_url = "https://jira.example.com/browse"
jira_prefixes = ["PROJ", "INFRA", "ENG", "OPS", "SEC", "DATA"]

设置文件密钥：

• data_dir --日记文件和提醒存储应该放在哪里
• jira_base_url --Jira实例的基本浏览URL
• jira_prefixes --应链接的Jira项目密钥前缀列表

jira_base_url 必须是非空URL，并且必须包含以下方案 https://.

配置的路径会自动展开，并在首次使用时创建目录。

解析顺序

数据目录

1. WORK_DIARY_DATA_DIR 环境变量
2. data_dir 在平台本机设置文件中
3. 内置默认值： /data

Jira自动链接

1. WORK_DIARY_JIRA_BASE_URL / WORK_DIARY_JIRA_PREFIXES 环境变量
2. jira_base_url / jira_prefixes 在平台本机设置文件中
3. 内置默认值：

- https://jira.example.com/browse - ["PROJ", "INFRA", "ENG", "OPS", "SEC", "DATA"]

______________________________________________________________________

工具

______________________________________________________________________

用法

自然地说话——你的MCP客户端会自动调用正确的工具：

Update Project Phoenix to On Track
Platform Infra is now blocked — waiting on the infra team
Add a note: had a productive all-hands today, big Q3 roadmap updates
Show me this week's diary
What projects am I tracking this week?
Show me my diary from last week
Show me my diary from 2 weeks ago
What weeks do I have diary entries for?
Remove Project Phoenix from this week
Clear the note on Platform Infra
Update [Project Phoenix](https://jira.example.com/PROJ-123) to At Risk with a note: blocked on dependency
Rename Project Phoenix to Phoenix Rewrite
Update all my projects: Phoenix Rewrite is On Track, Platform Infra is Blocked, Auth Service is Done
Append a note to Platform Infra: dependency resolved, unblocked as of Friday
Edit note 2: corrected — the all-hands covered Q3 and Q4 roadmap
Delete note 3
PROJ-1234 is now On Track
Add a note: opened PROJ-1234 and INFRA-5678 to track the rollout
Add a note to last week's diary: wrapped up the migration checklist
Edit note 2 in last week's diary: corrected the rollout status
Delete note 1 from 2 weeks ago
Update Stacks on TFE to Blocked in last week's diary with a note: waiting on dependency
Update project 2 to Done
Clear the note on project 3
Rename project 1 to Phoenix Rewrite
Add a reminder for next week: follow up with the perf team
Add a reminder for next week with due date Friday: confirm rollout checklist
Add a reminder in 4 weeks: prepare rollout notes
List reminders for next week
Complete reminder 1 for next week
Reopen reminder 1 for next week

______________________________________________________________________

特性

• 项目状态表 --跟踪每个项目的状态、可选的内联注释和可选的参与角色
• 参与角色 -在每个项目上标记一个首席工程师风格的参与角色（赞助商、向导、追赶者、顾问、催化剂、参与者），并在专用的表情符号中呈现 Role 列。角色与项目本身一起每周进行。
• 一般说明 --在一周内添加笔记
• 结转 --在每个新周的第一次交互中，未完成的项目会自动从前一周结转，而项目注释会重置为新周
• Jira自动链接 --裸Jira票证引用（用于支持的前缀，如 PROJ-1234 或 INFRA-5678)自动转换为Markdown链接
• Markdown链接 --在任何地方使用标准的Markdown链接语法： [text](url)
• 相对日期支持 --使用ISO日期和自然语言（如 "last week", "next week", "2 weeks ago", "2 weeks from now"，或 "in 4 weeks"
• 上周写支持 --通过指定日期（如）添加注释并更新过去一周的项目 "last week" 或 "2026-03-02"
• 项目行引用 --使用以下短语按表行引用现有项目 "project 2" 更新、批量更新、重命名、删除或清除项目注释时。如果引用类似 "project 2" 也可能意味着一个名为 Project 2，服务器会产生歧义错误，而不是猜测。 project 0 始终无效，即使存在具有该名称的文字项目。超出范围的正引用被视为字面项目名称。
• 提醒事项 --存储当前或未来几周的提醒，而不创建未来的日记页面，将其呈现在专用部分，并用复选框标记为完成
• 可配置数据目录 --将日记文件存储在仓库默认位置，或将服务器指向自定义目录

______________________________________________________________________

支持的状态值

众所周知的状态会自动格式化为表情符号。任何其他字符串都按原样存储。

终端状态用于决定哪些内容不应转入新的一周。

______________________________________________________________________

支持的角色价值观

项目角色受首席工程师角色框架的启发。每个项目都可以选择在其状态旁边分配一个角色；该角色在一个专门的 Role 日记项目表中的列。

角色对输入不区分大小写，并接受规范名称、表情符号快捷方式、裸表情符号或已格式化的显示值。传递一个空字符串以清除之前设置的角色。未知值按原样存储，因此调用者可以根据需要使用任意角色标签。

______________________________________________________________________

Jira自动链接

每当文本保存到日记中时，Bare Jira票证引用都会自动转换为Markdown链接，包括项目名称、内联注释和常规注释。已链接的引用永远不会双重链接。

默认的Jira配置为：

• 基本URL: https://jira.example.com/browse
• 前缀： PROJ, INFRA, ENG, OPS, SEC, DATA

您可以通过以下任一方式覆盖这些内容：

• 环境变量：

- WORK_DIARY_JIRA_BASE_URL - WORK_DIARY_JIRA_PREFIXES （例如，逗号分隔 PROJ,INFRA,ENG)

• 设置文件：

- jira_base_url - jira_prefixes

示例：

票证密钥在生成的链接中大写。与支持的前缀不匹配的引用将保持原样。

WORK_DIARY_JIRA_BASE_URL / jira_base_url 必须是非空URL，并且必须包含以下方案 https://.

______________________________________________________________________

数据格式

每周的日记以两个文件的形式存储在配置的数据目录中，以该周的星期一为关键字。

YYYY-MM-DD.json --真相来源：

{
  "weekKey": "2026-03-02",
  "projects": {
    "[Project Phoenix](https://jira.example.com/browse/PROJ-123)": "On Track"
  },
  "projectNotes": {
    "[Project Phoenix](https://jira.example.com/browse/PROJ-123)": "A few bugs found; [PROJ-124](https://jira.example.com/browse/PROJ-124) opened to track."
  },
  "projectRoles": {
    "[Project Phoenix](https://jira.example.com/browse/PROJ-123)": "🚀 Sponsor"
  },
  "notes": [
    {
      "content": "Kickoff meeting with TPM for Platform Infra."
    }
  ]
}

YYYY-MM-DD.md --渲染输出：

# Work Diary — Week of Mar 2, 2026

## Reminders for this week

- [ ] Due Date: 2026-03-06 Follow up with the perf team
- [x] Confirm rollout checklist

## Project Status

| Project | Role | Status | Notes |
|---------|------|--------|-------|
| [Project Phoenix](https://jira.example.com/browse/PROJ-123) | 🚀 Sponsor | 🟢 On Track | A few bugs found; [PROJ-124](https://jira.example.com/browse/PROJ-124) opened to track. |

## Notes

- **[1]** Kickoff meeting with TPM for Platform Infra.

______________________________________________________________________

数据位置

日记文件存储在中所述的配置数据目录中 配置.

每周由该周周一键入的两个文件表示：

• YYYY-MM-DD.json --真理之源（原始状态）
• YYYY-MM-DD.md --已渲染的Markdown，准备复制到Microsoft Loop中

提醒信息分别存储在：

• reminders.json --当前和未来几周提醒的真相来源

写入操作默认为当前周，但也可以使用相对日期或ISO日期针对特定周，包括 "last week", "next week", "N weeks ago", "N weeks from now", "in N weeks"，或值，例如 "2026-03-02"如果过去的一周还不存在，服务器会为该周创建一个空日记页，而不是结转状态。未来的提醒不会创建未来的日记页面。

______________________________________________________________________

延续行为

在每个新的一周的第一次交互中，会自动创建一个新的日记页面。非终端项目是从最近的前一周复制过来的，所以你永远不会从一张白纸开始。

结转行为目前为：

• 项目状态结转
• 项目角色被延续
• 项目内联注释不结转
• 一般注释不结转
• 已完成或取消的项目不结转
• 该周的提醒将在新的日记页中呈现，而不会提前创建未来的日记页
• 当某一周的提醒发生变化时，该周的持久Markdown会重新生成

具有终端状态的项目，例如 完成, 完成, 完成, 已取消, 已取消, 已发货，或 GA 待在他们完成的那一周，不要弄乱新一周的日记。

______________________________________________________________________

项目结构

work-diary-mcp/
├── .gitignore
├── README.md
├── CHANGELOG.md
├── data/                          # Diary files (gitignored) — default location
│   ├── YYYY-MM-DD.json            # Raw state for each week
│   └── YYYY-MM-DD.md              # Rendered Markdown, ready to copy into Loop
└── python/
    ├── README.md                  # Python-specific setup details
    ├── pyproject.toml
    ├── uv.lock
    ├── tests/
    │   ├── __init__.py
    │   └── test_diary.py
    └── work_diary_mcp/
        ├── __init__.py
        ├── config.py              # Data directory resolution and Jira configuration
        ├── diary.py               # State management, reminders, week helpers, persistence
        ├── jira.py                # Jira ticket auto-linking
        ├── markdown.py            # Markdown renderer
        ├── roles.py               # Engagement role definitions and normalization
        ├── server.py              # FastMCP server and tool definitions
        └── statuses.py            # Status definitions (emoji map, completion set)

______________________________________________________________________

测试

自 python/:

uv run --group dev pytest -v