Linear Project

Linear 项目 MCP 服务

一个范围受限的 Model Context Protocol 服务，用于管理 Linear 项目工作流，并可选配只读 GitHub 证据和本地 Obsidian 笔记适配器。

此服务为本仓库中的三项技能提供补充。当现有连接器无法创建团队、强制使用精确范围标签或安全关联本地证据时，这些工作流便可借助此服务所提供的集成功能。

支持的配置

Linear 配置	项目范围	Issue 标识符行为
现有团队	精确项目，以及 ACQI Issue 和项目标签	保留现有团队键，例如 OPEN-42
使用 ACQI 键的新专用团队	精确项目，以及 ACQI 标签	仅当确认团队为空时，才从 ACQI-1 开始
现有父团队下使用 ACQI 的新子团队	精确项目，以及 ACQI 标签	仅当确认子团队为空时，才从 ACQI-1 开始

Linear 标识符属于团队，而非项目或标签。如果请求要求在现有的 OPEN 团队中使用 ACQI-1，服务会在创建项目、标签、笔记或 Issue 之前拒绝该请求。首次标识符回读是即时安全检查，而非并发锁；初始化首个 Issue 时，请避免同时写入。

历史记录与进行中的工作分开。历史记录会添加精确的 [HISTORICAL] 标题前缀、范围标签和 HISTORICAL 标签、Historical only: true、Actionability: none，以及用于安全重放的确定性来源标记。

工具

工具	模式	用途
linear_project_capabilities	读取	报告适配器、可达性、允许列表和写入状态
linear_project_resolve_scope	读取	解析一个精确的团队／项目／标签范围
linear_project_create_team	写入	创建或复用具有范围键的专用团队或子团队
linear_project_bootstrap	写入	创建或复用团队、项目、标签、可选链接和首个 Issue
linear_project_list_scoped_issues	读取	仅列出属于精确项目且带有范围标签的 Issue
linear_project_upsert_scoped_issue	写入	幂等地创建或更新进行中或历史工作
linear_project_find_candidates	读取	查找允许列表中的待协调候选项，但不移动它们
linear_project_move_candidate	写入	在精确源状态和标识符保护措施下移动一项已审核的候选项
linear_project_link_evidence	写入	向范围内的 Issue 添加经过验证的 GitHub 或 Obsidian 链接
github_get_project_evidence	读取	规范化允许列表中的仓库、提交、PR 或 Issue
obsidian_search_project_notes	读取	搜索允许列表中的本地 Markdown 笔记
obsidian_read_project_note	读取	读取一篇允许列表中的本地 Markdown 笔记
obsidian_upsert_project_note	写入	仅替换笔记中由服务管理的部分

所有工具都使用严格的输入模式和结构化输出。修改类工具要求提供字面值确认字段，且还必须启用全局写入。

安装和构建

要求：Node.js 20 或更高版本，以及 pnpm 10。pnpm 11 要求 Node.js 22 或更高版本，无法验证与 Node.js 20 的最低兼容性。

pnpm install --frozen-lockfile
cp .env.example .env
pnpm check
pnpm build

npm 软件包名称为 @openly-useful/linear-project-mcp-server。安装后会提供 linear-project-mcp-server 协议服务和有界的 linear-project-mcp-write-window 安全辅助工具。首次成功发布到 npm 后，才可以通过 npx @openly-useful/linear-project-mcp-server 运行该软件包。在此之前，请按下方所示从源代码检出目录构建并运行。

官方 MCP Registry 名称为 org.openlyuseful/linear-project。server.json、package.json.mcpName、npm 软件包版本和 Registry 软件包版本必须一致。仓库本地的 Openly Useful 发布方信息记录了创始人个人为当前运营者，并记录了在 LLC 成立手续仍待完成期间有效的创始人所有者授权。prepublishOnly 会验证该授权，以及确切的 npm 身份、政策、命名空间、仓库来源和注册元数据。提供方身份验证和审核仍是 MCP Registry 中的独立步骤；构建、测试、验证和 pnpm pack --dry-run 都不会发布该记录。

配置

复制 .env.example，并仅提供所需适配器的配置。

Linear 接受 LINEAR_API_KEY 或 LINEAR_ACCESS_TOKEN。每次有范围限制的 Linear 读取和变更操作都必须指定准确的 LINEAR_ALLOWED_ORGANIZATION_ID；每次变更操作还必须满足以下要求：

• MCP_WRITES_ENABLED=true；
• MCP_WRITE_WINDOW_EXPIRES_AT 的时间为未来，且不超过 60 分钟；
• 使用内置写入窗口辅助工具时，MCP_AUDIT_LOG_PATH 安全且可写；
• LINEAR_ALLOWED_SCOPE_CODES 中包含准确的代码，例如 ACQI；
• 除非目标团队为键名与范围代码完全一致的专用团队，否则 LINEAR_ALLOWED_TEAM_IDS 中必须包含目标团队的 ID；
• 如果可选的 LINEAR_ALLOWED_PROJECT_IDS 允许列表非空，其中必须包含项目 ID；
• 变更工具的字面确认字段必须设为 true。

对于新的 ACQI 子团队，请将父团队 ID 加入允许列表，设置 team_mode: "subteam"，传入 parent_team_id，并使用 team_key: "ACQI"。经过身份验证的 Linear 身份必须有权在工作区中创建团队。

仅在初始项目引导期间将 LINEAR_ALLOWED_PROJECT_IDS 留空，因为此时新项目的 ID 尚不存在。读取确认后，将该准确 ID 添加到允许列表，再进行后续操作。如果项目 ID 允许列表非空，则现有项目也必须已加入允许列表；所有有范围限制的操作都必须使用准确的范围项目标签。

GitHub 为可选配置。设置 GITHUB_TOKEN，并在 GITHUB_ALLOWED_REPOSITORIES 中填写准确的 owner/name 条目。该适配器只发送 GET 请求；请使用细粒度令牌，并仅授予只读元数据权限，以及检查计划查看的引用所需的内容、拉取请求或议题访问权限。

Obsidian 为可选配置，且仅限本地使用。OBSIDIAN_VAULT_PATH 必须是绝对路径，OBSIDIAN_ALLOWED_DIRECTORIES 包含相对于 Vault 的目录，OBSIDIAN_VAULT_NAME 用于启用 obsidian:// 链接。只有这些目录下的 .md 文件可以访问。目录遍历、符号链接、非 Markdown 路径和超过 200,000 字节的文件都会被拒绝。将笔记链接到 Linear 时，只会发送 Obsidian URI 和标题，不会发送笔记内容。

如需审计操作，请将 MCP_AUDIT_LOG_PATH 设为仓库外的规范化绝对路径。其父目录必须已存在，归当前用户所有，且不得允许组用户或其他用户写入。服务会追加紧凑的 NDJSON 尝试/结果记录，其中包含操作 ID、工具名称、模式、耗时、结果和安全错误类别；不会记录工具参数、结果正文、描述、凭据或错误消息。配置审计后，如果审计接收端不可用，则会在工作流执行前阻止写入，并将读取操作标记为审计降级。

连接 Codex

使用 linear_project 作为规范的 Codex 注册别名。此别名是本地客户端配置键，有意与 npm 包名和可执行文件名不同。

在源代码检出目录中的服务目录下：

pnpm install --frozen-lockfile
pnpm build
MCP_ENTRYPOINT="$(pwd)/dist/index.js"
codex mcp add linear_project -- node "$MCP_ENTRYPOINT"
codex mcp get linear_project --json
codex mcp list --json

首次发布 npm 版本后，也可以通过版本固定的注册表安装来注册：

codex mcp add linear_project -- npx --yes @openly-useful/[email protected]
codex mcp get linear_project --json
codex mcp list --json

请勿使用 codex mcp add --env 添加 API 令牌，因为这会将提供的值存储在本地 Codex 配置中。请使用受保护的启动器或操作系统机密存储，仅向子进程导出凭据。非机密的允许列表设置可以存储在客户端配置中，但仓库中绝不能包含真实的组织、团队、项目、仓库或保管库值。

注册后，如果当前任务的工具注册表未刷新，请启动新的 Codex 任务。在新任务中：

1. 确认 linear_project 工具可见。
2. 调用 linear_project_capabilities，并确认 writesEnabled 为 false、Linear 可访问且组织已获允许。
3. 针对预期的范围代码调用 linear_project_resolve_scope，并确认团队、项目、问题标签和项目标签均已准确解析。

排查问题时，请区分以下包名：

名称	用途
linear_project	codex mcp add、codex mcp get 和 codex mcp list 的注册别名。
@openly-useful/linear-project-mcp-server	npx 和包管理器使用的 npm 包标识符。
org.openlyuseful/linear-project	官方 MCP 注册表服务名称和 npm mcpName。
linear-project-mcp-server	已安装的可执行文件和 MCP 协议服务工件名称。
linear-project-mcp-write-window	已安装的辅助工具，用于对写入窗口设置进行有界且明确的更改。

连接其他 MCP 客户端

构建服务，然后在客户端中配置本地 stdio 进程。具体配置键因客户端而异；典型格式如下：

{
  "mcpServers": {
    "linear_project": {
      "command": "/path/to/protected/linear-project-mcp-launcher",
      "args": []
    }
  }
}

受保护的启动器应从客户端的机密存储或受保护的进程环境中加载凭据，然后用 linear-project-mcp-server 进程替换自身。请勿提交包含机密信息的启动器、.env 或客户端配置。

推荐的操作顺序

1. 先禁用写入，并调用 linear_project_capabilities。
2. 使用只读工具解析或检查确切的目标位置。
3. 配置范围尽可能窄的组织、团队、项目、范围、存储库和笔记目录允许列表。
4. 仅为预期操作启用写入。
5. 使用确定性的来源标记进行引导或更新。
6. 读回结果并重放操作；已完成的导入应不再创建任何记录。
7. 再次禁用写入。

服务器进程启动时会读取配置。因此，启用或禁用 MCP_WRITES_ENABLED 后，必须重新连接或重启相关 MCP 客户端会话，然后才能检查能力或调用写入操作。安全的写入窗口如下：

1. 在禁用写入的情况下解析并检查确切范围。
2. 停止已连接的服务器进程，使用受保护运行时环境中的受限辅助工具，然后重新连接。
3. 调用 linear_project_capabilities，在执行一次明确确认的变更前，确认预期的写入状态和允许列表。
4. 读回变更后的记录并重放相同的确定性操作；重放必须报告没有额外变更。
5. 停止服务器进程，使用辅助工具关闭写入窗口，重新连接，并通过 linear_project_capabilities 确认写入已禁用。

如果任何范围读回、重放或禁用状态检查失败，请停止操作并保持写入禁用。

辅助工具接受 1–60 分钟的窗口；启用时要求输入两次范围代码；要求组织、团队、项目和范围允许列表均非空，并且必须设置 MCP_AUDIT_LOG_PATH；且绝不会隐式延长窗口。请使用存储库之外的受保护环境文件：

linear-project-mcp-write-window status --env-file /path/to/protected.env
linear-project-mcp-write-window enable --env-file /path/to/protected.env --scope ACQI --minutes 15 --confirm ACQI
# Reconnect or restart the MCP client, verify capabilities, perform one scoped operation, read back, and replay.
linear-project-mcp-write-window disable --env-file /path/to/protected.env
# Reconnect or restart again, then verify writesEnabled is false.

enable 会设置 MCP_WRITES_ENABLED=true 和有时限的 RFC 3339 格式 MCP_WRITE_WINDOW_EXPIRES_AT。disable 会恢复 MCP_WRITES_ENABLED=false 并清除过期时间。每次设置变更都要求重新连接或重启服务器进程；过期时间是额外的故障关闭限制，不能替代操作后禁用写入并重新连接。

此服务器不会运行守护进程、监视文件、自动移动协调候选项，也不会仅依据存储库证据将问题标记为 Done。单独的移动工具要求提供确切的源状态输入并明确确认；跨团队移动还要求确认标识符会发生变化，并且源标签会被替换。只有 MCP 客户端明确调用工具时，才会进行后续更新。

传输与部署

当前版本支持本地 stdio。这是有意为 Obsidian 适配器采用的设计，因为它需要读取本地知识库。未来的远程部署应使用 MCP SDK 的 Streamable HTTP 传输方式，省略本地文件系统访问，添加服务器端身份验证，并保留相同的允许列表和确认门槛。

开发

pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run

测试使用内存中的 Linear 和 MCP 传输，以及临时 Obsidian 测试数据。测试不会连接到在线服务。只读评估问题位于 evaluations/read-only.xml。

实现参考：MCP TypeScript SDK v2、Linear TypeScript SDK、Linear 团队、GitHub REST 身份验证和 Obsidian URI。

许可证

MIT