Skip to main content
Glama

PIPA CLI + MCP

一个 npm 包,两种独立入口,一次安装、一次登录。管理 PIPA 的待办、清单、日程、循环任务和笔记。

0.1.2 简化授权:打开链接,点一次“同意”即可。保留 0.1.1 的登录复用、有限网络重试和内置帮助;CLI/MCP 共用登录,临时网络失败不会清除授权。自建服务需更新简洁授权页;从更旧版本升级时还需先更新稳定 refresh 的 API。

  • CLI:pipa --help,执行命令、返回结果、退出;任何能运行终端命令的 Agent 都可以调用,不需要配置 MCP。

  • MCP:pipa mcp,以标准 stdio 协议提供工具;不调用 CLI 子进程,不依赖某一家 AI 客户端。

  • 两者直接复用 HTTP 客户端和用户目录中的授权,同一系统用户、服务地址和 profile 不需要重复登录。

需要 Node.js 22+ 和 npm。当前支持原生 macOS/Windows;Windows 实机与各 AI 客户端的交互仍需分别验收,不以单元测试代替。Linux/WSL 暂未支持。

第一次用,先看这里

  1. 安装后运行 pipa --help 或 pipa help quickstart,不需要先懂 MCP,也不需要安装 Skill。

  2. 运行 pipa login,打开显示的链接,点击“同意”。以后这台电脑会自动记住登录。

  3. 运行 pipa tasks list --json 看待办,pipa notes list --json 看笔记。

可以直接对 Agent 说:

请用 PIPA 管理我的待办。先运行 pipa --help 了解命令,已知命令直接调用;需要登录时运行 pipa login,把链接交给我确认。不熟悉参数再查 pipa tools show <工具名> --json,不要每次重复登录或查询全部工具。

登录或调用失败时按输出的 message / next_action 处理;不要读取凭据文件、复制 Cookie 或自行写超时补丁。普通网络失败保留登录,稍后重试即可。

Related MCP server: extbrain

安装一次

安装已发布的版本:

npm install -g --ignore-scripts @choco9527/pipa-cli --registry=https://registry.npmjs.org
pipa --help

不想全局安装,也可以通过 npx --yes --ignore-scripts --registry=https://registry.npmjs.org @choco9527/pipa-cli --help 按需执行。npx 是下载/启动方式,不是 MCP;命令最后带 mcp 才是启动 MCP。

不依赖公共 npm 发布的方式,是从 GitHub Releases 安装同一份版本化 tarball:

npm install -g --ignore-scripts https://github.com/choco9527/pipa-mcp/releases/download/v0.1.2/pipa-cli-0.1.2.tgz
pipa --help

下载需要访问 GitHub,依赖安装需要访问 npm registry;没有 npm 账号也能安装公开包。发布资产附带 SHA-256 校验文件。安装/npx 请在可信目录和可信 Node/npm 环境中执行;项目 .npmrc、PATH 和用户 npm 配置会影响 npm,--ignore-scripts 不是安全沙箱。安装不会修改任何 AI 客户端配置,也不会读取或撤销现有 PIPA 授权。

从旧版升级

npm install -g --ignore-scripts @choco9527/pipa-cli@0.1.2 --registry=https://registry.npmjs.org
pipa --version
pipa help quickstart

已有有效登录会直接复用,不要先 logout,也不要删除 .pipa。如果旧版已清除了登录或授权确实失效,再运行一次 pipa login。常驻 MCP 需重新启动该连接器进程才能加载新版,不必重装或更改其他 Agent 配置。

使用 npx 时指定 @choco9527/pipa-cli@0.1.2,避免继续使用旧版本;有终端能力的 Agent 可以直接调用 CLI,不要求配置 MCP。

登录一次

pipa login
pipa status --json

login 显示授权链接并等待。本人打开链接,点击“同意”即可;无需输入配对码或逐项选择权限。程序不会代开浏览器或批准。已有可用登录会复用,不创建第二份授权。网页仍受 PIPA 与 Cloudflare 的登录策略保护,公开安装包不代表自动取得网站访问权。

登录后 CLI 和 MCP 共用授权,短期 access token 自动刷新。新授权有效期 365 天,刷新不延长原到期日,可随时撤销。CF 网页登录到期不等于 Agent 授权到期。

pipa logout --yes

这会撤销当前服务/profile 的共享授权,同时影响 CLI 和 MCP;不会退出网页登录或删除待办。不想使用某个 MCP 客户端时只移除该客户端的配置,不必 logout。

CLI:执行后退出

pipa --help
pipa tools list --json
pipa tools show pipa_task_create --json
pipa lists --json
pipa tasks list --json
pipa tasks get --input '{"id":"<任务 UUID>"}' --json
pipa notes list --json

tools show 返回服务端当前 Schema,复杂写入用 --input 传入完整 JSON;通用 call 也支持服务端以后新增的工具,不用等 CLI 更新。示例中的 UUID 需要替换为真实值:

pipa call pipa_task_create --input '{"operation_id":"<本次操作 UUID>","list_id":"<清单 UUID>","title":"交报告"}' --json
pipa tasks create --input @task.json --json
pipa call pipa_help --input '{"topic":"recurrence"}' --json

Windows PowerShell 可优先使用 UTF-8 JSON 文件以避免引号转义。支持 --input - 从标准输入读取;不要把凭据放进参数或输入文件。

已知命令直接调用;不需要每次先执行 status → tools list → tools show。首次使用不熟悉的参数再查一次 Schema。工具目录按服务/profile/账户/授权缓存 5 分钟;状态检查只调用轻量 /me,缓存本身不代表服务器已验证登录。

常用命令有 tasks、notes 的查询和增删改,完整入口以 --help 为准。服务器维护业务 Schema、权限和帮助,CLI 不复制业务规则。写入需要显式 operation_id,不会偷偷生成新的操作 ID;结果不确定时沿用原 ID 和原参数重试,避免重复创建。修改前先读取最新 version;循环变更先确认本次/后续/整个系列范围。

--json 向 stdout 输出一个 JSON 结果;提示写入 stderr,错误以非零退出码表示。login --json 的授权链接在 stderr,终态才输出 JSON;终端应保持运行直到完成或取消。常规 --help/--version 离线可用,不读取用户凭据。绝对时间一律 Unix 秒整数,日历语义另传 IANA 时区。

MCP:使用同一程序

支持本地 stdio MCP 的客户端,只需配置启动命令;不需要第二次安装或登录。例如 WorkBuddy、Claude Code、Cursor 的配置形态为:

{
  "mcpServers": {
    "pipa": { "command": "pipa", "args": ["mcp"] }
  }
}

Codex 使用对应的 TOML 配置:

[mcp_servers.pipa]
command = "pipa"
args = ["mcp"]

只添加 PIPA 项,不覆盖其他配置。桌面应用可能没有终端的 PATH;启动失败时,将 command 改为实际的 pipa 路径,或用绝对 Node 路径和已安装的 src/bin.mjs 路径加 mcp 参数。客户端可能要求信任 MCP,授权后如未自动发现工具,刷新工具列表或重启客户端。

MCP 未登录时提供介绍、连接、状态、断开四个工具;登录后自动发现服务器业务工具。可直接在 MCP 里 pipa_connect 登录,CLI 随后也能使用;反过来同理。直接在普通终端执行 pipa mcp 后等待输入是正常现象,它在等待 MCP 协议,不是自然语言聊天界面。

无需上架 WorkBuddy 市场即可自定义接入;当前没有市场上架或所有客户端实机验收的承诺。云端 AI 若不能执行本机程序,不能直接使用这种 stdio/CLI 方式。服务器另有远程 MCP,但本包的设备授权不是通用 OAuth 自动发现/DCR。

连接与安全

全局 --server <HTTPS源站> 和 --profile <名称> 用于明确选择服务和隔离账户,默认 https://pipa.chooco.top / default。只有同一系统用户、服务地址、profile 才共用授权;不同电脑不自动同步。HTTP 仅允许回环地址用于本地测试。

凭据保存在系统用户目录 .pipa/auth.json,是明文 JSON,不是加密文件:macOS 目录 0700、文件 0600;Windows 使用当前用户 SID 的专用 ACL,设置失败就停止。短期 access token 与 refresh token 一起保存,CLI/MCP 重开时复用,临近到期才刷新;跨进程锁合并刷新,原子替换避免半写文件。config.json 不含 Token,tools.json 仅缓存工具定义;不要手动编辑、复制、共享或把 .pipa 放入仓库/云同步目录。文件权限不防御同用户恶意程序。

状态以 pipa status --json 或 MCP pipa_connection_status 为准:

  • connected:最近服务端验证成功;unverified 只是本地有凭据。

  • expired / revoked / reconnect_required:按原因重新登录,由本人确认。

  • offline:网络暂不可用,不等于到期;保留凭据。

  • blocked:机器接口受到登录挑战或配置异常,不通过复制浏览器 Cookie 绕过。

短期 access 到期时自动刷新;refresh 凭据在原授权期限内保持稳定,可随时从网页撤销。刷新网络失败最多重试一次,仍失败则保留登录,之后重试原命令即可,不因超时要求重新授权。明确撤销/过期/凭据无效才清理连接。用户取消不重试,不忽略取消或无限等待。稳定 refresh 被窃取后在撤销/到期前仍可使用,因此不要共享凭据文件。

业务写入的网络重试只在有有效 operation_id 时进行,参数保持不变,避免重复创建。

刷新单次请求最多 15 秒,业务请求最多 35 秒;没有四分钟等待或无限重试。错误的 diagnostics 可包含请求 ID、CF Ray、耗时和安全网络错误码,不含请求正文、Token 或原始异常文本。MCP 的 isError: true 或 CLI 非零退出码都不代表业务写入成功。

可选 PIPA Skill 提供操作规则,不参与鉴权,也不要求特定 AI 产品。仅支持命令行的 Agent 读 --help 即可。

开发

独立仓库:npm ci --ignore-scripts、npm test、npm run pack:check。 PIPA 主仓库中:pnpm --filter @choco9527/pipa-cli test;直接执行 node packages/pipa-mcp/src/bin.mjs --help。

许可证:MIT。公开仓库只包含客户端、测试和说明,不包含 PIPA 服务器源码、私有仓库历史或用户凭据。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable AI clients to read and write a self-hosted todo list, quick memos, and a plain-Markdown knowledge base through 16 tools covering search, tasks, notes, and identity checks. Tool visibility is scoped per API key with directory-level permissions, and every call is audit-logged.
      5
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants like Claude, Cursor, VS Code, and Windsurf to manage workspaces, projects, tasks, and AI agents through natural language, with a hosted OAuth server or a local stdio package. Also supports generating MCP tools from any OpenAPI spec.
      2,530 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI clients such as Claude, Cursor, VS Code, and Windsurf to list and manage workspaces, projects, tasks, AI agents, and automations through a hosted OAuth-secured endpoint or a local stdio package. Also generates MCP tools from any OpenAPI spec.
      2,530 npm
      MIT