AimYear

AimYear MCP 服务

在你已使用的 AI Agent 中担任督促伙伴。 将 AimYear 连接到 Claude、Claude Code、ChatGPT 或任何 MCP 客户端，让你的 Agent 为这一年设定一个重要目标，每天规划一个主要步骤，工作时启动计时器，并记录实际完成的事项。当主要步骤尚未完成，而你开始做轻松的工作时，它会提醒你先完成这一步。

专为独立开发者和创作者打造：他们整天忙于开发，却总是推迟那些能推动目标实现的工作，例如销售、与用户交流和发布内容。

• 免费版： 可在任意数量的设备上登录，通过你自己的 Agent 管理目标、计划、日常安排、时间记录和回顾。AimYear 不会在自身平台上运行 AI，因此不会产生 AI 费用。
• Pro（每年 $49 或每月 $8，即将推出手机应用）：通知、由 AimYear 撰写的回顾、AimYear 自带的 AI 教练以及 Google Calendar 同步。

网站：aimyear.com · 设置指南：aimyear.com/connect.html · 隐私：aimyear.com/privacy.html · 联系方式：[email protected]

连接（约一分钟）

端点：https://mcp.aimyear.com/mcp（Streamable HTTP，通过 Google、Apple 或电子邮件 OAuth 登录）。无需安装任何内容。

• Claude（网页、桌面、移动端）： 设置 → 连接器 → 添加自定义连接器 → 粘贴端点 → 连接，然后登录。
• Claude Code： claude mcp add --transport http aimyear https://mcp.aimyear.com/mcp，然后选择 /mcp → aimyear → Authenticate。
• ChatGPT（付费套餐，开发者模式）：设置 → 应用与连接器 → 高级设置 → 开启开发者模式。然后选择应用与连接器 → 创建：名称填写 AimYear，URL 填写上方的端点，身份验证选择 OAuth → 创建，然后登录。
• 其他 MCP 客户端： 将该端点添加为使用 OAuth 的远程（HTTP）服务。

然后说：“帮我设定今年的目标。” Agent 会检查目标是否可量化，制定阶段路径，此后你可以说：“规划我的一天”、“启动计时器”、“我这周过得怎么样？”。

教 Agent 使用这套方法的技能文件位于 skills/aim/SKILL.md。

你的数据会如何处理

服务会将 Agent 通过工具保存的内容（目标、路径、计划、工作时段及其摘要）存储在 Google Cloud Firestore 中。你的对话会保留在 Agent 提供商处；AimYear 只会收到工具调用。日志会记录工具名称、成功状态和耗时，不会记录参数值。如需删除账户和数据，请发送电子邮件至 [email protected]。详情请见：隐私政策。

工具（43）

名称说明了工具的用途：get_ 用于读取一项内容，list_ 用于读取多项内容，find_ 用于查找问题，set_ 用于替换整个列表，add_ / edit_ / delete_ 用于更改单个条目。

分组	工具
目标	get_goal, check_goal_draft, set_goal, record_progress, set_levers, set_projects
路径	get_path, set_milestones, edit_milestone, add_steps, edit_step, delete_step, next_steps
每周	get_commitments, set_commitments, get_capacity
每日	get_planning_context, get_plan, set_plan, edit_plan_item, delete_plan_item, set_day_mode, get_routines, set_routines
计时器和会话	get_now, start_session, add_note, split_attention, stop_session, stop_timer, add_session, edit_session, delete_session, list_sessions, find_gaps
回顾	summarize_day, summarize_week, find_leaks
设置和设备	get_settings, set_settings, add_device, list_devices, delete_device

0.4.2 增加了优先处理难事的检查：如果当天没有任何事项属于高难度杠杆，set_plan 会发出警告；如果某个阶段从准备工作开始，且第一步不是高难度杠杆事项，add_steps / set_levers 也会发出警告。服务端指令会向每个 Agent 说明同一条规则。

0.4.0 增加了例行事项：在固定星期几重复执行的小步骤（“在 Reddit 上和一个人交流”）。服务端会将它们添加到每个符合条件的日期计划中，因此每台设备和每个 Agent 看到的检查项都相同；get_now 会列出尚未完成的例行事项，summarize_week 会统计它们。

0.3.0 重命名了大多数工具（旧的 0.2.x 名称将无法使用），并增加了编辑工具：用于已完成会话的 edit_session、delete_session，以及 edit_milestone、delete_step、edit_plan_item、delete_plan_item、set_projects 和包含时区设置的 get_settings / set_settings。

协议详情

无状态 Streamable HTTP，仅支持 POST。登录采用 OAuth 2.1、PKCE 和动态客户端注册。登录页面使用与 AimYear 应用相同的 Firebase 项目，因此该应用和每个已连接的 AI 共用一个账户和一份历史记录。访客（匿名）账户无法连接。每个工具都以一个已登录用户的身份运行；请参阅 docs/ACCESS.md。

没有令牌时，服务端会描述自身（initialize、tools/list、prompts/list、ping）；其他所有请求都会返回带有 WWW-Authenticate 标头的 401，该标头指向 /.well-known/oauth-protected-resource/mcp。

面向应用的重试安全写入（0.7）

服务端是事实来源。手机可能在用户点击很久之后才送达请求，也可能送达两次。因此，stop_session、start_session、add_session、add_note、add_steps 和 delete_session 都接受可选的 op_id：应用在首次尝试前生成的 ID，并在每次重试时重复使用。写入只会应用一次；重试会收到首次请求的响应，不会写入任何内容。已应用的操作存储在 users/{uid}/ops/{op_id}（tool、sessionId、result、at、expiresAt）中，并与它们记录的变更在同一个 Firestore 事务中写入。请在 Firestore 控制台为 ops 集合的 expiresAt 设置 TTL 策略（30 天）。

stop_session 接受 end_at，start_session 接受 start_at（ISO 8601），因此，14:05 离线排队、16:40 才送达的停止请求会记录为 14:05。start_session 还接受应用自己的 session_id（仅在不存在时创建）。包含 op_id、end_at 或 start_at 的请求必须指定其 session_id：服务端绝不会猜测重放请求指的是哪个会话。未指定这些参数时，Agent 的 stop_session / delete_session 只会操作其自身连接上的单个运行中会话；否则会列出带 ID 的运行中会话。

两台设备可以停止同一个会话；无论停止请求以何种顺序送达，结果都相同：结束时间最早的请求生效（一旦有人停止会话，它就不再处于运行状态），done 优先于任何其他结果，第一个摘要会保留，之后不同的摘要会添加到笔记中。每次停止都会保存在会话的 stops[] 中，响应会说明 applied: ended | shortened | recorded。

---

本文件其余部分介绍服务器本身的开发工作。使用 AimYear 无需阅读这些内容。

构建方式

文件	功能
src/http.ts	Express 应用：MCP 端点、OAuth 路由和菜单栏端点。
src/access.ts	一张表列出每个 MCP 方法、工具和路由 → public / auth / admin，并说明原因。所有访问控制都会读取该表。
src/oauth.ts	Firestore 中的 OAuth 存储（代码和令牌以 SHA-256 哈希值存储），以及登录 / 授权页面。协议本身使用 MCP SDK 的 mcpAuthRouter。
src/calllog.ts	每次 MCP 调用记录一行结构化日志：method、tool、ok、error code、latency、user、client。绝不记录参数值。
src/tools.ts	工具注册、注释（只读 / 破坏性 / 幂等）以及服务器指令。
src/service.ts、src/domain/	规则：目标评估标准、分类、注意力、计划和会话。
src/surface.ts	surface.lock.json 背后的界面指纹。
.githooks/pre-commit	每次提交时从 src/access.ts 重新生成 docs/ACCESS.md 并将其暂存，确保已提交的表格不会过时（npm ci 通过 prepare 脚本将 core.hooksPath 指向此钩子；若文件过时，test/access.test.ts 仍会报错）。

数据存储在 Firestore 的 users/{uid}/aim/{goal,path,profile}、users/{uid}/days、 users/{uid}/sessions、users/{uid}/blocks、users/{uid}/ops 中（已应用的 op_id，expiresAt 上设置 TTL）；OAuth 数据存储在 oauth_clients、oauth_requests、oauth_codes、oauth_tokens 中；提醒存储在 pending_notifications 中（每次推送前通过事务性删除认领）。

本地运行

npm install && npm run build
# stdio, one person:
claude mcp add --scope user aimyear -e AIMYEAR_UID=<firebase uid> -- node $PWD/dist/index.js
# HTTP:
AIMYEAR_TOKENS="sometoken=<uid>" PORT=8787 node dist/index.js --http

凭据：Firebase 管理员服务账号，位于 ~/.aimyear/service-account.json（或使用 AIMYEAR_SERVICE_ACCOUNT=<path>；如果未设置，则回退到 Application Default Credentials）。

环境变量：AIMYEAR_UID（stdio）、AIMYEAR_TOKENS（HTTP：供 Claude Code 脚本、菜单栏应用和调度器使用的静态 token=uid 配对）、AIMYEAR_BASE_URL（公共 URL；OAuth issuer）、AIMYEAR_ALLOWED_ORIGINS（额外的浏览器来源）、AIMYEAR_WORKPLACE、AIMYEAR_TZ。

测试

npm test                  # access table guard, anonymous gate and batch smuggling, OAuth discovery,
                          # annotations, Origin, version negotiation, surface lock, domain rules
npm run test:conformance  # a client's path through the real HTTP entry point: initialize and
                          # tools/list without a token, then every tool with a throwaway user
                          # in the real Firestore; cleans up
CONFORMANCE_URL=https://mcp.aimyear.com/mcp npm run test:conformance   # read-only tools, live
npm run test:oauth        # register → consent → real Firebase ID token → code → token (PKCE) →
                          # tool call → refresh rotation, plus every refusal; cleans up
npx tsx test/smoke.ts     # the service end to end against Firestore

添加工具时：在 src/access.ts 中为其添加条目（缺少条目时 npm test 会失败），运行 npm run access-doc，更新 src/version.ts，再运行 npm run surface-lock。

托管（Cloud Run）

gcloud run deploy aimyear-mcp --source . --project aimyear-app --region us-central1 --quiet

服务上的环境变量：AIMYEAR_TOKENS、AIMYEAR_TZ、AIMYEAR_PROJECT、 AIMYEAR_BASE_URL=https://mcp.aimyear.com。mcp.aimyear.com 是 Cloud Run 域名映射 （在 Route 53 中通过 CNAME 指向 ghs.googlehosted.com），并已添加到 Firebase Auth 的授权域名中。 健康检查：/health。旧版 URL https://<service>/c/<token>/mcp 仍可使用。

调用分析：scripts/mcp-calls.sh [1d] 会按工具统计调用次数，并列出每个人和客户端的调用序列。

许可证

FSL-1.1-MIT：你可以阅读、运行、可自托管并修改此服务，但不得将其作为竞争性商业服务提供。每个版本发布两年后将改为 MIT 许可证。托管服务位于 https://mcp.aimyear.com/mcp。