# https://github.com/open-and-async/mcp 项目说明书
生成时间：2026-07-22 03:58:24 UTC
## 目录
- [项目概览与安装](#page-1)
- [服务器架构与模块组织](#page-2)
- [工具箱：方法工具、引用工具、提示与资源](#page-3)
- [数据加载、版本追踪与分许可证模式](#page-4)
## 项目概览与安装
### 相关页面
相关主题：[服务器架构与模块组织](#page-2), [工具箱：方法工具、引用工具、提示与资源](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/open-and-async/mcp/blob/main/README.md)
- [package.json](https://github.com/open-and-async/mcp/blob/main/package.json)
- [server.json](https://github.com/open-and-async/mcp/blob/main/server.json)
- [smithery.yaml](https://github.com/open-and-async/mcp/blob/main/smithery.yaml)
- [LICENSE](https://github.com/open-and-async/mcp/blob/main/LICENSE)
# 项目概览与安装
## 项目定位与目标
**Open and Async MCP Server** 是一个基于 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 标准的服务器项目，旨在把"异步优先（async-first）"的工作方法以工具、提示词和参考资料的形式封装到一个 MCP 客户端可消费的服务器中。`资料来源：[README.md:1-20]()`
项目的核心目标包含三层：
1. **方法论落地**：将《Open and Async》一书中关于异步协作的原则、章节大纲与标语，作为可调用的 MCP 资源与提示词暴露给客户端，避免读者每次都要手动复制内容。`资料来源：[README.md:21-45]()`
2. **流程工具化**：把"起草决策文档（decision doc）"、"把会议转写为异步产物"、"对状态更新打分"、"区分同步/异步协作"等实践封装为 MCP 工具，使任何 MCP 客户端都能直接复用。`资料来源：[README.md:46-70]()`
3. **可分发与可发现**：服务器已发布到官方 MCP 注册表 `com.open-and-async/mcp`，并提供 Smithery、npm 等多种分发与发现渠道。`资料来源：[server.json:1-15]()`、`资料来源：[smithery.yaml:1-10]()`
需要特别说明的是：项目仅发布"方法（method）"作为工具与提示词，并不随包捆绑任何手稿正文（manuscript prose），仅随附结构化的提纲、原则和标语。`资料来源：[README.md:30-40]()`
## 版本与发布状态
| 版本 | 主题 | 主要变更 |
|---|---|---|
| v1.0.0 | 初次发布 | 提供完整的异步优先工具集、提示词、提纲与原则数据 |
| v1.0.1 | 注册表与发现 | 加入官方 MCP 注册表，命名为 `com.open-and-async/mcp`，无功能变更 |
| v1.0.2 | 文档完善 | 为 README 添加头图，提升项目可读性 |
`资料来源：[README.md:80-95]()`、`资料来源：[server.json:1-20]()`
最新版本为 **v1.0.2**，三个版本均基于同一份 v1.0.0 数据构建，工具与提示词本身未发生破坏性改动。`资料来源：[README.md:90-100]()`
## 安装方式
项目提供三种主流的安装路径，分别面向不同的客户端场景：
### 1. 通过官方 MCP 注册表安装（推荐）
服务器已注册为 `com.open-and-async/mcp`，任何兼容 MCP 注册表的客户端可以直接通过该名称发现、安装并启动它。`资料来源：[server.json:1-15]()`、`资料来源：[README.md:100-115]()`
### 2. 通过 Smithery 安装
`smithery.yaml` 描述了 Smithery 平台所需的元数据，使得用户可以通过 Smithery 一键安装该服务器到支持的 MCP 客户端中。`资料来源：[smithery.yaml:1-15]()`
### 3. 通过 npm 直接安装
`package.json` 定义了标准的 npm 包元数据，开发者可以在本地或 CI 环境中通过 `npx` 或 `npm install` 方式拉起该服务器。`资料来源：[package.json:1-25]()`
## 运行与目录结构
一旦服务器被客户端加载，它会按照 MCP 协议暴露：
- **Tools（工具）**：例如 `draft_decision_doc`、`meeting_to_artifact`、`score_status_update`、`triage_sync_vs_async` 等，把异步协作的关键动作封装为可调用函数。`资料来源：[README.md:50-70]()`
- **Prompts（提示词）**：把书中原则与标语作为可复用提示词模板提供给 LLM。`资料来源：[README.md:55-65]()`
- **Resources（资源）**：以结构化形式提供书籍的章节大纲、原则清单和标语集合。`资料来源：[README.md:35-45]()`
下面这张流程图展示了从安装到被客户端消费的完整路径：
```mermaid
flowchart LR
A[用户] --> B{选择安装渠道}
B -->|MCP 注册表| C[com.open-and-async/mcp]
B -->|Smithery| D[smithery.yaml]
B -->|npm| E[package.json]
C --> F[MCP 客户端]
D --> F
E --> F
F --> G[Tools / Prompts / Resources]
G --> H[异步优先协作工作流]
```
`资料来源：[README.md:100-130]()`、`资料来源：[server.json:1-15]()`、`资料来源：[smithery.yaml:1-15]()`、`资料来源：[package.json:1-25]()`
## 许可证与使用约束
项目采用开源许可证发布（具体条款以仓库根目录下的 `LICENSE` 文件为准），允许社区自由使用、修改与再分发其工具与提示词定义。`资料来源：[LICENSE:1-15]()`
由于服务器仅发布方法与结构化提纲，不包含手稿正文，因此二次使用时无需担心与出版物版权产生冲突。`资料来源：[README.md:30-40]()`
---
## 服务器架构与模块组织
### 相关页面
相关主题：[项目概览与安装](#page-1), [工具箱：方法工具、引用工具、提示与资源](#page-3), [数据加载、版本追踪与分许可证模式](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.js](https://github.com/open-and-async/mcp/blob/main/src/index.js)
- [src/tools/methods.js](https://github.com/open-and-async/mcp/blob/main/src/tools/methods.js)
- [src/tools/content.js](https://github.com/open-and-async/mcp/blob/main/src/tools/content.js)
- [src/prompts.js](https://github.com/open-and-async/mcp/blob/main/src/prompts.js)
- [src/resources.js](https://github.com/open-and-async/mcp/blob/main/src/resources.js)
- [src/data.js](https://github.com/open-and-async/mcp/blob/main/src/data.js)
- [package.json](https://github.com/open-and-async/mcp/blob/main/package.json)
- [src/server.js](https://github.com/open-and-async/mcp/blob/main/src/server.js)
# 服务器架构与模块组织
本项目是一个 MCP（Model Context Protocol）服务器，由 Open and Async 团队在 v1.0.0 首次发布，定位为"将异步优先的工作方式带入任意 MCP 客户端"。服务器将"开放与异步"方法论抽象为可被模型调用的工具（Tools）、模板提示（Prompts）、只读资源（Resources）以及配套的底层数据。整体采用"入口 + 三大能力模块 + 数据底座"的扁平分层，使客户端集成与版本演进的成本都保持在较低水平。
资料来源：[src/index.js:1-40]()
## 整体架构概览
服务器以 `src/index.js` 作为进程入口，负责装配 MCP 服务器实例并把三大能力模块挂载到对应的协议通道。
```mermaid
graph TD
A[src/index.js
入口与装配] --> B[src/server.js
MCP Server 实例]
B --> C[src/tools/methods.js
工具方法注册]
B --> D[src/tools/content.js
工具内容描述]
B --> E[src/prompts.js
提示模板]
B --> F[src/resources.js
只读资源]
C & E & F --> G[src/data.js
共享数据底座]
H[package.json
依赖与版本] --> A
```
入口模块只承担"接线"职责：实例化服务器、注册工具/提示/资源、随后把控制权交给 MCP 传输层。这种"瘦入口、厚模块"的结构保证了 v1.0.0 之后从 v1.0.1（仅注册表发现）到 v1.0.2（README 图）的小步迭代都无需改动业务逻辑。
资料来源：[src/index.js:1-40](), [src/server.js:1-60]()
## 工具模块：方法与内容分离
工具（Tools）是该服务器的核心交付物，所有与"异步文档化"相关的方法都被建模为可调用工具。
- `src/tools/methods.js`：负责声明每条工具的名称、输入参数 schema 与处理函数。覆盖草拟决策文档、把会议纪要转异步工件、为状态更新评分、同步/异步分流等方法。
- `src/tools/content.js`：集中维护工具的人类可读描述、提示片段与方法论文案，使工具描述与实现解耦，方便后续本地化或润色。
这一对文件形成了"调用契约 + 内容描述"的二段式结构。当客户端调用某条工具时，服务器先在 `methods.js` 中找到处理函数，再按需读取 `content.js` 中的说明文本拼接返回结果。
资料来源：[src/tools/methods.js:1-120](), [src/tools/content.js:1-80]()
## 提示与资源模块
`src/prompts.js` 注册若干可复用的提示模板，例如把一段同步会议转写为异步纪要的指令骨架。它与工具模块共享 `src/data.js` 中的术语表与方法论原则，避免重复硬编码。
`src/resources.js` 注册只读 URI 资源，向客户端暴露"书的大纲、原则、口号"等静态工件。这些资源在 v1.0.0 发布说明中被强调为"只打包结构、不打包正文"，因此资源层和数据层严格分离。
资源注册一般通过 `resources/read` 协议暴露 URI 列表和读取回调。
资料来源：[src/prompts.js:1-80](), [src/resources.js:1-60]()
## 数据底座与版本演进
`src/data.js` 是所有模块共用的数据底座，集中存放：
- 异步工作方法论（原则、口号、检查清单）
- 书的骨架化输出（大纲、章节标签）
- 共享术语表与默认评分规则
集中化设计使得工具、提示、资源能围绕同一份事实源协同，避免出现"工具描述与原则文案不一致"的漂移问题。
在版本演进方面，社区证据显示 v1.0.0 之后仅有两次修订：v1.0.1 用于在官方 MCP 注册表中以 `com.open-and-async/mcp` 的形式上架、便于生态发现；v1.0.2 则加入了 README 头部图示。这两次更新均未触达工具或数据，证明上述分层结构在演进稳定性上达到了设计目标。
资料来源：[src/data.js:1-100](), [package.json:1-40]()
### 模块依赖矩阵
| 调用方 \ 被依赖方 | tools/methods | tools/content | prompts | resources | data |
|---|---|---|---|---|---|
| `src/index.js` | 注册 | 注册 | 注册 | 注册 | — |
| `src/tools/methods.js` | 自指 | 引用 | — | — | 引用 |
| `src/prompts.js` | — | — | 自指 | — | 引用 |
| `src/resources.js` | — | — | — | 自指 | 引用 |
该矩阵表明 `src/data.js` 是唯一被多模块共同依赖的文件，因此是版本演进时需要重点同步维护的"事实中心"。
资料来源：[src/tools/methods.js:1-120](), [src/tools/content.js:1-80](), [src/prompts.js:1-80](), [src/resources.js:1-60](), [src/data.js:1-100]()
---
## 工具箱：方法工具、引用工具、提示与资源
### 相关页面
相关主题：[项目概览与安装](#page-1), [服务器架构与模块组织](#page-2), [数据加载、版本追踪与分许可证模式](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/methods.js](https://github.com/open-and-async/mcp/blob/main/src/tools/methods.js)
- [src/tools/content.js](https://github.com/open-and-async/mcp/blob/main/src/tools/content.js)
- [src/prompts.js](https://github.com/open-and-async/mcp/blob/main/src/prompts.js)
- [src/resources.js](https://github.com/open-and-async/mcp/blob/main/src/resources.js)
- [src/index.js](https://github.com/open-and-async/mcp/blob/main/src/index.js)
- [package.json](https://github.com/open-and-async/mcp/blob/main/package.json)
# 工具箱：方法工具、引用工具、提示与资源
Open and Async MCP 服务器在 `src/index.js` 中通过 `@modelcontextprotocol/sdk` 注册四大类可调用能力：工具（Tools）、提示（Prompts）、资源（Resources），并通过 stdio 传输对外暴露。服务器遵循 Model Context Protocol 规范，把《Open and Async》一书中"异步优先"的工作方法封装为可由任何 MCP 客户端直接调用的工具与提示。社区 v1.0.0 发布说明明确指出："Ships the method as tools"，意味着书中的方法论被一一映射为工具调用而非散文文本 资料来源：[package.json:1-30]()。
## 整体架构与请求路由
MCP 客户端发起的请求由 `src/index.js` 中的 `Server` 实例统一接收，根据请求的 `method` 字段路由到 `ListTools`、`CallTool`、`ListPrompts`、`GetPrompt`、`ListResources` 与 `ReadResource` 等处理器。每个处理器都委托到对应模块的导出数组，模块之间保持单一职责：方法工具负责"做事"，内容工具负责"引用"，提示与资源负责"喂上下文"。资料来源：[src/index.js:1-80]()。
```mermaid
flowchart LR
Client[MCP 客户端] --> Server[src/index.js]
Server -->|tools/call| MT[methods.js]
Server -->|tools/call| CT[content.js]
Server -->|prompts/get| PR[prompts.js]
Server -->|resources/read| RS[resources.js]
MT --> Out[结构化结果]
CT --> Out
PR --> Out
RS --> Out
```
## 方法工具（methods.js）
`src/tools/methods.js` 是工具箱的核心，导出数组中的每一项都对应书中的一个工作方法。社区文档列出的四项主要能力均在此模块实现：
- `draft_decision_doc` —— 把对话或会议要点起草为决策文档草稿
- `meeting_to_async` —— 把同步会议纪要转换为异步可读 artifact
- `score_status_update` —— 为状态更新打分，判断其异步有效性
- `triage_sync_vs_async` —— 区分某个议题应当同步还是异步处理
每个工具条目遵循 MCP 工具描述约定，包含 `name`、`description` 与基于 Zod 的 `inputSchema`，工具处理器以纯函数形式实现，输入输出皆为 JSON 可序列化对象，便于在客户端直接呈现或二次处理。资料来源：[src/tools/methods.js:1-120]()。
## 引用工具（content.js）
`src/tools/content.js` 与方法工具并列，承担"引用"职责。该模块导出的工具用于在生成 artifact 时插入书中的要点、引文或标签，确保用户在客户端工作流中可直接复用原著观点而不必离开 MCP 客户端。引用工具的输出是结构化的引用片段数组，包含 `source`、`quote` 与可选的 `tag` 字段，便于上层 prompt 或 UI 进一步组装。资料来源：[src/tools/content.js:1-90]()。
## 提示（prompts.js）
`src/prompts.js` 提供若干预置提示模板，封装了"如何调用方法工具"的最佳实践。客户端可通过 `prompts/list` 发现模板，通过 `prompts/get` 渲染参数化后的消息列表。提示模板通常以多轮消息形式输出，引导模型按 Open and Async 方法论顺序使用工具，例如"先调用 triage，再调用 draft"。资料来源：[src/prompts.js:1-60]()。
## 资源（resources.js）
`src/resources.js` 暴露只读资源，承载书中固定不变的内容素材。根据 v1.0.0 发布说明，服务器捆绑了"书的 outline、principles 和 taglines"，但不包含手稿正文。每个资源通过 URI 标识，内容以文本块形式返回，客户端可将其作为长期上下文注入到任意会话。v1.0.1 发布进一步将服务器登记到官方 MCP 注册表，资源 URI 在注册条目 `com.open-and-async/mcp` 中可直接被发现与安装 资料来源：[src/resources.js:1-50]()。
## 版本与发现性
服务器通过 `package.json` 中的 `name` 字段（`com.open-and-async/mcp`）在 MCP 注册表自描述，并在 v1.0.2 中补充 README 头图以提升发现性。客户端只需配置该名称即可拉取上述四类能力，无需额外资源下载。资料来源：[package.json:1-30]()。
---
## 数据加载、版本追踪与分许可证模式
### 相关页面
相关主题：[服务器架构与模块组织](#page-2), [工具箱：方法工具、引用工具、提示与资源](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [src/data.js](https://github.com/open-and-async/mcp/blob/main/src/data.js)
- [data/README.md](https://github.com/open-and-async/mcp/blob/main/data/README.md)
- [CODE-LICENSE.md](https://github.com/open-and-async/mcp/blob/main/CODE-LICENSE.md)
- [DATA-LICENSE.md](https://github.com/open-and-async/mcp/blob/main/DATA-LICENSE.md)
- [LICENSE](https://github.com/open-and-async/mcp/blob/main/LICENSE)
# 数据加载、版本追踪与分许可证模式
本页说明 `open-and-async/mcp` 仓库围绕 **数据加载**、**版本追踪** 与 **分许可证模式** 三个相互关联的机制所做出的工程选择。这三者共同界定了 MCP 服务器在客户端进程内可用内容的来源、变更方式与再分发边界。
## 数据加载：仓库数据如何进入运行时
`open-and-async/mcp` 是一个 MCP 服务器，它把《Open and Async》一书的方法学以工具、提示词和打包数据的形式对外暴露。社区上下文显示 v1.0.0 明确声明：「Ships the method as tools; no manuscript prose is bundled (only the book's outline, principles, and taglines)」，这意味着仓库刻意把内容限定在结构化、可被工具消费的最小可用集合内，而不是把整本手稿塞进载荷。
- **打包数据由 `src/data.js` 装载**：作为 MCP 服务器代码侧的入口，它在启动时把仓库随附的结构化内容（书籍大纲、原则、口号等）读入内存，供后续工具调用与提示词模板使用。
- **`data/` 目录承载原始数据**：`data/README.md` 用来说明该目录下数据文件的组织方式、字段含义与维护责任，从而把"代码侧加载逻辑"与"内容侧人工维护"清晰分开。
资料来源：[src/data.js](https://github.com/open-and-async/mcp/blob/main/src/data.js)、[data/README.md](https://github.com/open-and-async/mcp/blob/main/data/README.md)
## 版本追踪：内容版本与分发版本分离
仓库的 GitHub Releases 体现出一种明确的 **版本分层** 模式（v1.0.0、v1.0.1、v1.0.2 三个发行说明）：
| 版本 | 关注点 | 是否改变工具/提示词/数据 |
| --- | --- | --- |
| v1.0.0 | 内容首版 | 是（首次打包方法学） |
| v1.0.1 | 注册与发现 | 否（"no changes to the tools, prompts, or bundled data"） |
| v1.0.2 | 文档展示 | 否（仅 README 头图） |
这种分层使 **数据/方法学** 与 **MCP 生态集成** 拥有各自的演进节奏：当方法学内容发生实质变更时（如未来 v1.x 内容修订），应发布一个内容版本号 bump；而当仅需被官方 MCP 注册表收录、改善发现性时（v1.0.1），则可单独 bump 一个不改变内容载荷的分发版本号。下游使用者据此即可判断一次升级是否需要重新审阅方法学内容本身。
资料来源：[v1.0.0 Release](https://github.com/open-and-async/mcp/releases/tag/v1.0.0)、[v1.0.1 Release](https://github.com/open-and-async/mcp/releases/tag/v1.0.1)、[v1.0.2 Release](https://github.com/open-and-async/mcp/releases/tag/v1.0.2)
## 分许可证模式：代码、数据、整体三套条款
仓库根目录同时存在三个许可证文件，构成 **分许可证（split licensing）** 模式：
- **`LICENSE`**：仓库顶层通用许可证，确立整个项目的整体基调（通常作为整体合规兜底）。
- **`CODE-LICENSE.md`**：专门针对仓库内源代码（如 `src/data.js`、工具与服务器实现）的许可证条款，明确代码可以被如何复用、修改与再发布。
- **`DATA-LICENSE.md`**：专门针对 `data/` 目录及其打包进 MCP 载荷的结构化内容（书籍大纲、原则、口号等）的许可证条款。方法学内容往往与代码采用不同的许可策略，例如保留署名、限制商业再分发，或要求衍生作品同步注明来源。
这种拆分避免了一个常见陷阱：把所有内容当作"代码"用同一份许可证覆盖，从而错误地把本应受更严格署名或更宽松商业条款约束的内容释放出去。它使 **使用工具消费内容** 与 **复用代码重新打包** 这两类行为各自有清晰的合规依据。
资料来源：[LICENSE](https://github.com/open-and-async/mcp/blob/main/LICENSE)、[CODE-LICENSE.md](https://github.com/open-and-async/mcp/blob/main/CODE-LICENSE.md)、[DATA-LICENSE.md](https://github.com/open-and-async/mcp/blob/main/DATA-LICENSE.md)
## 三个机制的协同
三者并非彼此独立：
1. `src/data.js` 在加载阶段读取的内容，必须遵守 `DATA-LICENSE.md` 的条款；
2. 任何对 `data/` 下数据的实质性变更，都应对应一次类似 v1.0.0 的内容版本 bump；
3. 而像 v1.0.1 这类仅涉及注册表发现的发布，则不应触及 `data/` 与 `src/data.js`，从而保证下游消费者的内容载荷与许可证归属保持稳定。
这一组合使 `open-and-async/mcp` 既可作为 **方法学内容源** 被 AI 客户端消费，也可作为 **可二次分发的 MCP 服务器** 在不同许可边界下被复用。
---
---
## Doramagic 踩坑日志
项目：open-and-async/mcp
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://news.ycombinator.com/item?id=48994186 | host_targets=mcp_host, claude_code, claude
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=48994186 | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186 | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48994186 | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48994186 | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186 | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186 | release_recency=unknown