devflow-mcp

@cocaxcode/devflow-mcp

由 AI 助手处理你的 Jira + GitHub/GitLab 工作流。
一个 MCP 服务，32 个工具。说出你的需求，它就会帮你完成。

概述 · 直接对话 · 安装 · 项目范围 · 工具 · 工作流 · 规则 · 存储 · 兼容性 · 架构

概述

面向开发者工作流自动化的最完整 MCP 服务。32 个工具可连接 Jira（Cloud + Server）与 GitHub/GitLab（云端 + 可自托管），让你的 AI 助手管理问题、分支、PR 和部署，无需打开浏览器标签页。

它会自动检测你的 Jira 版本和 Git 提供商，强制执行可配置的安全规则，并允许你定义自定义 YAML 工作流手册，以便重复执行工作流。项目只需配置一次，之后便会被记住——每个项目都有自己的 Jira 实例、Git 提供商、分支约定、凭据和目录范围。与当前目录匹配的项目会自动激活（默认），你也可以在当前会话中切换到其他项目（活动项目）。所有凭据都保留在本地的 ~/.devflow-mcp/ 中——不会同步、不会被跟踪，也不会离开你的机器。

直接对话

你无需记住工具名称。只要自然地对话，助手就会选择合适的工具。

“为我的 Jira + GitHub 配置一个项目”

> df_project_setup with:
    name: "my-backend"
    jiraUrl: "https://myteam.atlassian.net"
    jiraEmail: "[email protected]"
    jiraToken: "ATATT3x..."
    jiraProjectKey: "PROJ"
    gitToken: "ghp_..."

Auto-detects:
  - Jira Cloud (API v3)
  - GitHub (org/my-backend)
  - Base branch: main
  - Scope: C:/repos/my-backend (your CWD, auto-added)

“列出我的项目”

Projects:
  my-backend    [default] [active]   scopes: C:/repos/my-backend
  my-frontend                        scopes: C:/repos/my-frontend

“在本次会话中切换到 my-frontend”

Active project switched to: my-frontend (session only)
Default remains: my-backend (based on your current directory)

“我们来处理 PROJ-123”

> Reading PROJ-123...
  Title: Add OAuth login
  Status: To Do | Priority: High

> Branch feat/PROJ-123 not found. Creating...
  branch: feat/PROJ-123-add-oauth-login
  base: main
  Confirm? (confirm: true to execute)

> Moved PROJ-123 → In Progress
> Assigned to you

“显示 ACME 项目中的任务”

ACME-45  Fix OAuth login             In Progress  High
ACME-52  Dashboard refactor          To Do        Medium
ACME-61  Update dependencies         To Do        Low

“推送我的更改”

Preview:
  branch: feat/PROJ-123-add-oauth-login
  pending commits:
    - a1b2c3d feat: add login component
    - d4e5f6g feat: add auth service

Confirm? (confirm: true to execute)

“将 main 合并到我当前的分支”

Conflict detected:
  - src/auth/login.ts
  - src/config/routes.ts

Resolve the files and commit to complete the merge.

“创建一个标题为 ‘feat: add OAuth login’ 的 PR”

PR created:
  url: https://github.com/org/repo/pull/42
  title: feat: add OAuth login
  provider: github

“在 PROJ-123 下评论，说明 PR 已准备好进行审查”

Preview:
  issue: PROJ-123
  comment: "PR ready for review: https://github.com/org/repo/pull/42"

Confirm? (confirm: true to publish)

“为 PROJ-456 创建一个修复分支，描述为 fix-oauth-redirect”

Preview:
  branch: fix/PROJ-456-fix-oauth-redirect
  base: main
  actions: checkout main → pull → create branch

Confirm? (confirm: true to execute)

安装

Claude Code（推荐）

# Global — available across all your projects
claude mcp add --scope user devflow -- npx -y @cocaxcode/devflow-mcp@latest

# Per-project
claude mcp add devflow -- npx -y @cocaxcode/devflow-mcp@latest

Claude Desktop

{
  "mcpServers": {
    "devflow": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/devflow-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "devflow": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/devflow-mcp@latest"]
    }
  }
}

Cursor / Windsurf

// .cursor/mcp.json or .windsurf/mcp.json
{
  "mcpServers": {
    "devflow": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/devflow-mcp@latest"]
    }
  }
}

VS Code / Codex / Gemini CLI

{
  "mcpServers": {
    "devflow": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/devflow-mcp@latest"]
    }
  }
}

项目范围

每个项目都有路径（范围），即属于该项目的目录。一个目录只能作为一个项目的范围。

这涉及两个概念：

• 默认项目：范围与当前工作目录匹配的项目。这是自动且持久的——如果你位于 C:/repos/my-backend，且该目录是 my-backend 的范围，那么 my-backend 就是默认项目。无需执行任何操作。

• 活动项目：你当前正在使用的项目。默认情况下，它等于默认项目，但你可以使用 df_project_switch 手动切换当前会话中的活动项目。重启后会重置为默认项目。

df_project_list 会显示默认和活动标记，让你随时了解当前状态。

实际示例

"Set up a project called my-backend"
  → CWD (C:/repos/my-backend) is auto-added as scope

"Set up another called my-frontend"
  → Run from C:/repos/my-frontend, that directory becomes its scope

"List projects"
  → my-backend   [default] [active]    scopes: C:/repos/my-backend
     my-frontend                        scopes: C:/repos/my-frontend

"Switch to my-frontend"
  → Session switches. Now my-frontend is active for checking issues, etc.

"List projects"
  → my-backend   [default]             scopes: C:/repos/my-backend
     my-frontend  [active]              scopes: C:/repos/my-frontend

Close and reopen → my-backend is active again (matches CWD = default)

这意味着你可以在多个项目之间协作，每个项目使用不同的 Jira 实例和 Git 提供商——系统始终会根据你所在的位置选择正确的凭据；需要时，你也可以在当前会话中随时切换。

工具

共有 32 个工具，分为 5 个类别。

项目（5）

df_project_setup with:
  name: "my-project"
  jiraUrl: "https://myteam.atlassian.net"
  jiraEmail: "[email protected]"
  jiraToken: "ATATT3x..."
  jiraProjectKey: "PROJ"
  gitToken: "ghp_..."

Auto-detects:
  - Jira Cloud (API v3)
  - GitHub (org/my-project)
  - Base branch: main
  - Scope: your CWD (auto-added)

Jira（6）

Git（7）

重要：df_branch、df_checkout 和 df_push 在执行前会检查工作目录。如果存在未提交的文件或未推送的提交，它们会阻止操作，并准确列出需要处理的内容。这可以防止意外丢失工作成果。

工作流（5）

规则（9）

工作流

工作流是定义步骤序列的 YAML 操作手册。它们不会自动运行——你需要告诉助手何时使用。

默认工作流：start-task

当你说类似 “我们来处理 PROJ-123” 的话时触发：

name: start-task
trigger: "when the user says 'let's work on', 'start task', 'new task' + issue ID"
steps:
  - tool: df_issue
    note: "Read issue detail and summarize the task"
  - tool: df_find_branch
    note: "Check if a branch already exists for this issue"
  - tool: df_branch
    confirm: true
    note: "Only if no existing branch was found"
  - tool: df_statuses
    note: "Get transitions to find the 'In Progress' transition ID"
  - tool: df_transition
    target: "In Progress"
    confirm: true
  - tool: df_assign
    note: "Assign the issue if it has no assignee"

自定义工作流

用自然语言创建自己的工作流：

“创建一个名为 ‘finish-task’ 的工作流，用于推送、创建 PR 并在 Jira 上发表评论。”

name: finish-task
trigger: "when the user says 'finish task', 'wrap up' + issue ID"
steps:
  - tool: df_push
    confirm: true
    note: "Push pending commits"
  - tool: df_pr
    note: "Create PR/MR to base branch"
  - tool: df_comment
    confirm: true
    note: "Comment on the issue with the PR link"

可以修改 start-task 工作流，但不能删除。使用 df_flow_update 更改任意工作流的步骤、触发条件或名称。

规则

规则是可配置的防护措施，用于阻止操作或发出警告。分为两个级别：全局和按项目配置。

默认规则

项目级覆盖规则

每个项目都可以覆盖全局规则，或定义自己的规则：

# Disable a global rule for one project
df_rule_project_override: name="no-close-issues", enabled=false

# Add a project-only rule
df_rule_project_add: name="no-push-friday", scope="git", action="warn"

# Remove an override or project rule
df_rule_project_remove: name="no-close-issues"

自定义规则

df_rule_create:
  name: "no-push-friday"
  description: "Warn when pushing on Fridays"
  scope: "git"       # git | jira | all
  action: "warn"     # block | warn

注意： **规则解析顺序：**先加载全局规则，再应用项目覆盖规则（以项目规则为准），最后添加项目专属规则。评估前会根据范围和启用状态筛选规则。

存储

所有内容都存储在 ~/.devflow-mcp/ 中，即你的主目录，绝不会存放在任何 git 仓库内。Jira 令牌、GitHub PAT、GitLab 令牌均在本地以 600 权限（仅所有者可读写）存储。不会提交任何内容，不会推送任何内容，也不会有任何内容离开你的计算机。

~/.devflow-mcp/
├── projects/              # Project configs (.json) — credentials included
│   ├── my-project.json    # Jira URL, token, GitHub PAT, branch rules, scopes
│   └── other-project.json
├── flows/                 # Flow definitions (.yaml)
│   └── start-task.yaml
├── rules/                 # Global rules (.json)
│   ├── no-merge-to-base.json
│   ├── no-merge-from-dev.json
│   ├── no-close-issues.json
│   └── only-own-issues.json
├── active-project         # Current active project (plain text)
└── config.json            # Server configuration

项目解析会自动完成：devflow-mcp 会将你的当前工作目录与各项目的 paths（范围）进行匹配。匹配到的项目将成为默认项目。你可以使用 df_project_switch 为当前会话切换项目，将其设为活动项目。重启后，活动项目会重置为当前工作目录对应的默认项目。如果没有匹配项，且未设置活动项目，系统会提示你使用 df_project_setup 进行配置。

兼容性

Jira

通过 /rest/api/2/serverInfo 自动检测——无需手动配置。

Git 提供商

通过解析仓库的远程 URL 自动检测。

架构

src/
├── index.ts              # Entry point (stdio transport)
├── server.ts             # Factory: createServer() + instructions
├── lib/
│   ├── types.ts          # Interfaces, defaults, valid tool names
│   ├── storage.ts        # CRUD: projects, flows, rules, config
│   ├── git-exec.ts       # Git CLI wrapper (execFile)
│   ├── jira/
│   │   ├── client.ts     # JiraClient (Cloud v3 + Server v2)
│   │   └── types.ts      # Raw Jira API response shapes
│   └── git/
│       ├── detect.ts     # parseRemoteUrl (SSH/HTTPS, GitHub/GitLab)
│       ├── github.ts     # GitHubClient (REST API v3)
│       ├── gitlab.ts     # GitLabClient (REST API v4)
│       ├── factory.ts    # createGitProviderClient()
│       └── types.ts      # Git provider interfaces
└── tools/
    ├── project.ts        # 5 tools: setup, update, list, switch, delete
    ├── jira.ts           # 6 tools: issues, issue, statuses, transition, assign, comment
    ├── git.ts            # 7 tools: branch, find_branch, checkout, pull, push, merge, pr
    ├── flow.ts           # 5 tools: create, list, get, update, delete
    └── rule.ts           # 9 tools: CRUD global + 3 project-level

**技术栈：**TypeScript · MCP SDK · Zod · YAML · tsup

**测试：**4 个测试套件 · 51 个测试（Vitest + InMemoryTransport）

MIT · 由 cocaxcode 构建