使用说明
Joan MCP服务器
Joan生产力应用程序的模型上下文协议（MCP）服务器。使Claude Code等人工智能助手能够与您的项目、任务、目标、里程碑和笔记进行交互。
特性
- 读写访问：项目、任务、目标、里程碑和注释的完整CRUD操作
- 安全认证：使用加密令牌存储通过浏览器登录
- Claude代码集成：与Claude Code和其他MCP客户端无缝协作
- 自我描述：通过MCP协议自动向AI助手提供使用说明
- API生产：直接连接到您的Joan帐户数据
共享规格
- 交叉代理工作流程和MCP/neneneba API校准现场
shared/joan-shared-specs. - 回购文件：
shared/joan-shared-specs/docs/joan-mcp/README.md.
安装
选项1:npx（推荐-无需安装）
npx @pollychrome/joan-mcp init
此单个命令将：
- 打开浏览器与Joan进行身份验证
- 将凭据安全地存储在您的计算机上
- 自动配置Claude代码
选项2：全局安装
npm install -g @pollychrome/joan-mcp
# Then run:
joan-mcp init
选项3：来源（开发）
git clone https://github.com/pollychrome/joan-mcp.git
cd joan-mcp
npm install
npm run build
npm link
joan-mcp init
快速开始
npx @pollychrome/joan-mcp init
在设置之后， 重新启动克劳德代码 你准备好了！
在任何项目中使用Joan MCP
一旦你跑了 npx @pollychrome/joan-mcp init，Joan会自动全局配置。它工作在 任何项目 无需额外设置。
示例提示
在处理任何代码库时，你可以说：
"Create a task in Joan for the bug I just found"
"Show me my Joan projects"
"Add a note in Joan about this architecture decision"
"Mark my 'Review PR #42' task as completed"
"What tasks do I have in my Backend project?"
"Create a milestone called 'v2.0 Release' in Joan"
运作原理
Joan MCP 自我描述 -它自动告诉克劳德密码：
- 琼是什么，它做什么
- 所有可用工具及其参数
- 所有可用资源和URI
- 有效字段值（状态、优先级等）
CLAUDE.md文件中不需要手动文档。
手动配置（可选）
这个 init 命令会自动配置，但如果需要，请运行：
claude mcp add joan -s user -- joan-mcp serve
这将Joan MCP添加到您的用户配置中，使其在所有项目中都可用。
故障排除
Joan MCP不工作：
- 完全重新启动Claude代码
- 跑
npx @pollychrome/joan-mcp status检查身份验证 - 跑
npx @pollychrome/joan-mcp login重新验证
CLI命令
所有命令都可以用 npx @pollychrome/joan-mcp <command>:
| 命令 | 描述 |
|---|---|
init |
完整设置向导（登录+配置克劳德代码+安装计划日技能） |
login |
与Joan进行身份验证（打开浏览器） |
logout |
清除存储的凭据 |
status |
显示身份验证状态 |
install-skill |
安装/刷新 plan-day Claude代码技能(~/.claude/skills/plan-day) |
serve |
启动MCP服务器（默认） |
help |
显示帮助消息 |
可用工具
这些工具允许AI助手修改Joan中的数据：
任务工具
| 工具 | 说明 |
|---|---|
search_tasks |
在创建重复项之前，按文本（标题/描述）搜索现有任务以解决提及问题 |
create_task |
创建新任务（根据状态自动放置在匹配列中） |
update_task |
更新任务（状态更改时自动同步列） |
complete_task |
标记为已完成并移至“完成”列 |
delete_task |
删除任务 |
bulk_update_tasks |
在单个事务中更新多个任务 |
项目工具
| 工具 | 说明 |
|---|---|
create_project |
创建新项目 |
update_project |
更新项目名称、描述、状态 |
list_columns |
列出项目的看板列 |
里程碑工具
| 工具 | 说明 |
|---|---|
create_milestone |
在项目中创建里程碑 |
update_milestone |
更新里程碑详细信息 |
delete_milestone |
删除里程碑 |
link_tasks_to_milestone |
将任务链接到里程碑 |
unlink_task_from_milestone |
从里程碑中删除任务 |
目标工具
| 工具 | 说明 |
|---|---|
list_goals |
列出目标的类型、状态和进度（对日常计划有用） |
create_goal |
创建新目标 |
update_goal |
更新目标标题、状态、进度 |
delete_goal |
删除目标 |
link_task_to_goal |
链接任务以跟踪进度 |
unlink_task_from_goal |
从目标中删除任务 |
日常计划工具
这些工具为日常计划仪式提供动力。服务器打包计划 确定性地 根据优先级排序的项目列表和实际系统时钟 值——它从不猜测时间。结果是暂定的 草稿；用户 最后拖动是否重新排序并在中确认 Joan应用程序.
| 工具 | 说明 |
|---|---|
get_daily_plan |
获取特定计划 本地 日期（服务器为UTC，始终传递本地日期） |
generate_daily_plan |
根据优先级排序的项目+实际时钟值生成暂定的草稿计划 |
update_daily_plan |
替换现有计划的完整项目列表并重新打包 |
confirm_daily_plan |
确认计划草案（仅在用户明确要求时；应用程序是主要的确认界面） |
笔记工具
| 工具 | 说明 |
|---|---|
create_note |
创建新笔记 |
update_note |
更新笔记内容和元数据 |
delete_note |
删除注释 |
计划你的一天技能
Joan MCP发送克劳德密码 技能 被称为 plan-day 它会带你走过
将“我今天想做的事情”变成一个具体的、有时间顺序的计划
琼。它收集你的意图，将其分解为实际任务（之前搜索
创建以避免重复）、设置锚点和持续时间以及调用
使用日常计划工具生成草稿。
安装它 （也由自动完成 init):
npx @pollychrome/joan-mcp install-skill
这将技能复制到 ~/.claude/skills/plan-day，覆盖以前的任何内容
复制，使其与安装的软件包保持同步。
用它 在Claude Code中，通过运行斜线命令：
/plan-day
或者只是说类似的话 “帮我计划我的一天”, “我应该做什么 今天？"，或 “计划我的一天”.Claude读取您的真实本地日期/时间，检查 一个现有的计划，帮助你选择任务和设定时间，并生成一个暂定的 草案。您进行最后的拖动重新排序，并在 Joan应用程序.
可用资源
这些资源提供对Joan数据的只读访问：
| 资源URI | 描述 |
|---|---|
joan://projects |
列出所有项目 |
joan://projects/{id} |
项目详细信息和统计数据 |
joan://projects/{id}/tasks |
项目中的任务 |
joan://projects/{id}/milestones |
项目里程碑 |
joan://projects/{id}/columns |
看板栏 |
joan://projects/{id}/analytics |
项目分析 |
joan://tasks |
所有用户任务 |
joan://tasks/{id} |
任务详细信息 |
joan://goals |
所有目标 |
joan://goals/{id} |
具有链接任务的目标 |
joan://goals/{id}/stats |
目标统计 |
joan://notes |
所有笔记 |
joan://notes/{id} |
注释详细信息 |
状态和列同步
Joan使用两个并行系统来处理任务状态：
- 状态:
todo,in_progress,done,cancelled - 列：看板栏（例如“待办事项”、“进行中”、“完成”）
默认情况下，MCP服务器 自动同步 这些：
| 行动 | 行为 |
|---|---|
create_task 带状态 |
将任务放置在匹配列中 |
update_task 状态更改 |
将任务移动到匹配的列 |
complete_task |
设置状态并移动到“完成”列 |
禁用自动同步
所有任务工具都支持 sync_column 参数（默认值： true):
// Only update status, don't move column
update_task(task_id: "...", status: "done", sync_column: false)
// Only mark complete, don't move to Done column
complete_task(task_id: "...", sync_column: false)
列覆盖
提供明确的 column_id 始终优先于自动同步：
// Move to specific column regardless of status
update_task(task_id: "...", status: "done", column_id: "custom-column-id")
发展
以开发模式运行
cd mcp-server
npm run dev
类型检查
npm run typecheck
构建
npm run build
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
JOAN_AUTH_TOKEN |
JWT身份验证令牌 | （来自登录） |
JOAN_API_URL |
API基本URL | https://joan-api.alexbbenson.workers.dev/api/v1 |
JOAN_MCP_TIMEOUT_MS |
HTTP请求超时（毫秒） | 10000 |
JOAN_MCP_CONNECT_TIMEOUT_MS |
MCP握手超时（ms） | 30000 |
JOAN_MCP_SLOW_REQUEST_MS |
慢速请求的日志警告（毫秒） | （已禁用） |
JOAN_MCP_LOG_LEVEL |
记录冗长(debug, info, warn, error, silent) |
info |
JOAN_MCP_VERIFY_ON_STARTUP |
在以下情况下跳过后台身份验证检查 false |
true |
安全
- 身份验证令牌在静止时使用AES-256-GCM进行加密
- 代币存储在
~/.joan-mcp/credentials.json具有受限权限（600） - 代币在7天后过期
- 您可以从Joan个人资料设置中撤销MCP访问权限
故障排除
“身份验证失败”
npx @pollychrome/joan-mcp logout
npx @pollychrome/joan-mcp login
“令牌已过期”
代币在7天后过期。跑 npx @pollychrome/joan-mcp login 重新验证。
MCP服务器未连接
- 完全重新启动Claude代码
- 检查状态：
npx @pollychrome/joan-mcp status - 重新运行安装程序：
npx @pollychrome/joan-mcp init
许可证
麻省理工学院
