关键词

待办事项管理时间追踪LLM应用后端GTD多用户

项目简介

Eddo MCP 服务器是 Eddo GTD (Getting Things Done) 风格待办事项和时间追踪应用的核心后端组件。它实现了 Model Context Protocol (MCP)，允许大型语言模型 (LLM) 客户端以结构化方式访问和管理用户的待办事项、时间记录及相关上下文信息。该服务器支持多用户隔离、数据迁移、以及通过 JSON-RPC 协议进行工具调用和资源管理。

主要功能点

  • 待办事项管理: 支持创建、读取、更新、删除待办事项（Todo），并可按 GTD 上下文、完成状态、日期范围和标签进行筛选。
  • 时间追踪: 允许用户启动、停止待办事项的时间追踪，并查询当前所有正在进行时间追踪的待办事项。
  • 任务完成与重复: 支持将待办事项标记为完成或未完成，并能根据预设的重复规则自动创建新的重复任务。
  • 智能上下文: 服务器提供 GTD 标签指导、上下文（如“工作”、“私人”）、记忆存储等，帮助 LLM 理解和执行复杂指令。
  • 用户隔离: 每个用户拥有独立的数据库，确保数据安全和隐私。
  • 认证授权: 通过请求头中的用户身份信息进行认证，确保只有授权用户能访问其数据。
  • 数据模型: 使用 'TodoAlpha3' 数据模型，并支持自动数据迁移。
  • 分析报告: 提供服务器信息、数据模型说明、使用示例以及热门标签统计等分析功能，辅助 LLM 进行更智能的决策。

安装步骤

  1. 环境准备: 确保您的系统已安装 Node.js (≥18.11.0) 和 pnpm (≥7.1.0)。
  2. 克隆仓库: 使用 Git 克隆 Eddo 仓库。 
    git clone https://github.com/walterra/eddoapp.git
cd eddoapp
  3. 安装依赖: 在项目根目录运行以下命令安装所有依赖。 
    pnpm install
  4. 配置环境变量:
    • 复制 '.env.example' 文件到 '.env'。
    • 配置 'COUCHDB_URL'（CouchDB 数据库的 URL，例如 'http://admin:password@localhost:5984'）。
    • 配置 'JWT_SECRET'（用于认证的 JWT 密钥，至少 32 个字符）。
    • （可选）为测试环境配置 'COUCHDB_TEST_URL', 'COUCHDB_TEST_DB_NAME', 'MCP_TEST_PORT'。
  5. 启动 MCP 服务器: 
    pnpm dev
    此命令会同时启动 Web 客户端和 MCP 服务器。MCP 服务器将运行在 'http://localhost:3001/mcp' (或 'MCP_TEST_PORT' 指定的端口)。 如果您只想启动 MCP 服务器，可以使用以下命令： 
    pnpm --filter @eddo/mcp-server start
    在开发模式下，您也可以直接运行： 
    pnpm dev:mcp-server

服务器配置 (供MCP客户端连接使用)

MCP 客户端需要以下配置信息来连接 Eddo MCP 服务器。以下是一个 JSON 格式的示例配置：

{
  "name": "eddo-mcp-server",
  "command": "pnpm",
  "args": ["--filter", "@eddo/mcp-server", "start"],
  "url": "http://localhost:3001/mcp",
  "protocolVersion": "0.1.0",
  "env": {
    "COUCHDB_URL": "http://admin:password@localhost:5984",
    "JWT_SECRET": "your-strong-jwt-secret-here-at-least-32-chars",
    "NODE_ENV": "production"
  },
  "capabilities": {
    "tools": {
      "createTodo": {
        "description": "Create a new todo item.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "listTodos": {
        "description": "List todos with optional filters.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "updateTodo": {
        "description": "Update an existing todo.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "toggleTodoCompletion": {
        "description": "Mark a todo as completed or uncompleted.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "deleteTodo": {
        "description": "Delete a todo permanently.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "startTimeTracking": {
        "description": "Start tracking time for a todo.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "stopTimeTracking": {
        "description": "Stop tracking time for a todo.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "getActiveTimeTracking": {
        "description": "Get todos with active time tracking.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "getUserInfo": {
        "description": "Get current authenticated user information.",
        "inputSchema": { /* 实际的 Zod schema */ }
      },
      "getServerInfo": {
        "description": "Get comprehensive information about the Eddo MCP server.",
        "inputSchema": { /* 实际的 Zod schema */ }
      }
    }
  },
  "headers": {
    "X-User-ID": "your_username",     // 您的用户名，用于标识用户
    "X-Database-Name": "eddo_user_your_username", // 用户专属数据库名称，通常格式为 'eddo_user_<username>'
    "X-Telegram-ID": "your_telegram_id" // 您的 Telegram ID (如果已绑定)
  }
}

配置参数注释:

  • 'name': MCP 服务器的名称，例如 'eddo-mcp-server'。
  • 'command': 启动 MCP 服务器的命令，例如 'pnpm'。
  • 'args': 传递给启动命令的参数列表。'--filter @eddo/mcp-server start' 会启动 'eddoapp' monorepo 中的 MCP 服务器包。
  • 'url': MCP 服务器的访问地址，默认情况下是 'http://localhost:3001/mcp'。
  • 'protocolVersion': MCP 协议版本，当前示例中为 '0.1.0'。
  • 'env': 启动服务器时所需的环境变量。
    • 'COUCHDB_URL': CouchDB 数据库的连接 URL，格式通常为 'http://username:password@host:port'。
    • 'JWT_SECRET': 用于用户认证的密钥，必须与 'packages/web-api' 中的配置一致。
    • 'NODE_ENV': 运行环境，例如 'production' 或 'development'。
  • 'capabilities.tools': 服务器声明支持的工具列表及其描述和输入 Schema。MCP 客户端可以根据这些信息了解服务器提供的功能。
    • 'createTodo': 创建待办事项。
    • 'listTodos': 列出待办事项（支持多种筛选）。
    • 'updateTodo': 更新待办事项。
    • 'toggleTodoCompletion': 切换待办事项完成状态。
    • 'deleteTodo': 删除待办事项。
    • 'startTimeTracking': 启动待办事项时间追踪。
    • 'stopTimeTracking': 停止待办事项时间追踪。
    • 'getActiveTimeTracking': 获取所有正在进行时间追踪的待办事项。
    • 'getUserInfo': 获取当前认证用户的信息。
    • 'getServerInfo': 获取 MCP 服务器的详细信息和文档。
  • 'headers': MCP 客户端在进行工具调用时需要额外发送的 HTTP 请求头，用于用户认证和数据隔离。
    • 'X-User-ID': 客户端用户在 Eddo 系统中的唯一用户名。
    • 'X-Database-Name': 客户端用户对应的 CouchDB 数据库名称，通常由 'eddo_user_' 前缀和用户名组成。
    • 'X-Telegram-ID': 客户端用户绑定的 Telegram 用户 ID（如果适用）。

基本使用方法

启动服务器后，您可以通过 MCP 客户端（如 Eddo Telegram Bot 或其他定制的 LLM 客户端）来与它交互。

通过 MCP 客户端调用工具 (示例 JSON-RPC 请求体): 要调用 'createTodo' 工具，创建一个 JSON-RPC 请求，包含工具名称和参数。

{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "createTodo",
    "arguments": {
      "title": "提交季度报告",
      "description": "包含销售分析和未来预测",
      "context": "work",
      "due": "2025-06-30T17:00:00.000Z",
      "tags": ["报告", "紧急"],
      "repeat": null,
      "link": null
    }
  },
  "id": 1
}

客户端需在 HTTP 请求头中包含以下认证信息:

  • 'X-User-ID: your_username'
  • 'X-Database-Name: eddo_user_your_username'
  • 'X-Telegram-ID: your_telegram_id' (如果需要)

通过 Telegram Bot 交互: Eddo 项目提供了 Telegram Bot 作为 MCP 服务器的一个主要客户端。用户可以通过与 Bot 自然语言对话来管理待办事项。例如：

  • "添加一个明天上午10点的会议待办"
  • "列出我所有工作相关的待办"
  • "启动 '提交季度报告' 的时间追踪"

信息

分类

生产力应用

访问项目