mcpField
L
linear

linear

github.com/vercel-labs测试与质量2.0k98 次安装3 天前更新
代码仓库

关于 linear

linear 是一个有状态的 Linear GraphQL API 模拟器，面向开发与测试场景，可配置组织、工作流、问题、OAuth 和 Webhook。它提供本地检查界面及多种查询和变更操作，但并未实现完整的生产 API 行为。

主要功能

  1. 01模拟 Linear GraphQL 查询与变更
  2. 02配置组织、团队、问题等种子数据
  3. 03支持 OAuth 授权与令牌流程
  4. 04发送 Linear 格式的 Webhook
  5. 05通过界面检查模拟数据

适用场景

  1. 01测试依赖 Linear API 的应用
  2. 02在本地验证 OAuth 流程
  3. 03测试问题变更触发的 Webhook

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vercel-labs/emulate --skill linear

安装后在 Claude Code 中输入/linear确认已加载。

详细介绍

Linear API 模拟器

有状态的 Linear GraphQL API 模拟，包含组织、用户、团队、工作流状态、问题、评论、标签、项目、周期、OAuth 应用、令牌、Webhook 和基础 Agent 会话。

启动

本地监听器默认绑定到 127.0.0.1。如需从容器或其他机器访问，请在 CLI 中传入 --host 0.0.0.0，或在 createEmulator 中设置 hostname: '0.0.0.0'。配置 --base-url 或 baseUrl，以设置这些客户端可访问的对外 URL。

# Linear only
npx emulate --service linear

所有服务启动时的默认 URL：http://localhost:4012；仅启动 Linear 时的默认 URL：http://localhost:4000。

URL 映射

真实 Linear URL模拟器 URL
https://api.linear.app/graphql$LINEAR_EMULATOR_URL/graphql
https://linear.app/oauth/authorize$LINEAR_EMULATOR_URL/oauth/authorize
https://api.linear.app/oauth/token$LINEAR_EMULATOR_URL/oauth/token
https://api.linear.app/oauth/revoke$LINEAR_EMULATOR_URL/oauth/revoke

身份验证

GraphQL 接受 Bearer 令牌或不带前缀的个人 API 密钥：

curl "$LINEAR_EMULATOR_URL/graphql" \
  -H "Authorization: Bearer lin_test_admin" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id email } }"}'

默认情况下，范围检查较宽松。在种子配置中设置 linear.strict_scopes: true，即可要求操作具有受支持的范围，例如 read、write、issues:create、comments:create 和 admin。

种子配置

linear:
  organization:
    name: Acme
    url_key: acme
  users:
    - email: [email protected]
      name: Admin User
      admin: true
    - email: [email protected]
      name: Developer
  teams:
    - key: ENG
      name: Engineering
  issues:
    - team: ENG
      title: Fix local checkout test
      state: Todo
      assignee: [email protected]
  oauth_apps:
    - client_id: lin_example_client_id
      client_secret: example_client_secret
      name: My Linear App
      redirect_uris:
        - http://localhost:3000/api/auth/callback/linear
      scopes: [read, write, issues:create, comments:create]
  tokens:
    - token: lin_test_admin
      user: [email protected]
      scopes: [read, write, issues:create, comments:create, admin]
  strict_scopes: false

GraphQL 接口

支持的查询：

  • viewer
  • organization
  • users、user
  • teams、team
  • workflowStates、workflowState
  • issues、issue
  • comments、comment
  • issueLabels、issueLabel
  • projects、project
  • cycles、cycle
  • webhooks、webhook
  • agentSessions、agentSession

支持的变更：

  • issueCreate、issueUpdate、issueDelete、issueArchive、issueUnarchive
  • commentCreate、commentUpdate、commentDelete
  • issueLabelCreate、issueLabelUpdate、issueLabelDelete
  • issueAddLabel、issueRemoveLabel
  • webhookCreate、webhookDelete
  • agentSessionCreateOnIssue、agentSessionCreateOnComment、agentSessionUpdate
  • agentActivityCreate

连接使用 Relay 风格的游标，包含 nodes、edges 和 pageInfo。

问题查询字段同时提供数字类型的 priority 和 Linear 派生的 priorityLabel 值：No priority、Urgent、High、Medium 和 Low。

OAuth

  • GET /oauth/authorize - 带本地用户选择器的授权端点
  • POST /oauth/authorize/callback - 本地用户选择器回调
  • POST /oauth/token - 授权码、刷新令牌和客户端凭据授权
  • POST /oauth/revoke - 撤销访问令牌或刷新令牌

OAuth 应用可使用 actor: user 或 actor: app。配置的 actor 具有权威性。用户 actor 应用使用授权码流程。App actor 应用使用应用安装流程，并可请求客户端凭据令牌。App actor 支持足以用于本地 Agent 和服务账号测试，但并未完整实现生产环境中的 Linear Agent 行为。

Webhook

通过 webhookCreate 或种子配置创建本地 Webhook 订阅。执行受支持的写入操作时，会分发符合 Linear 格式的负载；配置了密钥时，还会附带 Linear-Delivery、Linear-Event 和 Linear-Signature 标头。

检查器

在 Linear 模拟器中打开 GET /，即可检查问题、团队、用户、项目、Agent 会话、OAuth 应用、令牌、Webhook 订阅和 Webhook 投递记录。

当前限制

尚未实现完整的 Linear 架构覆盖、精确的生产环境速率限制、通知收件箱行为、丰富的文档 API、客户 API、计划 API、精确的搜索相关性以及完整的生产环境 Agent 行为。

与内置模拟器搭配使用自定义模拟器

使用 npx emulate init --custom inventory 搭建第三方 API 模拟器和测试。在 emulate.config.ts 中使用 emulate 提供的 defineConfig 注册该模拟器，并与 { emulator: "linear" } 等内置条目并列。运行 npx emulate start --watch 以重新加载导入项，并在打印出的 /_emulate URL 中检查自定义状态。成功重新加载后，会将本次运行重置为种子状态。现有的扁平种子配置仍可使用；--config 用于选择明确指定的文件。有关第三方 API 模拟器的编写和测试，请参阅 https://emulate.dev/docs/custom-emulators。

评论

支持 Markdown