# @practicemakes/mcp 中文文档

规范地址：https://npmcn.com/package/%40practicemakes/mcp/

版本：26\.1101\.2
npm 元数据更新时间：2026-11-02T03:28:47.122Z
中文译文更新时间：2026-11-02T07:03:21.978Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40practicemakes/mcp
原文对照：https://npmcn.com/package/%40practicemakes/mcp/?lang=original

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

- 包体积（解压后）：72.4 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2026-07-12T03:46:00.744Z
- 最新版本发布：2026-11-02T03:28:46.962Z
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

MCP服务器将practicemakeprod数据（只读）暴露给Claude，身份验证为调用用户自己的Firebase身份。

## 安装

```sh
npm install @practicemakes/mcp
```

也可以使用：`pnpm add @practicemakes/mcp`、`yarn add @practicemakes/mcp`、`bun add @practicemakes/mcp`

## README

# @practicemakes / mcp

一个小 [MCP](https://modelcontextprotocol.io/) 公开的服务器 **PracticeMakes** 生产数据（只读）到Claude进行管理和开发工作-并显示您的 **规划师积压** 因此，您自己的任务列表可以驱动开发。

它的身份验证为 **您自己的平台标识** （您的Firebase用户），因此每个结果都由后端限定为您的实际角色和组织。SYSADMIN可以看到整个平台；普通用户只能看到他们的组织。这样就可以将同一台服务器交给平台上的其他用户。

## 它是如何工作的

```
Claude  ──stdio──▶  @practicemakes/mcp  ──HTTPS Bearer──▶  https://api.practicemakes.io/api/...
                    (refreshes your Firebase ID token)      (existing authz + business logic)
```

没有后端更改，也没有秘密凭据——它使用的Firebase Web API密钥是 **公共** 客户机值（作为默认值嵌入），因此每个用户仅为 **他们自己的** 帐户。只读的。

## 使用它（已发布的包）

一旦发布到npm，任何平台用户都可以连接到一行代码——无需克隆或构建：

```sh
claude mcp add practicemakes \
  --env FIREBASE_REFRESH_TOKEN=<your-refresh-token> \
  -- npx -y @practicemakes/mcp
```

在开发过程中指向本地后端 `--env PM_API_BASE_URL=http://localhost:9090`.

### 获取刷新令牌

-   **账户密码:** 创建 `.env` (见 `.env.example`), `PM_EMAIL` / `PM_PASSWORD`、运行 `yarn workspace @practicemakes/mcp login` -它打印一个 `FIREBASE_REFRESH_TOKEN=...` 线路使用。
-   **谷歌和苹果登录:** 登录web应用，打开DevTools→Application→IndexedDB→ `firebaseLocalStorage` →授权用户记录，并复制 `stsTokenManager.refreshToken`.

## Develop（从monoorepo开始）

```sh
yarn install                                   # at repo root, links the workspace
yarn workspace @practicemakes/mcp build
cp packages/mcp/.env.example packages/mcp/.env # then fill in a credential
yarn workspace @practicemakes/mcp smoke        # end-to-end check against prod
```

`smoke` 打印您的身份验证，有多少组织是可见的，以及您的Planner待办事项。要直接在Claude中运行本地构建，而不是在已发布的包中运行：

```sh
claude mcp add practicemakes \
  --env FIREBASE_REFRESH_TOKEN=... \
  -- node "$(pwd)/packages/mcp/dist/index.js"
```

## 发布

版本按单一日历方案(`26.MMDD.patch`）. 适用范围：

```sh
yarn workspace @practicemakes/mcp publish   # runs prepublishOnly (clean + build) first
```

## 工具(阅读)

| 工具 | 它返回什么 |
| --- | --- |
| `list_organizations` | 对您可见的组织（SYSADMIN→all） |
| `get_organization` | 一个组织按UUID |
| `get_my_profile` | 您的配置文件+权利/角色/org上下文 |
| `list_profiles` | 配置文件（SYSADMIN→所有，ADMIN→您的组织） |
| `get_profile` | 一个配置文件按UUID |
| `get_my_planner_tasks` | 你的计划表待办事项（推动开发） |
| `search_tasks` | 搜索任务;通过显示已完成/已删除/已休眠 `showFields` |
| `get_task` | 按UUID执行一个任务 |
| `list_workflows` | 你的Planner工作流程 |
| `get_workflow` | 一个工作流，与运行状态相结合 |
| `get_billing_config` | 您的组织的计费/权利配置(需要一个required `platform`） |
| `list_servers` | 受监视的服务器+下面工具需要的两个标识符 |
| `get_server` | 一台服务器的配置，包括其维护窗口 |
| `list_server_statuses` | 的生活状态 **所有** 您的服务器（现在有任何问题吗） |
| `get_server_uptime` | 正常运行时间%在过去的1-168小时，从原始心跳 |
| `get_server_uptime_daily` | 每天的正常运行时间历史记录超出心跳保留 |
| `list_server_incidents` | 一台服务器的停机历史记录，计划内与计划外 |

### 服务器标识符

监控工具采用 **两个不同的、不可互换的标识符**和传递错误 其中一个返回404，读起来像是丢失了服务器。 `list_servers` 返回:

| 标识符 | 所使用的 | 路线的家庭 |
| --- | --- | --- |
| `serverShortLink` | `get_server_uptime`， `get_server_uptime_daily` | `/api/public/...` (未经身份验证的) |
| `serverId` | `get_server`， `list_server_incidents` | `/api/server/...` (org-scoped认证) |

两者都不是UUID - `serverId` 是操作符指定的id(例如： `web-01`）。

## 工具(写)

每个写入工具在发送任何内容之前都要求您确认确切的请求。

| 工具 | 它是做什么的 |
| --- | --- |
| `create_task` | 在当前的组织上下文中创建一个Planner任务（需要ADMIN） |
| `complete_task` | 集 `completedAt` 在一个任务上——完成计划者驱动的开发循环的工具 |
| `switch_org_context` | 切换您的活动组织上下文（SYSADMIN→任意组织，否则仅限邀请） |

### 在启用写工具之前，请先阅读本文

**这些工具以您的身份运行，具有您的所有权限。** 身份验证是针对每个用户的Firebase ID令牌，而不是服务帐户——没有只读角色，没有单独的服务标识，并且 它们背后没有服务器端允许列表。如果您的帐户是SYSADMIN，那么写工具可以跨写 平台上的每个租户。工具列表和确认提示就是整个安全 边界。

**确认需要客户的支持。** 门采用MCP _引出_． 如果你的客户没有 在握手的过程中，广告的启发支持，没有渠道问你，每一次 编写工具 **拒绝，什么也不送** -它不会在未经确认的情况下退回到书面状态。这个 错误指定了它拒绝执行的变异。这是故意的：默默地进行 让那些不同意被要求的客户失去保护。

**`switch_org_context` 会话是全球性的。** 它改变了你的侧写，所以它改变了什么 _每一个 后读工具_ 返回会话的其余部分，而不仅仅是下一个调用。

**`complete_task` 是读-修改-写。** 没有专用的完井端点；这个工具 读取任务，设置 `completedAt`，然后带着读过的内容重新发布 `ETag` 在 `If-Match` 因此，并发编辑不会被悄无声息地破坏。

`yarn smoke` 是不受影响的-它发出三个固定的只读请求，从不触及工具 注册表，因此没有写入可以通过它到达生产。

## 路线图

-   **管理的行为** （例如ARCH-153 /user purge） - blocked：没有可执行端点存在 然而，只有一个 `GET .../data-inventory` 这说明这是一次多么大的清洗 _将_ 执行并删除任何内容。
-   **OpenAPI-driven** 从后端分组规范（monorepo已经使用）生成工具 `openapi-typescript` 在 `packages/core`）。
-   **托管远程服务器** （streamable-HTTP + per-user OAuth），这样用户就不用安装任何东西就可以连接到URL。

## 常见问题

### @practicemakes/mcp 是什么？

MCP服务器将practicemakeprod数据（只读）暴露给Claude，身份验证为调用用户自己的Firebase身份。

### 如何安装 @practicemakes/mcp？

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

### @practicemakes/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @practicemakes/mcp 支持 ESM 还是 CommonJS？

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

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

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

### @practicemakes/mcp 可以商用吗？

@practicemakes/mcp 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @practicemakes/mcp 还在维护吗？

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