Arch Flow

ArchFlow

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

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

______________________________________________________________________

什么是ArchFlow？

ArchFlow是一个 MCP（模型上下文协议） 连接的服务器 Jira, GitHub，以及 Draw.io 将图表发送给您的AI编码助手。询问冲刺进度、跟踪代码问题或探索系统架构——所有这些都在一次对话中完成，无需切换选项卡。

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

这是给谁的？

______________________________________________________________________

安装

先决条件

• Python 3.11+ — 下载
• 克劳德代码 --必须安装并工作
• Jira Cloud帐户 （必填）--GitHub和Google Drive是可选的

快速启动（2个命令）

# 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 以交互方式引导您完成所有操作：

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)

在完成之后， 重新启动克劳德代码 并尝试 /archflow-status 或 /archflow-onboard.

健康检查

archflow doctor    # verify all connections

安装方法

之后 archflow init，Claude Code通过以下方式自动运行MCP服务器 uvx --不需要额外的设置。

______________________________________________________________________

你能做什么

对每个人

面向开发者

经理/新成员

______________________________________________________________________

Slash命令

安装后，这些在Claude Code中工作：

您也可以在没有斜线命令的情况下自然地提问——Claude可以直接使用ArchFlow的23个MCP工具。

______________________________________________________________________

MCP工具（23）

在幕后，ArchFlow通过模型上下文协议公开了23个工具：

所有工具都以前缀 archflow_ （例如。， archflow_jira_get_issue).

来源要求

如果未配置源，这些工具将返回“未配置”消息，而不是崩溃。

______________________________________________________________________

配置

配置文件

由...生成 archflow init 在 ~/.archflow/config.yml。随时编辑：

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令牌

archflow init 以交互方式提示这些。供参考：

Jira API Token (2 min)

1. 首选https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击 “创建API令牌” → 输入标签（例如。， archflow)
3. 复制令牌→ 粘贴到 archflow init

GitHub Personal Access Token (2 min, optional)

1. 首选https://github.com/settings/tokens?type=beta
2. 生成新令牌 → 命名它 archflow
3. 权限→ 存储库： 目录, 拉取请求, 元数据 （全部为只读）
4. 复制令牌→ 粘贴到 archflow init

Google Drive OAuth (10 min, optional — only for Draw.io)

1. 谷歌云控制台 → 创建/选择项目
2. API和服务>库 → 启用 Google Drive API
3. 凭证 → 创建 OAuth客户端ID （桌面应用程序）
4. 复制 客户端ID 和 客户端密钥
5. 通过获取刷新令牌 OAuth游乐场:

- 设置→ “使用您自己的OAuth凭据”→ 输入客户端ID/密码 - 第一步：选择 drive.readonly 范围→ 授权 - 第二步：交换→ copy 刷新令牌

How to find board_id / folder_id

Jira板_id --打开你的板，看看网址：

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

谷歌云端硬盘文件夹_id --打开文件夹，查看URL：

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

Manual install (without archflow init)

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"
  }
}'

claude mcp add （无 -json)确实如此 不 传递环境变量。

______________________________________________________________________

建筑

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"]

所有API响应都被缓存（默认30分钟TTL）。重复提问的API调用为零。

______________________________________________________________________

故障排除

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

______________________________________________________________________

贡献

项目结构

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

开发人员设置

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/

承诺公约

: 
Types: feat | fix | refactor | docs | test | chore | perf | ci

______________________________________________________________________

许可证

麻省理工学院——见 许可证 了解详情。