ArchFlow

Jira + GitHub + Draw.io — one MCP server, one question

Install · What You Can Do · Commands · Configuration · Architecture · Contributing · 한국어

What is ArchFlow?

ArchFlow is an MCP (Model Context Protocol) server that connects Jira, GitHub, and Draw.io diagrams to your AI coding assistant. Ask about sprint progress, trace issues to code, or explore system architecture — all in one conversation, without switching tabs.

You: "Where's the code for KAN-42?"

ArchFlow:
  Jira   → KAN-42: "Add OAuth2 login" (In Progress, @alice)
  GitHub → PR #87 "feat: oauth2 login flow" (src/auth/oauth.ts)
  Draw.io → Auth Service → connected to API Gateway, User DB

Who is this for?

Install

Prerequisites

• Python 3.11+ — download
• Claude Code — must be installed and working
• Jira Cloud account (required) — GitHub and Google Drive are optional

Quick Start (2 commands)

# 1. Install the package (pick one)
pip install archflow-hub        # classic
# or
uv pip install archflow-hub    # faster alternative
# or
pipx install archflow-hub      # isolated global install

# 2. Interactive setup — validates tokens, generates config, registers MCP, installs slash commands
archflow init

archflow init walks you through everything interactively:

Jira URL           → https://your-team.atlassian.net
Jira email         → you@company.com
Jira API token     → ********  (validated automatically)
Jira project key   → KAN
Jira board ID      → 1
GitHub token       → ********  (optional, Enter to skip)
Google Drive       → (optional, Enter to skip)

After completion, restart Claude Code and try /archflow-status or /archflow-onboard.

Health Check

archflow doctor    # verify all connections

Install Methods

After archflow init, Claude Code automatically runs the MCP server via uvx — no additional setup needed.

What You Can Do

For everyone

For developers

For managers / new members

Slash Commands

These work in Claude Code after install:

You can also ask naturally without slash commands — ArchFlow's 23 MCP tools are available to Claude directly.

MCP Tools (23)

Under the hood, ArchFlow exposes 23 tools via the Model Context Protocol:

All tools are prefixed with archflow_ (e.g., archflow_jira_get_issue).

Source requirements

If a source is not configured, those tools return a "not configured" message instead of crashing.

Configuration

Config file

Generated by archflow init at ~/.archflow/config.yml. Edit anytime:

jira:
  url: "https://your-team.atlassian.net"
  projects: ["KAN"]
  board_id: "1"

github:
  repos: ["your-org/your-repo"]
  default_branch: "main"

gdrive:
  folder_id: "1AbCdEfG..."
  cache_ttl_minutes: 30

API Tokens

archflow init prompts for these interactively. For reference:

https://your-team.atlassian.net/jira/software/projects/KAN/boards/1
                                                                  ^

https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

pip install archflow-hub   # or: uv pip install archflow-hub

claude mcp add-json --scope user archflow '{
  "type": "stdio",
  "command": "uvx",
  "args": ["archflow-hub"],
  "env": {
    "PYTHONUNBUFFERED": "1",
    "ARCHFLOW_CONFIG_PATH": "~/.archflow/config.yml",
    "JIRA_URL": "https://your-domain.atlassian.net",
    "JIRA_EMAIL": "you@example.com",
    "JIRA_API_TOKEN": "your-jira-api-token",
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
  }
}'

Architecture

graph TB
    User["Your Question"] --> Server

    subgraph Server["ArchFlow MCP Server"]
        Cache["Cache (TTL)"]
        Matcher["Cross-Source Matcher"]
        JP["Jira Provider"]
        GP["GitHub Provider"]
        DP["Draw.io Provider"]
    end

    JP --> Jira["Jira Cloud API"]
    GP --> GitHub["GitHub API"]
    DP --> GDrive["Google Drive"]

All API responses are cached (default 30 min TTL). Repeated questions cost zero API calls.

Troubleshooting

archflow doctor    # checks Python, config, APIs, MCP registration

Contributing

Project Structure

src/archflow/
├── server.py              # MCP server + tool registration
├── cli.py                 # CLI: init, doctor, serve
├── cli_init.py            # Setup wizard (tokens + MCP + slash commands)
├── cli_doctor.py          # Connection diagnostics
├── clients/               # API clients (Jira, GitHub, Google Drive)
├── providers/             # Business logic per source
├── core/                  # Config, cache, matcher, models
├── tools/                 # 23 MCP tools
└── skills/                # 6 slash command definitions

Dev Setup

git clone https://github.com/Juhwan01/ArchFlow.git
cd ArchFlow
uv sync --dev
uv run python -m pytest tests/ -v
uv run ruff check src/

Commit Convention

<type>: <description>
Types: feat | fix | refactor | docs | test | chore | perf | ci

License

MIT — see LICENSE for details.