Quire

Quire MCP 服务

这是一个面向 Quire 项目管理平台的 Model Context Protocol（MCP） 服务。

此服务可让 AI 助手（例如 Claude）安全地与 Quire 项目、任务和数据交互。

快速开始

前置条件

• Node.js v22 或更高版本
• Quire 账户
• Quire OAuth 应用（请参阅创建 Quire OAuth 应用）

步骤 1：创建 Quire OAuth 应用

1. 前往 Quire 应用管理
2. 点击 Create new app
3. 将 Redirect URL 设为：http://localhost:3000/callback
4. 选择所需的权限范围
5. 复制 Development Client ID 和 Development Client Secret

步骤 2：配置 MCP 客户端

选择与你的 MCP 客户端相匹配的设置方式：

Claude Desktop（推荐）

将以下内容添加到你的 claude_desktop_config.json：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_OAUTH_CLIENT_ID": "your-client-id",
        "QUIRE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code（CLI）

将以下内容添加到 Claude Code MCP 设置（~/.claude/mcp.json 或项目级设置）：

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_OAUTH_CLIENT_ID": "your-client-id",
        "QUIRE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor

在 Cursor 设置中添加 MCP 服务：

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_OAUTH_CLIENT_ID": "your-client-id",
        "QUIRE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

步骤 3：首次授权

首次使用时，服务会：

1. 在控制台输出授权 URL
2. 等待你在浏览器中打开该 URL
3. 授权后，Quire 会重定向到 localhost
4. 服务会捕获令牌并缓存

之后使用时，令牌会按需自动刷新。

传输模式

此服务支持两种传输模式：stdio（默认）和 http。

STDIO 模式（默认）

STDIO 模式是最简单的设置方式。MCP 客户端会直接启动服务进程，并通过 stdin/stdout 使用 JSON-RPC 进行通信。

工作原理：

1. MCP 客户端通过环境变量启动 npx quire-mcp
2. 首次调用工具时，如果没有缓存的令牌，服务会将 OAuth URL 输出到 stderr
3. 用户在浏览器中打开该 URL 并授权
4. Quire 会重定向到 localhost:3000/callback，由服务捕获令牌
5. 令牌会缓存到磁盘，供后续使用

令牌缓存位置：

• Windows：%APPDATA%\quire-mcp\tokens.json
• macOS：~/Library/Application Support/quire-mcp/tokens.json
• Linux：~/.config/quire-mcp/tokens.json

HTTP 模式

HTTP 模式会运行带有 OAuth 2.0 端点的 HTTP 服务。适用于以下场景：

• 需要长期运行的服务进程
• 多个客户端连接到同一个服务
• 部署到远程主机（例如 Cloudflare Workers、云 VM）

重要提示： 在 HTTP 模式下，客户端连接前必须先启动服务。环境变量应设置在服务进程中，而不是客户端配置中。

在本地运行 HTTP 模式

第 1 步： 启动服务：

# Using npx
QUIRE_OAUTH_CLIENT_ID=your-client-id \
QUIRE_OAUTH_CLIENT_SECRET=your-client-secret \
MCP_TRANSPORT=http \
npx quire-mcp

# Or using pnpm (for development)
pnpm dev:http

服务将输出：

[quire-mcp] HTTP server listening on 127.0.0.1:3001
[quire-mcp] OAuth metadata: http://localhost:3001/.well-known/oauth-authorization-server
[quire-mcp] MCP endpoint: http://localhost:3001/mcp

第 2 步： 配置 MCP 客户端以连接：

{
  "mcpServers": {
    "quire": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

注意： HTTP 模式下，客户端配置中无需 env 部分——OAuth 凭据位于服务端。

第 3 步： MCP 客户端连接后，将会：

1. 通过 /.well-known/oauth-authorization-server 发现 OAuth 端点
2. 将你重定向到 Quire 进行授权
3. 交换令牌并建立会话

HTTP 模式环境变量

变量	必需	默认值	描述
MCP_TRANSPORT	是	stdio	设为 http 以启用 HTTP 模式
QUIRE_OAUTH_CLIENT_ID	是	-	Quire OAuth 客户端 ID
QUIRE_OAUTH_CLIENT_SECRET	是	-	Quire OAuth 客户端密钥
MCP_SERVER_HOST	否	127.0.0.1	HTTP 服务绑定的主机
MCP_SERVER_PORT	否	3001	HTTP 服务端口
MCP_ISSUER_URL	否	http://localhost:3001	OAuth 端点的基础 URL
QUIRE_OAUTH_REDIRECT_URI	否	http://localhost:3001/oauth/callback	Quire OAuth 回调 URL

HTTP 模式的 Quire 应用配置： 使用 HTTP 模式时，请将 Quire 应用的重定向 URL 更新为：http://localhost:3001/oauth/callback

手动令牌模式

如果你已有预先获取的访问令牌（例如，从 Postman 获取），可以完全跳过 OAuth：

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

注意： 手动获取的令牌最终会过期，且没有 OAuth 凭据时不会自动刷新。

配置参考

所有环境变量

变量	必需	默认值	描述
QUIRE_OAUTH_CLIENT_ID	是*	-	Quire OAuth 客户端 ID
QUIRE_OAUTH_CLIENT_SECRET	是*	-	Quire OAuth 客户端密钥
QUIRE_ACCESS_TOKEN	否	-	手动覆盖令牌（跳过 OAuth 流程）
QUIRE_OAUTH_REDIRECT_URI	否	http://localhost:3000/callback	OAuth 回调 URL（stdio 模式）
QUIRE_TOKEN_STORE_PATH	否	平台默认值	令牌缓存文件的路径
MCP_TRANSPORT	否	stdio	传输模式：stdio 或 http
MCP_SERVER_HOST	否	127.0.0.1	HTTP 服务绑定地址
MCP_SERVER_PORT	否	3001	HTTP 服务端口
MCP_ISSUER_URL	否	http://localhost:3001	OAuth 签发方 URL（HTTP 模式）

*除非设置了 QUIRE_ACCESS_TOKEN，否则为必需。

功能

工具

该服务按类别提供 60+ 个工具：

身份验证

工具	描述
quire.whoami	获取当前已认证用户的个人资料

组织

工具	描述
quire.listOrganizations	列出所有可访问的组织
quire.getOrganization	按 ID 或 OID 获取组织详情
quire.updateOrganization	更新组织关注者

项目

工具	描述
quire.listProjects	列出所有项目，可按组织筛选
quire.getProject	获取项目详情，包括任务数量
quire.updateProject	更新项目名称、描述、图标和关注者
quire.exportProject	以 JSON 或 CSV 格式导出项目任务

任务

工具	描述
quire.listTasks	列出项目中的任务（顶层任务或子任务）
quire.getTask	按项目 ID 和任务 ID 或 OID 获取任务详情
quire.createTask	创建新任务，可选设置优先级、日期、受派人和标签
quire.updateTask	更新任务属性
quire.deleteTask	删除任务及其子任务
quire.searchTasks	按关键字和筛选条件搜索项目中的任务
quire.createTaskAfter	在指定任务后创建任务
quire.createTaskBefore	在指定任务前创建任务
quire.searchFolderTasks	搜索文件夹中的任务
quire.searchOrganizationTasks	搜索整个组织中的任务

标签

工具	描述
quire.listTags	列出项目中的所有标签
quire.getTag	按 OID 获取标签详情
quire.createTag	创建带名称和颜色的新标签
quire.updateTag	更新标签名称或颜色
quire.deleteTag	删除标签

评论

工具	描述
quire.listTaskComments	列出任务的所有评论
quire.addTaskComment	为任务添加评论
quire.updateComment	更新评论文本
quire.deleteComment	删除评论
quire.listChatComments	列出聊天频道中的所有评论
quire.addChatComment	在聊天频道中添加评论

用户

工具	描述
quire.getUser	按 ID、OID 或电子邮件获取用户详情
quire.listUsers	列出所有可访问的用户
quire.listProjectMembers	列出项目的所有成员

自定义状态

工具	描述
quire.listStatuses	列出项目中的自定义状态
quire.getStatus	按值获取状态详情
quire.createStatus	创建自定义工作流状态
quire.updateStatus	更新状态名称或颜色
quire.deleteStatus	删除自定义状态

外部团队（合作伙伴）

工具	描述
quire.getPartner	获取外部团队详情
quire.listPartners	列出项目中的所有外部团队

文档

工具	描述
quire.createDocument	在组织或项目中创建文档
quire.getDocument	获取文档内容和元数据
quire.listDocuments	列出所有文档
quire.updateDocument	更新文档名称或内容
quire.deleteDocument	删除文档

子列表

工具	描述
quire.createSublist	创建子列表
quire.getSublist	获取子列表详情
quire.listSublists	列出所有子列表
quire.updateSublist	更新子列表名称或描述
quire.deleteSublist	删除子列表

聊天频道

工具	描述
quire.createChat	创建聊天频道
quire.getChat	获取聊天频道详情
quire.listChats	列出所有聊天频道
quire.updateChat	更新聊天名称、描述或成员
quire.deleteChat	删除聊天频道

键值存储

工具	描述
quire.getStorageValue	按键获取已存储的值
quire.listStorageEntries	按前缀列出存储条目
quire.putStorageValue	存储一个值
quire.deleteStorageValue	删除已存储的值

通知

工具	描述
quire.sendNotification	向用户发送通知

附件

工具	描述
quire.uploadTaskAttachment	向任务上传文件附件
quire.uploadCommentAttachment	向评论上传文件附件

资源

该服务将数据作为 MCP 资源公开：

静态资源

资源 URI	描述
quire://user/me	当前已验证用户的个人资料
quire://organizations	所有可访问组织的列表
quire://projects	所有可访问项目的列表

资源模板

资源 URI	描述
quire://project/{id}	特定项目的详情和元数据
quire://project/{projectId}/tasks	项目中的根任务
quire://project/{projectId}/tags	项目中定义的标签
quire://project/{projectId}/statuses	项目中的自定义状态

提示词

该服务为常见工作流提供了引导式提示词：

提示词	描述
quire.create-project-plan	根据目标描述生成任务计划
quire.daily-standup	生成每日站会摘要
quire.sprint-planning	根据待办列表规划冲刺
quire.task-breakdown	将复杂任务拆分为子任务
quire.weekly-summary	生成每周进度报告

开发

设置

# Clone the repo
git clone https://github.com/jacob-hartmann/quire-mcp.git
cd quire-mcp

# Use the Node.js version from .nvmrc
# (macOS/Linux nvm): nvm install && nvm use
# (Windows nvm-windows): nvm install 22 && nvm use 22
nvm install
nvm use

# Install dependencies
pnpm install

# Copy .env.example and configure
cp .env.example .env
# Edit .env with your OAuth credentials

本地运行

# Development mode (stdio, auto-reload)
pnpm dev

# Development mode (http, auto-reload)
pnpm dev:http

# Production build
pnpm build

# Production run
pnpm start        # stdio mode
pnpm start:http   # http mode

调试

你可以使用 MCP Inspector 调试该服务：

# Run from source
pnpm inspect

# Run from built output
pnpm inspect:dist

pnpm inspect 会通过 dotenv 自动加载 .env（参见 .env.example）。

如果看到 Ignored build scripts: esbuild...，请运行 pnpm approve-builds 并允许 esbuild。 在 CI 中，我们会禁用生命周期脚本安装依赖（pnpm install --ignore-scripts），然后仅为生产构建作业显式重新构建 esbuild。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解如何为本项目做出贡献。

安全

安全政策及漏洞报告方式请参阅 SECURITY.md。

支持

这是一个社区项目，按“现状”提供，不保证提供支持。详情请参阅 SUPPORT.md。

许可证

MIT © Jacob Hartmann