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 :
| 命令 | 描述 |
|---|---|
init | 完整设置向导（登录+配置Claude代码） |
login | 与Joan进行身份验证（打开浏览器） |
logout | 清除存储的凭据 |
status | 显示身份验证状态 |
serve | 启动MCP服务器（默认） |
help | 显示帮助消息 |
可用工具
这些工具允许AI助手修改Joan中的数据：
任务工具
| 工具 | 说明 |
|---|---|
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 | 从里程碑中删除任务 |
目标工具
| 工具 | 说明 |
|---|---|
create_goal | 创建新目标 |
update_goal | 更新目标标题、状态、进度 |
delete_goal | 删除目标 |
link_task_to_goal | 链接任务以跟踪进度 |
unlink_task_from_goal | 从目标中删除任务 |
笔记工具
| 工具 | 说明 |
|---|---|
create_note | 创建新笔记 |
update_note | 更新笔记内容和元数据 |
delete_note | 删除注释 |
可用资源
这些资源提供对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
许可证
麻省理工学院