# @monadsag/productive-mcp 中文文档

规范地址：https://npmcn.com/package/%40monadsag/productive-mcp/

版本：1\.2\.62
npm 元数据更新时间：2026-11-01T21:00:10.324Z
中文译文更新时间：2026-11-01T22:43:55.749Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40monadsag/productive-mcp
原文对照：https://npmcn.com/package/%40monadsag/productive-mcp/?lang=original
项目主页：https://github.com/MonadsAG/monads-mcp-productive#readme
源码仓库：https://github.com/MonadsAG/monads-mcp-productive

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：665 kB，65 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：3 个
- 首次发布：2026-10-05T11:16:00.747Z
- 最新版本发布：2026-11-01T21:00:10.009Z
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

用于生产的MCP服务器。io API集成

## 安装

```sh
npm install @monadsag/productive-mcp
```

也可以使用：`pnpm add @monadsag/productive-mcp`、`yarn add @monadsag/productive-mcp`、`bun add @monadsag/productive-mcp`

## README

# 生产力。io远程MCP服务器

一、 **远程MCP服务器** 用于 [Productive.io](https://productive.io/) 上运行的 **Cloudflare工人**． 连接克劳德桌面，克劳德代码和其他mcp兼容的客户端到您的生产力。io工作空间-没有本地安装，客户端机器上没有API密钥。

## 突出了

-   **Remote-first** -运行在Cloudflare Workers上，客户端通过URL连接
-   **微软Entra ID** - OAuth 2.1与您组织的身份提供者（SSO + MFA）
-   **每用户授权（BYOT）** -每个呼叫使用用户自己的生产性令牌，在休息时加密；没有共享管理令牌([细节](https://npmcn.com/package/%40monadsag/productive-mcp/#readme-per-user-tokens-byot)）
-   **自动用户分辨率** -将Entra电子邮件自动映射到生产性用户ID
-   **名称解析** -人员、公司、项目、任务和交易按名称显示，而不是原始ID
-   **70 +工具** -项目，任务，时间跟踪，发票，评论，页面等
-   **零客户端设置** -只需添加一个URL到克劳德桌面或克劳德代码

## 快速入门

如果您的组织中有人已经部署了此服务器，您只需要配置您的MCP客户端：

### 克劳德桌面

将......添加到...... `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "productive": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-worker>.<your-subdomain>.workers.dev/mcp"]
    }
  }
}
```

重新启动Claude Desktop。浏览器窗口打开Entra ID登录在第一次连接。会话持续-您只登录一次。

### 克劳德代码

```bash
claude mcp add productive -- npx -y mcp-remote https://<your-worker>.<your-subdomain>.workers.dev/mcp
```

## 部署你自己的

### 先决条件

-   [Cloudflare帐户](https://dash.cloudflare.com/sign-up) 有工人（免费层作品）
-   [微软Entra ID](https://entra.microsoft.com/) 具有App注册权限的租户
-   Node.js 18+和npm

### 1\. 克隆并安装

```bash
git clone https://github.com/MonadsAG/monads-mcp-productive.git
cd monads-mcp-productive
npm install
```

### 2\. 创建Cloudflare KV命名空间

```bash
npx wrangler login
npx wrangler kv namespace create "OAUTH_KV"
npx wrangler kv namespace create "USER_MAPPING_KV"
npx wrangler kv namespace create "USER_PAT_KV"
```

将命名空间id复制到 `wrangler.jsonc`． （`USER_PAT_KV` 存储每个用户的 加密的生产性令牌-参见 [用户令牌](https://npmcn.com/package/%40monadsag/productive-mcp/#readme-per-user-tokens-byot).）

### 3\. 注册Entra ID应用程序

```bash
# Login to your Entra tenant
az login --tenant <your-tenant-id> --allow-no-subscriptions

# Create the app registration (single tenant).
# Register BOTH redirect URIs: /callback (MCP login) and /settings/callback (token settings page).
az ad app create \
  --display-name "Productive MCP" \
  --sign-in-audience "AzureADMyOrg" \
  --web-redirect-uris \
    "https://<your-worker>.<your-subdomain>.workers.dev/callback" \
    "https://<your-worker>.<your-subdomain>.workers.dev/settings/callback"

# Note the appId from the output, then add API permissions
az ad app permission add \
  --id <app-id> \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions \
    37f7f235-527c-4136-accd-4a02d197296e=Scope \
    14dad69e-099b-42c9-810b-d002981feec1=Scope \
    64a6cdd6-aab1-4aaf-94b8-3cc8405e90d0=Scope \
    e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope

# Grant admin consent
az ad app permission admin-consent --id <app-id>

# Generate a client secret (2-year expiry)
az ad app credential reset \
  --id <app-id> \
  --append \
  --display-name "Cloudflare Worker" \
  --years 2
```

权限id对应： `openid`， `profile`， `email`， `User.Read` (委托)。

### 4\. 设置Cloudflare机密

```bash
npx wrangler secret put PRODUCTIVE_ORG_ID         # your org ID with slug (e.g. 12345-company-name)
npx wrangler secret put PRODUCTIVE_API_BASE_URL   # https://api.productive.io/api/v2/ (or sandbox URL)
npx wrangler secret put PRODUCTIVE_TOOLSETS       # optional, comma-separated toolset names (default: all tools)
npx wrangler secret put ENTRA_CLIENT_ID           # app (client) ID from step 3
npx wrangler secret put ENTRA_CLIENT_SECRET       # client secret from step 3
npx wrangler secret put ENTRA_TENANT_ID           # your Entra directory (tenant) ID
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY   # signs session/CSRF cookies
openssl rand -hex 32 | npx wrangler secret put PAT_ENC_KEY             # encrypts per-user PATs at rest (AES-256-GCM)
```

> **没有共享的生产性令牌。** 每个用户通过提供自己的生产性PAT `/settings` 页面(参见 [用户令牌](https://npmcn.com/package/%40monadsag/productive-mcp/#readme-per-user-tokens-byot)),所以 `PRODUCTIVE_API_TOKEN` 是 **不** 工人所需要的。它只适用于传统的本地工作室入口点 （放进去） `.env`（而不是作为Worker的秘密）。在那里, `PRODUCTIVE_API_TOKEN` 和 `PRODUCTIVE_ORG_ID` 就足够了：“我”后面的人ID从令牌处解析为 创业公司,所以 `PRODUCTIVE_USER_ID` 只需要重写它。

### 5\. 部署

```bash
npm run worker:deploy
```

### 6\. 连接

配置Claude Desktop或Claude Code，如 [快速入门](https://npmcn.com/package/%40monadsag/productive-mcp/#readme-quick-start)，将占位符URL替换为您的Worker URL。

## 每用户令牌（BYOT）

每个生产性API调用都使用 **请求用户自己的个人访问令牌** （Bring Your Own Token），所以Productive强制每个用户的真实权限——没有 共享管理令牌。身份仍然来自微软的Entra ID；只有上游 凭证现在是针对每个用户的。

连接MCP后，每个用户打开一次设置页面来存储他们的令牌：

```
https://<your-worker>.<your-subdomain>.workers.dev/settings
```

该页面使用Entra ID登录用户，然后允许他们登录 **设置、旋转或删除** 他们的 生产PAT -不需要MCP重新连接。令牌是针对生产性进行验证的， 用AES-256-GCM加密(`PAT_ENC_KEY`)，然后再写信给他 `USER_PAT_KV` (键控 用户的稳定Entra对象ID)，并且从未显示、记录或通过模型发送。

在用户存储令牌之前，他们的工具调用返回一个链接到的友好消息 `/settings` 而不是任何数据。

显示设置页面和登录对话框 **自动德语或英语**，基于… 浏览器的 `Accept-Language` (默认英文);附加 `?lang=de` / `?lang=en` 强迫一个。

## 体系结构

```
┌─────────────────┐    Streamable HTTP    ┌──────────────────────────────┐
│  Claude Desktop  │ ◄──────────────────► │  Cloudflare Worker           │
│  / Claude Code   │                      │                              │
│  (via mcp-remote)│                      │  OAuthProvider (OAuth 2.1)   │
└─────────────────┘                       │       ↓                      │
                                          │  Entra ID (OIDC login)       │
       Browser ←── login redirect ───────→│       ↓                      │
                                          │  McpAgent (Durable Object)   │
                                          │       ↓                      │
                                          │  ProductiveAPIClient         │
                                          └──────────────┬───────────────┘
                                                         ↓
                                                  Productive.io API
```

## 可用的工具

### 公司及项目

| 工具 | 描述 |
| --- | --- |
| `whoami` | 获取当前用户上下文 |
| `list_companies` | 公司/客户列表 |
| `list_projects` | 列出具有状态过滤的项目 |

### 文件夹（板）和任务列表

Productive的UI将此资源称为“文件夹”；API将其建模为一个“板”（任务和任务列表通过a引用它们的父节点） `board`/`board_id` 关系)。一个工具集涵盖了它——没有单独的“板”工具。

| 工具 | 描述 |
| --- | --- |
| `list_folders` / `get_folder` / `create_folder` / `update_folder` | 文件夹CRUD |
| `archive_folder` / `restore_folder` / `copy_folder` / `move_folder` / `reposition_folder` | 文件夹生命周期及定位 |
| `list_task_lists` / `create_task_list` / `get_task_list` / `update_task_list` | 任务列表CRUD |
| `archive_task_list` / `restore_task_list` / `copy_task_list` / `move_task_list` / `reposition_task_list` | 任务列表操作 |

### 任务

| 工具 | 描述 |
| --- | --- |
| `list_tasks` / `get_task` / `get_project_tasks` / `my_tasks` | 查询任务 |
| `create_task` / `update_task` / `delete_task` | 任务CRUD |
| `update_task_status` | 任务状态更改 |
| `list_custom_fields` / `list_custom_field_options` | 自定义字段发现 |
| `move_task_to_list` / `add_to_backlog` / `reposition_task` | 任务定位 |
| `list_subtasks` / `create_subtask` | 子任务管理 |
| `list_task_dependencies` / `create_task_dependency` / `delete_task_dependency` | 依赖关系 |

### 评论和待办事项

| 工具 | 描述 |
| --- | --- |
| `add_task_comment` / `list_comments` / `get_comment` / `update_comment` / `delete_comment` | 评论CRUD |
| `pin_comment` / `unpin_comment` / `add_comment_reaction` | 评论的行为 |
| `list_todos` / `get_todo` / `create_todo` / `update_todo` / `delete_todo` | 任务管理 |

### 页面和文档

| 工具 | 描述 |
| --- | --- |
| `list_pages` / `get_page` / `create_page` / `update_page` / `delete_page` | 页面CRUD |
| `list_page_children` | 页面层次结构 |
| `move_page` / `copy_page` | 页面操作 |

### 时间跟踪

| 工具 | 描述 |
| --- | --- |
| `list_time_entries` / `create_time_entry` / `update_time_entry` | 时间输入CRUD |
| `set_time_entry_approval` | 审批工作流（动作参数） |
| `start_timer` / `stop_timer` / `get_timer` / `get_running_timer` | 实时计时器 |
| `list_services` / `get_project_services` / `list_project_deals` / `list_deal_services` | 预算和服务查询 |
| `create_budget_service` / `update_budget_service` | 预算服务（行项目）CRUD |
| `list_budget_sections` / `create_budget_section` / `update_budget_section` / `delete_budget_section` | 预算组（服务组） |

### 发票

| 工具 | 描述 |
| --- | --- |
| `list_invoices` / `get_invoice` / `create_invoice` / `update_invoice` / `delete_invoice` | 发票CRUD |
| `list_company_budgets` / `create_budget` / `update_budget` / `create_budget_from_deal` | 预算CRUD和推导 |
| `generate_line_items` / `finalize_invoice` / `mark_invoice_paid` | 发票的工作流 |
| `get_invoice_pdf_url` / `get_timesheet_report_url` | 文档的url |

### 活动&工作流程

| 工具 | 描述 |
| --- | --- |
| `list_activities` | 列出带有过滤器的活动 |
| `get_recent_updates` | 获取最新更新 |
| `list_workflow_statuses` | 列出工作流状态 |

## 常见的工作流

### 时间输入

按照顺序：项目→交易/预算→服务→时间入账。

```
list_projects → list_project_deals → list_deal_services → create_time_entry
```

### 任务状态更新

按名称更新-不需要查找ID：

```json
{ "task_id": "123", "status_name": "In Progress" }
```

### 发票

```
list_companies → list_company_budgets → create_invoice → generate_line_items → finalize_invoice → mark_invoice_paid
```

### 预算

直接创建:

```
list_companies → create_budget → update_budget (optional)
```

派生自现有的交易/合同（交易必须处于“赢”状态）：

```
list_project_deals → create_budget_from_deal
```

### 预算服务

将服务（行项目）附加到预算中：

```
create_budget → create_budget_service → update_budget_service (optional)
```

```json
{ "budget_id": "123", "name": "Consulting Hours", "price": 150, "quantity": 20 }
```

`unit_id` （1=小时，2=片，3=天）默认为 `1`； `billing_type_id` （1=固定，2=实际，3=无，4=百分比）默认为 `2`.

要对预算的服务进行分组，例如按项目阶段对其进行分组，请使用 `create_budget_section` 并通过 `section_id` 来 `create_budget_service` 或者 `update_budget_service`. `list_budget_sections` 显示每个部分及其服务； `delete_budget_section` 只删除 空的部分。

## npm package / MCP hub

工作室入口点也被发布到npm [`@monadsag/productive-mcp`](https://www.npmjs.com/package/@monadsag/productive-mcp)，为主机 将MCP服务器作为本地进程启动（例如Monads MCP hub）。每一次推到 `main` 从CI发布一个新版本，其来源为npm：主要和次要来自 `package.json`， 补丁是CI运行号。没有手动释放步骤。每个版本都包含一个 `npm-shrinkwrap.json`，因此每次安装都会得到经过CI测试的依赖树。

```bash
npx -y @monadsag/productive-mcp@latest
```

| 变量 | 要求 | 描述 |
| --- | --- | --- |
| `PRODUCTIVE_API_TOKEN` | 是 | 用户自己的生产性API令牌 |
| `PRODUCTIVE_ORG_ID` | 是 | 带编号的组织ID，例如： `12345-company-name` |
| `PRODUCTIVE_USER_ID` | 否 | “我”后面的人ID；如果未设置，则从令牌解析 |
| `PRODUCTIVE_TOOLSETS` | 否 | 启用逗号分隔的工具集（默认值：all） |

服务器在标准输出上使用MCP，并只记录标准输出日志。注意，没有作用域 `productive-mcp` 在NPM上是berwickgeek的上游版本，而不是这个分支。

`npm run build && npm run package:smoke` 打包，从当地的一次性食品中取出 注册表并开始 `npx` 通过演播室，和集线器一样。

## 开发

```bash
npm run worker:dev     # local dev on port 8788 (requires .dev.vars with secrets)
npm run worker:deploy  # deploy to Cloudflare
npm run build          # compile TypeScript (for local stdio fallback)
npm run format         # prettier
```

创建一个 `.dev.vars` 使用与Cloudflare本地开发秘密相同的变量(包括 `PAT_ENC_KEY` (64位十六进制字符串，例如： `openssl rand -hex 32`）。 `wrangler dev` 自动提供本地KV命名空间。

## 许可证

[Apache 2.0](https://npmcn.com/package/%40monadsag/productive-mcp/LICENSE)

最初基于 [productive-mcp](https://github.com/berwickgeek/productive-mcp) 由 [jayat3dn](https://github.com/berwickgeek) (ISC)。看到 [请注意](https://npmcn.com/package/%40monadsag/productive-mcp/NOTICE) 查看归属详细信息。

* * *

维护的 [单体AG)](https://monads.ch/)

## 常见问题

### @monadsag/productive-mcp 是什么？

用于生产的MCP服务器。io API集成

### 如何安装 @monadsag/productive-mcp？

在项目目录运行 npm install @monadsag/productive-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 productive-mcp，可以用 npx productive-mcp 直接运行。

### @monadsag/productive-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/monadsag\_\_productive-mcp 是否存在。

### @monadsag/productive-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @monadsag/productive-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @monadsag/productive-mcp 可以商用吗？

@monadsag/productive-mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @monadsag/productive-mcp 还在维护吗？

最新版本 1\.2\.62 发布于 2026/11/02（1 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/10/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。