{ "markdown": "

\n

@cocaxcode/devflow-mcp

\n

\n Your Jira + GitHub/GitLab workflow, handled by your AI assistant.
\n One MCP server. 32 tools. Say what you need, it gets done.\n

\n

\n\n

\n \n \"npm\n \n \n \"downloads\"\n \n \"tools\"\n \"tests\"\n \"node\"\n \n \"license\"\n \n

\n\n

\n Overview ·\n Just Talk to It ·\n Installation ·\n Project Scopes ·\n Tools ·\n Flows ·\n Rules ·\n Storage ·\n Compatibility ·\n Architecture\n

\n\n---\n\n## Overview\n\nThe most complete MCP server for developer workflow automation. 32 tools that connect Jira (Cloud + Server) with GitHub/GitLab (cloud + self-hosted) — so your AI assistant can manage issues, branches, PRs, and deployments without you ever opening a browser tab.\n\nIt auto-detects your Jira version and git provider, enforces configurable safety rules, and lets you define custom YAML flow playbooks for repeatable workflows. Projects are configured once and remembered — each with its own Jira instance, git provider, branch conventions, credentials, and directory scopes. The project that matches your current directory activates automatically (default), or you can switch to another for the session (active). **All credentials stay local in `~/.devflow-mcp/` — nothing is synced, nothing is tracked, nothing leaves your machine.**\n\n---\n\n## Just Talk to It\n\nYou don't memorize tool names. You talk naturally and the assistant picks the right tools.\n\n**\"Set up a project for my Jira + GitHub\"**\n\n```\n> df_project_setup with:\n name: \"my-backend\"\n jiraUrl: \"https://myteam.atlassian.net\"\n jiraEmail: \"dev@myteam.com\"\n jiraToken: \"ATATT3x...\"\n jiraProjectKey: \"PROJ\"\n gitToken: \"ghp_...\"\n\nAuto-detects:\n - Jira Cloud (API v3)\n - GitHub (org/my-backend)\n - Base branch: main\n - Scope: C:/repos/my-backend (your CWD, auto-added)\n```\n\n**\"List my projects\"**\n\n```\nProjects:\n my-backend [default] [active] scopes: C:/repos/my-backend\n my-frontend scopes: C:/repos/my-frontend\n```\n\n**\"Switch to my-frontend for this session\"**\n\n```\nActive project switched to: my-frontend (session only)\nDefault remains: my-backend (based on your current directory)\n```\n\n**\"Let's work on PROJ-123\"**\n\n```\n> Reading PROJ-123...\n Title: Add OAuth login\n Status: To Do | Priority: High\n\n> Branch feat/PROJ-123 not found. Creating...\n branch: feat/PROJ-123-add-oauth-login\n base: main\n Confirm? (confirm: true to execute)\n\n> Moved PROJ-123 → In Progress\n> Assigned to you\n```\n\n**\"Show me my tasks for the ACME project\"**\n\n```\nACME-45 Fix OAuth login In Progress High\nACME-52 Dashboard refactor To Do Medium\nACME-61 Update dependencies To Do Low\n```\n\n**\"Push my changes\"**\n\n```\nPreview:\n branch: feat/PROJ-123-add-oauth-login\n pending commits:\n - a1b2c3d feat: add login component\n - d4e5f6g feat: add auth service\n\nConfirm? (confirm: true to execute)\n```\n\n**\"Merge main into my current branch\"**\n\n```\nConflict detected:\n - src/auth/login.ts\n - src/config/routes.ts\n\nResolve the files and commit to complete the merge.\n```\n\n**\"Create a PR titled 'feat: add OAuth login'\"**\n\n```\nPR created:\n url: https://github.com/org/repo/pull/42\n title: feat: add OAuth login\n provider: github\n```\n\n**\"Comment on PROJ-123 that the PR is ready for review\"**\n\n```\nPreview:\n issue: PROJ-123\n comment: \"PR ready for review: https://github.com/org/repo/pull/42\"\n\nConfirm? (confirm: true to publish)\n```\n\n**\"Create a fix branch for PROJ-456 with description fix-oauth-redirect\"**\n\n```\nPreview:\n branch: fix/PROJ-456-fix-oauth-redirect\n base: main\n actions: checkout main → pull → create branch\n\nConfirm? (confirm: true to execute)\n```\n\n---\n\n## Installation\n\n### Claude Code (recommended)\n\n```bash\n# Global — available across all your projects\nclaude mcp add --scope user devflow -- npx -y @cocaxcode/devflow-mcp@latest\n\n# Per-project\nclaude mcp add devflow -- npx -y @cocaxcode/devflow-mcp@latest\n```\n\n### Claude Desktop\n\n
\nmacOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n\n```json\n{\n \"mcpServers\": {\n \"devflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cocaxcode/devflow-mcp@latest\"]\n }\n }\n}\n```\n
\n\n
\nWindows: %APPDATA%\\Claude\\claude_desktop_config.json\n\n```json\n{\n \"mcpServers\": {\n \"devflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cocaxcode/devflow-mcp@latest\"]\n }\n }\n}\n```\n
\n\n### Cursor / Windsurf\n\n```json\n// .cursor/mcp.json or .windsurf/mcp.json\n{\n \"mcpServers\": {\n \"devflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cocaxcode/devflow-mcp@latest\"]\n }\n }\n}\n```\n\n### VS Code / Codex / Gemini CLI\n\n```json\n{\n \"mcpServers\": {\n \"devflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cocaxcode/devflow-mcp@latest\"]\n }\n }\n}\n```\n\n---\n\n## Project Scopes\n\nEach project has **paths** (scopes) — the directories that belong to it. A directory can only be the scope of one project.\n\nThis gives you two concepts:\n\n- **Default project**: The project whose scope matches your current working directory. This is automatic and persistent — if you are inside `C:/repos/my-backend` and that directory is a scope of `my-backend`, then `my-backend` is the default. No action needed.\n\n- **Active project**: The project you are currently working with. By default it equals the default project, but you can switch it manually with `df_project_switch` for the current session. This resets to the default when you restart.\n\n`df_project_list` shows both the **default** and **active** indicators so you always know where you stand.\n\n### Practical example\n\n```\n\"Set up a project called my-backend\"\n → CWD (C:/repos/my-backend) is auto-added as scope\n\n\"Set up another called my-frontend\"\n → Run from C:/repos/my-frontend, that directory becomes its scope\n\n\"List projects\"\n → my-backend [default] [active] scopes: C:/repos/my-backend\n my-frontend scopes: C:/repos/my-frontend\n\n\"Switch to my-frontend\"\n → Session switches. Now my-frontend is active for checking issues, etc.\n\n\"List projects\"\n → my-backend [default] scopes: C:/repos/my-backend\n my-frontend [active] scopes: C:/repos/my-frontend\n\nClose and reopen → my-backend is active again (matches CWD = default)\n```\n\nThis means you can work across multiple projects with different Jira instances and git providers — the right credentials are always selected based on where you are, and you can always override for the session when needed.\n\n---\n\n## Tools\n\n32 tools organized in 5 categories.\n\n### Projects (5)\n\n| Tool | Description |\n|------|-------------|\n| `df_project_setup` | Configure a new project (Jira + Git, auto-detects everything) |\n| `df_project_update` | Modify project configuration |\n| `df_project_list` | List all configured projects (shows default + active) |\n| `df_project_switch` | Switch the active project for the current session |\n| `df_project_delete` | Delete a project |\n\n
\nExample: setting up a project\n\n```\ndf_project_setup with:\n name: \"my-project\"\n jiraUrl: \"https://myteam.atlassian.net\"\n jiraEmail: \"dev@myteam.com\"\n jiraToken: \"ATATT3x...\"\n jiraProjectKey: \"PROJ\"\n gitToken: \"ghp_...\"\n\nAuto-detects:\n - Jira Cloud (API v3)\n - GitHub (org/my-project)\n - Base branch: main\n - Scope: your CWD (auto-added)\n```\n
\n\n### Jira (6)\n\n| Tool | Description | Confirmation |\n|------|-------------|:---:|\n| `df_issues` | List my assigned issues (filters by project) | -- |\n| `df_issue` | Full issue detail | -- |\n| `df_statuses` | Available transitions for an issue | -- |\n| `df_transition` | Move issue to another status | Yes |\n| `df_assign` | Assign issue to current user | -- |\n| `df_comment` | Comment on an issue | Yes |\n\n### Git (7)\n\n| Tool | Description | Confirmation |\n|------|-------------|:---:|\n| `df_branch` | Create branch (`feat/` or `fix/`) from base | Yes |\n| `df_find_branch` | Search branch by issue key | -- |\n| `df_checkout` | Switch branch (with safety guard) | -- |\n| `df_pull` | Pull current branch from remote | -- |\n| `df_push` | Push current branch to remote | Yes |\n| `df_merge` | Merge a branch into the current one | Yes |\n| `df_pr` | Create PR (GitHub) or MR (GitLab) | -- |\n\n> **Important:** `df_branch`, `df_checkout`, and `df_push` verify the working directory before executing. They **block if there are uncommitted files or unpushed commits**, listing exactly what needs attention. This prevents accidental work loss.\n\n### Flows (5)\n\n| Tool | Description |\n|------|-------------|\n| `df_flow_create` | Create a custom flow |\n| `df_flow_list` | List all flows |\n| `df_flow_get` | View flow details |\n| `df_flow_update` | Modify an existing flow |\n| `df_flow_delete` | Delete a flow (protects `start-task`) |\n\n### Rules (9)\n\n| Tool | Description | Level |\n|------|-------------|-------|\n| `df_rule_create` | Create a global rule | Global |\n| `df_rule_list` | List all rules | Global |\n| `df_rule_get` | View rule details | Global |\n| `df_rule_update` | Modify a rule | Global |\n| `df_rule_toggle` | Enable/disable a rule | Global |\n| `df_rule_delete` | Delete a rule | Global |\n| `df_rule_project_override` | Enable/disable a global rule for a project | Project |\n| `df_rule_project_add` | Create a project-only rule | Project |\n| `df_rule_project_remove` | Remove a project rule or override | Project |\n\n---\n\n## Flows\n\nFlows are YAML playbooks that define step sequences. They don't run automatically -- you tell the assistant when to use them.\n\n### Default: `start-task`\n\nTriggered when you say something like _\"let's work on PROJ-123\"_:\n\n```yaml\nname: start-task\ntrigger: \"when the user says 'let's work on', 'start task', 'new task' + issue ID\"\nsteps:\n - tool: df_issue\n note: \"Read issue detail and summarize the task\"\n - tool: df_find_branch\n note: \"Check if a branch already exists for this issue\"\n - tool: df_branch\n confirm: true\n note: \"Only if no existing branch was found\"\n - tool: df_statuses\n note: \"Get transitions to find the 'In Progress' transition ID\"\n - tool: df_transition\n target: \"In Progress\"\n confirm: true\n - tool: df_assign\n note: \"Assign the issue if it has no assignee\"\n```\n\n### Custom flows\n\nCreate your own by asking naturally:\n\n> _\"Create a flow called 'finish-task' that pushes, creates a PR, and comments on Jira\"_\n\n```yaml\nname: finish-task\ntrigger: \"when the user says 'finish task', 'wrap up' + issue ID\"\nsteps:\n - tool: df_push\n confirm: true\n note: \"Push pending commits\"\n - tool: df_pr\n note: \"Create PR/MR to base branch\"\n - tool: df_comment\n confirm: true\n note: \"Comment on the issue with the PR link\"\n```\n\nThe `start-task` flow can be modified but not deleted. Use `df_flow_update` to change any flow's steps, trigger, or name.\n\n---\n\n## Rules\n\nRules are configurable guards that block or warn about actions. Two levels: global and per-project.\n\n### Default rules\n\n| Rule | Scope | Action | What it does |\n|------|-------|--------|-------------|\n| `no-merge-to-base` | git | block | Prevent direct push/merge to main/master |\n| `no-merge-from-dev` | git | block | Prevent merging dev/develop/int branches out |\n| `no-close-issues` | jira | block | Prevent closing issues (Done, Closed, Resolved...) |\n| `only-own-issues` | jira | block | Prevent modifying issues assigned to others |\n\n### Project overrides\n\nEach project can override global rules or define its own:\n\n```\n# Disable a global rule for one project\ndf_rule_project_override: name=\"no-close-issues\", enabled=false\n\n# Add a project-only rule\ndf_rule_project_add: name=\"no-push-friday\", scope=\"git\", action=\"warn\"\n\n# Remove an override or project rule\ndf_rule_project_remove: name=\"no-close-issues\"\n```\n\n### Custom rules\n\n```\ndf_rule_create:\n name: \"no-push-friday\"\n description: \"Warn when pushing on Fridays\"\n scope: \"git\" # git | jira | all\n action: \"warn\" # block | warn\n```\n\n> **Note:** **Rule resolution order:** Global rules load first, then project overrides are applied (project wins), then project-specific rules are added. Rules are filtered by scope and enabled state before evaluation.\n\n---\n\n## Storage\n\nEverything lives in `~/.devflow-mcp/` — your home directory, never inside any git repository. Jira tokens, GitHub PATs, GitLab tokens — all stored locally with `600` permissions (owner-only read/write). Nothing gets committed, nothing gets pushed, nothing leaves your machine.\n\n```\n~/.devflow-mcp/\n├── projects/ # Project configs (.json) — credentials included\n│ ├── my-project.json # Jira URL, token, GitHub PAT, branch rules, scopes\n│ └── other-project.json\n├── flows/ # Flow definitions (.yaml)\n│ └── start-task.yaml\n├── rules/ # Global rules (.json)\n│ ├── no-merge-to-base.json\n│ ├── no-merge-from-dev.json\n│ ├── no-close-issues.json\n│ └── only-own-issues.json\n├── active-project # Current active project (plain text)\n└── config.json # Server configuration\n```\n\n**Project resolution works automatically:** devflow-mcp matches your current working directory against each project's `paths` (scopes). The matching project becomes the **default**. You can override it for the session with `df_project_switch`, which sets the **active** project. On restart, the active project resets to whatever the default is for your CWD. If no match is found and no active project is set, it prompts you to configure with `df_project_setup`.\n\n---\n\n## Compatibility\n\n### Jira\n\n| Type | API | Authentication |\n|------|-----|----------------|\n| Jira Cloud | REST API v3 | Email + API Token (Basic) |\n| Jira Server / Data Center | REST API v2 | Personal Access Token (Bearer) |\n\nAuto-detection via `/rest/api/2/serverInfo` -- no manual configuration needed.\n\n### Git providers\n\n| Provider | API |\n|----------|-----|\n| GitHub (cloud) | REST API v3 |\n| GitHub Enterprise | REST API v3 (custom URL) |\n| GitLab (cloud) | REST API v4 |\n| GitLab self-hosted | REST API v4 (custom URL) |\n\nAuto-detection by parsing the repository's remote URL.\n\n---\n\n## Architecture\n\n```\nsrc/\n├── index.ts # Entry point (stdio transport)\n├── server.ts # Factory: createServer() + instructions\n├── lib/\n│ ├── types.ts # Interfaces, defaults, valid tool names\n│ ├── storage.ts # CRUD: projects, flows, rules, config\n│ ├── git-exec.ts # Git CLI wrapper (execFile)\n│ ├── jira/\n│ │ ├── client.ts # JiraClient (Cloud v3 + Server v2)\n│ │ └── types.ts # Raw Jira API response shapes\n│ └── git/\n│ ├── detect.ts # parseRemoteUrl (SSH/HTTPS, GitHub/GitLab)\n│ ├── github.ts # GitHubClient (REST API v3)\n│ ├── gitlab.ts # GitLabClient (REST API v4)\n│ ├── factory.ts # createGitProviderClient()\n│ └── types.ts # Git provider interfaces\n└── tools/\n ├── project.ts # 5 tools: setup, update, list, switch, delete\n ├── jira.ts # 6 tools: issues, issue, statuses, transition, assign, comment\n ├── git.ts # 7 tools: branch, find_branch, checkout, pull, push, merge, pr\n ├── flow.ts # 5 tools: create, list, get, update, delete\n └── rule.ts # 9 tools: CRUD global + 3 project-level\n```\n\n**Stack:** TypeScript · MCP SDK · Zod · YAML · tsup\n\n**Tests:** 4 suites · 51 tests (Vitest + InMemoryTransport)\n\n---\n\n[MIT](./LICENSE) · Built by [cocaxcode](https://github.com/cocaxcode)\n", "bytes": 16685, "sha": "c171fc093abdc1412b9f5bafef40f61ca6d3aacc7466fd32a067e53b3f322378", "repo_slug": "cocaxcode/devflow-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_cocaxcode_devflow_mcp_833378ec/readme" }