TimeLiner MCP Server

TimeLiner 项目管理系统的 MCP (Model Context Protocol) Server，让 AI 客户端通过 MCP 协议操控项目管理。

前置条件

• Python 3.11+
• TimeLiner 后端服务运行在 localhost:8080
• 安装依赖：

cd TimeLiner/mcp_server
pip install -r requirements.txt

启动后端

cd TimeLiner/backend
uvicorn main:app --reload --port 8080

客户端接入

stdio 模式（推荐）

适用于 Claude Desktop、Cursor、Kiro 等本地 AI 客户端。

在客户端 MCP 配置文件中添加（通过环境变量传入用户名密码，连接时自动登录）：

{
  "mcpServers": {
    "timeliner": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "D:/demo/TimeLiner",
      "env": {
        "TIMELINER_BACKEND_URL": "http://localhost:8080/api",
        "TIMELINER_USERNAME": "li.ming.pm",
        "TIMELINER_PASSWORD": "Demo@12345"
      }
    }
  }
}

配置文件位置：

客户端	路径
Claude Desktop	%APPDATA%/Claude/claude_desktop_config.json
Kiro	.kiro/settings/mcp.json
Cursor	.cursor/mcp.json

SSE 模式（远程/多客户端）

cd TimeLiner
TIMELINER_USERNAME=li.ming.pm TIMELINER_PASSWORD=Demo@12345 \
  python -m mcp_server.server --transport sse --port 8888

客户端配置：

{
  "mcpServers": {
    "timeliner": {
      "url": "http://localhost:8888/sse"
    }
  }
}

鉴权说明

• 配置 TIMELINER_USERNAME + TIMELINER_PASSWORD 环境变量后，MCP Server 启动时自动登录，无需手动调用 login
• 如果未配置环境变量，可以通过 login tool 手动登录
• 已登录状态下调用 login 可切换用户身份
• 调用 whoami 可查看当前登录状态

环境变量

变量	默认值	说明
TIMELINER_BACKEND_URL	http://localhost:8080/api	后端 API 地址
TIMELINER_REQUEST_TIMEOUT	30	HTTP 请求超时（秒）
TIMELINER_USERNAME	(空)	自动登录用户名
TIMELINER_PASSWORD	(空)	自动登录密码

Tool 清单（47 个）

认证（3）

Tool	说明	角色
login	手动登录 / 切换用户（通常不需要）	Public
get_current_user	获取当前用户信息	Both
whoami	查看当前登录状态	Public

项目管理（6）

Tool	说明	角色
create_project	创建项目	Admin
list_projects	列出项目	Both
get_project	项目详情	Both
update_project	更新项目	Admin
delete_project	删除项目	Admin
get_project_dashboard	时间线仪表盘	Both

任务管理（8）

Tool	说明	角色
create_task	创建任务	Admin
list_tasks	列出任务	Both
get_task	任务详情	Both
update_task	更新任务	Admin
delete_task	删除任务	Admin
add_task_dependency	添加依赖	Admin
ai_split_task	AI 拆分任务	Admin
confirm_and_distribute_tasks	批量分发任务	Admin

成员管理（6）

Tool	说明	角色
add_member	添加成员	Admin
list_members	列出成员	Both
get_member	成员详情	Both
update_member	更新成员	Admin
remove_member	移除成员	Admin
list_member_skills	查看技能	Both

技能管理（2）

Tool	说明	角色
add_member_skill	添加技能	Admin
remove_member_skill	移除技能	Admin

里程碑（5）

Tool	说明	角色
create_milestone	创建里程碑	Admin
list_milestones	列出里程碑	Both
get_milestone	里程碑详情	Both
update_milestone	更新里程碑	Admin
delete_milestone	删除里程碑	Admin

邀请管理（4）

Tool	说明	角色
create_invitation	创建邀请码	Admin
list_invitations	查看邀请列表	Admin
revoke_invitation	撤销邀请	Admin
accept_invitation	接受邀请	User

调度管理（5）

Tool	说明	角色
list_schedule_requests	查看调度申请	Admin
approve_schedule_request	批准申请	Admin
reject_schedule_request	拒绝申请	Admin
request_schedule_change	发起调度申请	User
get_my_schedule_requests	查看我的申请	User

决策（2）

Tool	说明	角色
validate_decision	验证决策	Admin
apply_decision	应用决策	Admin

用户任务（4）

Tool	说明	角色
get_my_tasks	我的任务列表	User
get_today_goals	今日目标	User
submit_task_completion	提交完成	User

上下文查询（3）

Tool	说明	角色
get_project_context	项目 Markdown 上下文	Both
get_task_context	任务 Markdown 上下文	Both
get_project_activities	项目活动日志	Both

典型使用流程

Admin：AI 辅助任务拆分

连接时已自动登录（env 配置 li.ming.pm / Demo@12345），直接使用：

1. create_project("用户认证模块", "2026-04-01T00:00:00Z", "2026-05-01T00:00:00Z")
2. add_member(project_id, "张三")
3. ai_split_task(project_id, "实现登录、注册、密码重置、OAuth2")
   → 返回 prompt，客户端 LLM 生成子任务方案
4. confirm_and_distribute_tasks(project_id, task_plan)
   → 批量创建任务、设依赖、验证、应用决策

User：日常任务管理

连接时已自动登录（env 配置 chen.yan.dev / Demo@12345），直接使用：

1. get_today_goals(project_id)
   → 按优先级 + 关键路径排序的待办任务
2. update_task(task_id, progress=0.6, status="InProgress")
3. submit_task_completion(task_id)

运行测试

cd TimeLiner
python -m pytest mcp_server/tests/ -v

架构说明

MCP Client (Claude/Cursor/Kiro)
    ↕ MCP 协议 (stdio/SSE)
MCP Server (FastMCP)
    ↕ HTTP (httpx)
TimeLiner Backend (FastAPI :8080)
    ↕ SQLAlchemy
PostgreSQL / SQLite

MCP Server 不直接访问数据库，所有操作通过后端 HTTP API 完成，保持架构分层。