使用说明

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

这是给谁的？

角色	示例
首席执行官/项目经理	“冲刺进度如何？”·“每周团队报告”
新团队成员	“解释我们的系统架构”·“我应该先看什么？”
开发者	“KAN-123的代码在哪里？”·“哪些PR与身份验证相关？”

安装

先决条件

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

安装方法

方法	说明	何时使用
`pip install archflow-hub`	经典pip安装	如果不使用uv，则默认选项
`uv pip install archflow-hub`	通过紫外线安装（速度快10-100x）	如果你有紫外线已安装
`pipx install archflow-hub`	隔离全局安装	CLI工具不会污染全局环境
`uvx archflow-hub`	无需安装即可运行（如npx）	Claude Code内部用于启动MCP服务器

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

你能做什么

对每个人

问这个	ArchFlow做这个
“冲刺进展如何？”	从Jira中提取活动冲刺，按状态分组，显示完成百分比
“查找Redis的所有信息”	一次搜索Jira问题+GitHub代码+图表节点
“什么连接到认证服务？”	解析Draw.io图，显示入站/出站连接

面向开发者

问这个	ArchFlow做这个
“KAN-42的代码在哪里？”	追踪Jira问题→ GitHub PR→ 代码文件→ 架构节点
“显示用于身份验证的打开PR”	按关键字、分支或链接的Jira键搜索GitHub PR
“团队本周发布了什么？”	将提交、PR和Jira转换聚合到一个报告中

经理/新成员

问这个	ArchFlow做这个
“每周团队报告”	跨源活动：谁做了什么，移动了什么，阻止了什么
“我刚加入——给我背景”	Sprint概述+架构+回购结构+关键问题
“授权史诗有多远？”	完成率为%的史诗级儿童，按状态细分

Slash命令

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

命令	它的作用
`/archflow-status`	Sprint进度、问题状态、组件完成情况
`/archflow-trace`	问题→ PR → code → 架构跟踪
`/archflow-arch`	架构图查询和连接
`/archflow-onboard`	新团队成员的完整项目背景
`/archflow-report`	每周团队活动报告
`/archflow-search`	跨所有来源的统一搜索

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

MCP工具（23）

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

组	计数	工具
Jira	7	`get_issue`, `sprint_status`, `search`, `user_workload`, `component_status`, `recent_activity`, `epic_progress`
GitHub	6	`get_pr`, `list_prs`, `pr_for_issue`, `recent_commits`, `search_code`, `repo_overview`
Draw.io	4	`list_diagrams`, `get_diagram`, `search_nodes`, `node_connections`
交叉来源	5	`trace_issue`, `trace_component`, `project_overview`, `team_activity`, `onboarding_context`
搜索	1	`search` （所有来源统一）

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

来源要求

工具组	Jira	GitHub	Draw.io
Jira工具	必需	—	—
GitHub工具	--	必需	—
Draw.io工具	--	--	必需
交叉来源	必需	可选	可选
统一搜索	可选	可选	可选项

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

配置

配置文件

由...生成 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)

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

GitHub Personal Access Token (2 min, optional)

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

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

谷歌云控制台 → 创建/选择项目
API和服务>库 → 启用 Google Drive API
凭证 → 创建 OAuth客户端ID （桌面应用程序）
复制 客户端ID 和 客户端密钥
通过获取刷新令牌 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

问题	解决方案
克劳德代码中未显示服务器	运行 `archflow init` 再次，然后重新启动Claude Code
“Jira未配置”	检查Jira环境变量--运行 `archflow init` 再一次
“GitHub未配置”	添加 `GITHUB_PERSONAL_ACCESS_TOKEN` --奔跑 `archflow init` 再一次
未找到Draw.io文件	检查 `folder_id` 在配置+所有3个谷歌环境变量
陈旧数据	重新启动克劳德代码（清除30分钟缓存）
GitHub速率限制	等一下——结果会自动缓存

贡献

项目结构

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/

承诺公约

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

许可证

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